Rename and document members of SubkeyIdentifier

pgpainless-core/src/main/kotlin/org/pgpainless/key/SubkeyIdentifier.kt

@@ -11,59 +11,135 @@ import org.bouncycastle.openpgp.api.OpenPGPCertificate.OpenPGPComponentKey
 import org.bouncycastle.openpgp.api.OpenPGPKey.OpenPGPPrivateKey
 
 /**
- * Tuple class used to identify a subkey by fingerprints of the primary key of the subkeys key ring,
- * as well as the subkeys fingerprint.
+ * Tuple class used to identify a subkey (component key) by fingerprints of the certificate,
+ * as well as the component keys fingerprint.
  */
 class SubkeyIdentifier(
-    val primaryKeyFingerprint: OpenPgpFingerprint,
-    val subkeyFingerprint: OpenPgpFingerprint
+    val certificateFingerprint: OpenPgpFingerprint,
+    val componentKeyFingerprint: OpenPgpFingerprint
 ) {
 
-    constructor(fingerprint: OpenPgpFingerprint) : this(fingerprint, fingerprint)
+    /**
+     * Constructor for a [SubkeyIdentifier] pointing to the primary key identified by the
+     * [certificateFingerprint].
+     * @param certificateFingerprint primary key fingerprint
+     */
+    constructor(certificateFingerprint: OpenPgpFingerprint) : this(certificateFingerprint, certificateFingerprint)
 
-    constructor(keys: PGPKeyRing) : this(keys.publicKey)
+    /**
+     * Constructor for a [SubkeyIdentifier] pointing to the primary key of the given [PGPKeyRing].
+     *
+     * @param certificate certificate
+     */
+    constructor(certificate: PGPKeyRing) : this(certificate.publicKey)
 
-    constructor(key: PGPPublicKey) : this(OpenPgpFingerprint.of(key))
+    /**
+     * Constructor for a [SubkeyIdentifier] pointing to the given [primaryKey].
+     *
+     * @param primaryKey primary key
+     */
+    constructor(primaryKey: PGPPublicKey) : this(OpenPgpFingerprint.of(primaryKey))
 
-    constructor(keys: PGPKeyRing, keyId: Long) : this(keys, KeyIdentifier(keyId))
+    /**
+     * Constructor for a [SubkeyIdentifier] pointing to a component key (identified by
+     * [componentKeyId]) from the given [certificate].
+     */
+    @Deprecated("Pass in a KeyIdentifier instead of a keyId.")
+    constructor(certificate: PGPKeyRing, componentKeyId: Long) : this(certificate, KeyIdentifier(componentKeyId))
 
+    /**
+     * Constructor for a [SubkeyIdentifier] pointing to the given [componentKey].
+     *
+     * @param componentKey component key
+     */
     constructor(
-        key: OpenPGPComponentKey
+        componentKey: OpenPGPComponentKey
     ) : this(
-        OpenPgpFingerprint.of(key.certificate.pgpPublicKeyRing),
-        OpenPgpFingerprint.of(key.pgpPublicKey))
+        OpenPgpFingerprint.of(componentKey.certificate),
+        OpenPgpFingerprint.of(componentKey))
 
-    constructor(key: OpenPGPPrivateKey) : this(key.secretKey)
+    /**
+     * Constructor for a [SubkeyIdentifier] pointing to the given [componentKey].
+     */
+    constructor(componentKey: OpenPGPPrivateKey) : this(componentKey.secretKey)
 
+    /**
+     * Constructor for a [SubkeyIdentifier] pointing to a component key (identified by
+     * the [componentKeyFingerprint]) of the given [certificate].
+     *
+     * @param certificate certificate
+     * @param componentKeyFingerprint fingerprint of the component key
+     */
     constructor(
-        keys: PGPKeyRing,
-        subkeyFingerprint: OpenPgpFingerprint
-    ) : this(OpenPgpFingerprint.of(keys), subkeyFingerprint)
+        certificate: PGPKeyRing,
+        componentKeyFingerprint: OpenPgpFingerprint
+    ) : this(OpenPgpFingerprint.of(certificate), componentKeyFingerprint)
 
+    /**
+     * Constructor for a [SubkeyIdentifier] pointing to a component key (identified by the
+     * [componentKeyIdentifier]) of the given [certificate].
+     *
+     * @param certificate certificate
+     * @param componentKeyIdentifier identifier of the component key
+     */
     constructor(
-        keys: PGPKeyRing,
-        subkeyIdentifier: KeyIdentifier
+        certificate: PGPKeyRing,
+        componentKeyIdentifier: KeyIdentifier
     ) : this(
-        OpenPgpFingerprint.of(keys),
+        OpenPgpFingerprint.of(certificate),
         OpenPgpFingerprint.of(
-            keys.getPublicKey(subkeyIdentifier)
+            certificate.getPublicKey(componentKeyIdentifier)
                 ?: throw NoSuchElementException(
-                    "OpenPGP key does not contain subkey $subkeyIdentifier")))
+                    "OpenPGP key does not contain subkey $componentKeyIdentifier")))
 
