Merge branch 'RM-5019' into 'master'

RM-5019: lib: add method to load keys from smart-card with pre-saved pin

See merge request cdoc2/cdoc2-java-ref-impl!112

Author: Olesja Aarma

cdoc2-lib/README.md

@@ -279,20 +279,32 @@ with `cdoc2-lib` verify that you can access id-card with [DigiDoc4](https://gith
         Path destDir = Paths.get("/tmp");
         Integer slot = 0;
         String alias = "Isikutuvastus";
-        DecryptionKeyMaterial dkm = DecryptionKeyMaterial.fromKeyPair(
-            Pkcs11Tools.loadFromPKCS11Interactively(
-                "/usr/lib/x86_64-linux-gnu/opensc-pkcs11.so", // pkcs11 driver location, differs on different platforms 
-                slot, 
-                alias
-            )
+
+        // load keys by asking pin code interactively
+        KeyPair keyPair = Pkcs11Tools.loadFromPKCS11Interactively(
+            "/usr/lib/x86_64-linux-gnu/opensc-pkcs11.so", // pkcs11 driver location, differs on different platforms 
+            slot, 
+            alias
         );
 
+        // or load keys with a given pin code
+        char[] pin;
+        KeyPair keyPair = Pkcs11Tools.loadFromPKCS11WithPin(
+                 "/usr/lib/x86_64-linux-gnu/opensc-pkcs11.so", // pkcs11 driver location, differs on different platforms 
+                 slot,
+                 new PasswordProtection(pin),
+                 alias
+        );
+
+        DecryptionKeyMaterial dkm = DecryptionKeyMaterial.fromKeyPair(keyPair);
+        
         List<String> extractedFiles = new CDocDecrypter()
-                .withCDoc(cdoc2FileToDecrypt.toFile())
-                .withRecipient(dkm)
-                .withDestinationDirectory(destDir.toFile())
-                .decrypt();
+             .withCDoc(cdoc2FileToDecrypt.toFile())
+             .withRecipient(dkm)
+             .withDestinationDirectory(destDir.toFile())
+             .decrypt();
 ```
+
 `/usr/lib/x86_64-linux-gnu/opensc-pkcs11.so` is location of OpenSC pkcs11 driver library. Some info
 on setting up pcks11 on Ubuntu can be found in [pkcs11.README](https://github.com/open-eid/cdoc2-java-ref-impl/blob/master/cdoc2-lib/pkcs11.README)
 
@@ -379,8 +391,6 @@ Similar to previous example, to decrypt cdoc2 with server recipient,
 [cdoc2-capsule-server](https://github.com/open-eid/cdoc2-capsule-server)client needs to be configured.
 
 ```java
-
-
 Path cdoc2FileToDecrypt = Paths.get("/tmp/second.cdoc2");
 Path destDir = Paths.get("/tmp");
 Integer slot = 0;

cdoc2-lib/src/main/java/ee/cyber/cdoc2/crypto/Pkcs11Tools.java

@@ -62,7 +62,7 @@ private Pkcs11Tools() {
      *
      * @param pkcs11LibPath pkcs11 provider library location, defaults described above if null
      * @param slot          the slot number with the keys
-     * @param keyAlias      key alias (optional) to use in case the are more than one entry in the
+     * @param keyAlias      key alias (optional) to use in case there are more than one entry in the
      *                      keystore
      * @return KeyPair
      *
@@ -88,6 +88,34 @@ public static KeyPair loadFromPKCS11Interactively(String pkcs11LibPath, Integer
         return new KeyPair(entry.getValue().getPublicKey(), entry.getKey());
     }
 
+    /**
+     * Load KeyPair using automatically generated SunPKCS11 configuration with given pin code.
+     *
+     * @param pkcs11LibPath pkcs11 provider library location, defaults described above if null
+     * @param slot          the slot number with the keys
+     * @param pin           pin code wrapped into PasswordProtection object
+     * @param keyAlias      key alias (optional) to use in case there are more than one entry in the
+     *                      keystore
+     * @return KeyPair
+     *
+     * @see <a href="https://docs.oracle.com/en/java/javase/17/security/pkcs11-reference-guide1.html">
+     *     SunPKCS11 documentation Table 5-1</a>
+     */
+    public static KeyPair loadFromPKCS11WithPin(
+        String pkcs11LibPath,
+        Integer slot,
+        KeyStore.PasswordProtection pin,
+        @Nullable String keyAlias
+    ) throws GeneralSecurityException, IOException {
+        var entry = loadFromPKCS11(
+            Pkcs11Tools.createSunPkcsConfigurationFile(null, pkcs11LibPath, slot),
+            pin,
+            keyAlias
+        );
+
+        return new KeyPair(entry.getValue().getPublicKey(), entry.getKey());
+    }
+
     /**
      * Init OpenSC based KeyStore (like EST-EID). OpenSC must be installed. Creates configuration file for SunPKCS11,
      * configures SunPkcs11 Provider and loads and configures PKCS11 KeyStore from SunPkcs11 Provider.