PKCS12Util: add some much-needed comments

Part of: https://pagure.io/dogtagpki/issue/2610

Change-Id: Ic35a81c4c4dd49622bfdeb677d588641594b7ec6
(cherry picked from commit 507908d1aac8f9db6c380f5cae634521608043e8)

2 files changed, 36 insertions, 0 deletions

diff --git a/base/util/src/netscape/security/pkcs/PKCS12KeyInfo.java b/base/util/src/netscape/security/pkcs/PKCS12KeyInfo.java
index f180cf23b..ddcc3dbbc 100644
--- a/base/util/src/netscape/security/pkcs/PKCS12KeyInfo.java
+++ b/base/util/src/netscape/security/pkcs/PKCS12KeyInfo.java
@@ -21,6 +21,17 @@ import java.math.BigInteger;
 
 import org.mozilla.jss.crypto.PrivateKey;
 
+/**
+ * This object is used for carrying key info around.
+ *
+ * It does not handle raw key material (but it used to).
+ *
+ * FIXME: A clear refactoring opportunity exists.  The 'privateKey'
+ * field (and associated constructor) is only used during export,
+ * and the 'epkiBytes' field (and associated constructor) is only
+ * used during import.  Therefore this should be two different
+ * types.
+ */
 public class PKCS12KeyInfo {
 
     private PrivateKey privateKey;
@@ -31,10 +42,18 @@ public class PKCS12KeyInfo {
     public PKCS12KeyInfo() {
     }
 
+    /**
+     * Construct with a PrivateKey.  This constructor is used
+     * for moving the PrivateKey handle around during export.
+     */
     public PKCS12KeyInfo(PrivateKey k) {
         this.privateKey = k;
     }
 
+    /** Construct with a (serialised) EncrypedPrivateKeyInfo.  This
+     * constructor is used for moving the EPKI data around during
+     * import.
+     */
     public PKCS12KeyInfo(byte[] epkiBytes) {
         this.epkiBytes = epkiBytes;
     }
diff --git a/base/util/src/netscape/security/pkcs/PKCS12Util.java b/base/util/src/netscape/security/pkcs/PKCS12Util.java
index 9f9a35e16..31c712691 100644
--- a/base/util/src/netscape/security/pkcs/PKCS12Util.java
+++ b/base/util/src/netscape/security/pkcs/PKCS12Util.java
@@ -102,6 +102,14 @@ public class PKCS12Util {
         icert.setObjectSigningTrust(PKCS12.decodeFlags(flags[2]));
     }
 
+    /**
+     * Used during EXPORT to add a private key to the PKCS12.
+     *
+     * The private key is exported directly from the token, into
+     * an EncryptedPrivateKeyInfo value, then added as a
+     * "Shrouded Key Bag" to the PKCS #12 object.  Unencrypted
+     * key material is never seen.
+     */
     public void addKeyBag(PKCS12KeyInfo keyInfo, Password password,
             SEQUENCE encSafeContents) throws Exception {
         PrivateKey k = keyInfo.getPrivateKey();
@@ -346,6 +354,12 @@ public class PKCS12Util {
         }
     }
 
+    /**
+     * Loads key bags (for IMPORT and other operations on existing
+     * PKCS #12 files).  Does not decrypt EncryptedPrivateKeyInfo
+     * values, but stores them in PKCS12KeyInfo objects for possible
+     * later use.
+     */
     public PKCS12KeyInfo getKeyInfo(SafeBag bag, Password password) throws Exception {
 
         PKCS12KeyInfo keyInfo = new PKCS12KeyInfo(bag.getBagContent().getEncoded());
@@ -598,6 +612,9 @@ public class PKCS12Util {
         }
     }
 
+    /**
+     * Store a certificate (and key, if present) in NSSDB.
+     */
     public void storeCertIntoNSS(
             PKCS12 pkcs12, Password password,
             PKCS12CertInfo certInfo, boolean overwrite)