-    val keyIdentifier = KeyIdentifier(subkeyFingerprint.bytes)
-    val subkeyIdentifier = keyIdentifier
-    val primaryKeyIdentifier = KeyIdentifier(primaryKeyFingerprint.bytes)
+    @Deprecated("Use certificateFingerprint instead.",
+        replaceWith = ReplaceWith("certificateFingerprint")
+    )
+    val primaryKeyFingerprint: OpenPgpFingerprint = certificateFingerprint
 
+    @Deprecated("Use componentKeyFingerprint instead.",
+        replaceWith = ReplaceWith("componentKeyFingerprint"))
+    val subkeyFingerprint: OpenPgpFingerprint = componentKeyFingerprint
+
+    /**
+     * [KeyIdentifier] of the component key.
+     */
+    val keyIdentifier = componentKeyFingerprint.keyIdentifier
+
+    /**
+     * [KeyIdentifier] of the component key.
+     */
+    val componentKeyIdentifier = keyIdentifier
+
+    /**
+     * [KeyIdentifier] of the primary key of the certificate the component key belongs to.
+     */
+    val certificateIdentifier = certificateFingerprint.keyIdentifier
+
+    /**
+     * Key-ID of the component key.
+     */
     @Deprecated("Use of key-ids is discouraged.") val keyId = keyIdentifier.keyId
-    val fingerprint = subkeyFingerprint
 
-    @Deprecated("Use of key-ids is discouraged.") val subkeyId = subkeyIdentifier.keyId
-    @Deprecated("Use of key-ids is discouraged.") val primaryKeyId = primaryKeyIdentifier.keyId
+    /**
+     * Fingerprint of the component key.
+     */
+    val fingerprint = componentKeyFingerprint
 
-    val isPrimaryKey = primaryKeyIdentifier == subkeyIdentifier
+    /**
+     * Key-ID of the component key.
+     */
+    @Deprecated("Use of key-ids is discouraged.") val subkeyId = componentKeyIdentifier.keyId
+
+    /**
+     * Key-ID of the primary key of the certificate the component key belongs to.
+     */
+    @Deprecated("Use of key-ids is discouraged.") val primaryKeyId = certificateIdentifier.keyId
+
+    val isPrimaryKey = certificateIdentifier.matches(componentKeyIdentifier)
 
     fun matches(fingerprint: OpenPgpFingerprint) =
-        primaryKeyFingerprint == fingerprint || subkeyFingerprint == fingerprint
+        certificateFingerprint == fingerprint || componentKeyFingerprint == fingerprint
 
     override fun equals(other: Any?): Boolean {
         if (other == null) {
@@ -76,13 +152,13 @@ class SubkeyIdentifier(
             return false
         }
 
-        return primaryKeyFingerprint == other.primaryKeyFingerprint &&
-            subkeyFingerprint == other.subkeyFingerprint
+        return certificateFingerprint == other.certificateFingerprint &&
+            componentKeyFingerprint == other.componentKeyFingerprint
     }
 
     override fun hashCode(): Int {
-        return primaryKeyFingerprint.hashCode() + 31 * subkeyFingerprint.hashCode()
+        return certificateFingerprint.hashCode() + 31 * componentKeyFingerprint.hashCode()
     }
 
-    override fun toString(): String = "$subkeyFingerprint $primaryKeyFingerprint"
+    override fun toString(): String = "$componentKeyFingerprint $certificateFingerprint"
 }

pgpainless-core/src/main/kotlin/org/pgpainless/key/info/KeyRingInfo.kt

@@ -594,7 +594,7 @@ class KeyRingInfo(
         require(publicKey.keyIdentifier.equals(identifier.keyIdentifier)) {
             "Mismatching primary key ID."
         }
-        return getPublicKey(identifier.subkeyIdentifier)
+        return getPublicKey(identifier.componentKeyIdentifier)
     }
 
     /**
@@ -605,7 +605,7 @@ class KeyRingInfo(
      *   key of the key.
      */
     fun getSecretKey(identifier: SubkeyIdentifier): OpenPGPComponentKey? =
-        getSecretKey(identifier.subkeyIdentifier)
+        getSecretKey(identifier.componentKeyIdentifier)
 
     fun isKeyValidlyBound(keyIdentifier: KeyIdentifier): Boolean {
         return isKeyValidlyBound(keyIdentifier.keyId)