#1792 Add documentation to PGPSignature

Author: gefeili

pg/src/main/java/org/bouncycastle/openpgp/PGPSignature.java

@@ -34,22 +34,161 @@
 public class PGPSignature
     extends PGPDefaultSignatureGenerator
 {
+    /**
+     * The signature is made over some binary data.
+     * No preprocessing is applied.
+     * <br>
+     * This signature type is used to create data signatures.
+     *
+     * @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-binary-signature-type-id-0x">
+     *     RFC9580 - Binary Signature of a Document</a>
+     */
     public static final int BINARY_DOCUMENT = 0x00;
+
+    /**
+     * The signature is made over text data.
+     * In a preprocessing step, the text data is canonicalized (line endings may be altered).
+     * <br>
+     * This signature type is used to create data signatures.
+     *
+     * @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-text-signature-type-id-0x01">
+     *     RFC9580 - Text Signature of a Canonical Document</a>
+     */
     public static final int CANONICAL_TEXT_DOCUMENT = 0x01;
+
+    /**
+     * The signature is made only over its own signature subpackets.
+     *
+     * @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-standalone-signature-type-i">
+     *     RFC9580 - Standalone Signature</a>
+     */
     public static final int STAND_ALONE = 0x02;
 
+    /**
+     * Generic certification over a user-id or user-attribute.
+     * The issuer of a generic certification does not make any claims as to what extent they checked
+     * the authenticity of the identity claim.
+     * <br>
+     * This signature type is used to bind user information to primary keys, or to certify the identity claim
+     * of a third party.
+     *
+     * @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-generic-certification-signa">
+     *     RFC9580 - Generic Certification Signature of a User ID and Public Key Packet</a>
+     */
     public static final int DEFAULT_CERTIFICATION = 0x10;
+
+    /**
+     * Persona certification over a user-id or user-attribute.
+     * The issuer of a persona certification did explicitly not check the authenticity of the identity claim.
+     * <br>
+     * This signature type is used to bind user information to primary keys, or to certify the identity claim
+     * of a third party.
+     *
+     * @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-persona-certification-signa">
+     *     RFC9580 - Persona Certification Signature of a User ID and Public Key Packet</a>
+     */
     public static final int NO_CERTIFICATION = 0x11;
+
+    /**
+     * Casual certification over a user-id or user-attribute.
+     * The issuer of a casual certification did some casual verification to check the authenticity of the
+     * identity claim.
+     * <br>
+     * This signature type is used to bind user information to primary keys, or to certify the identity claim
+     * of a third party.
+     *
+     * @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-casual-certification-signat">
+     *     RFC9580 - Casual Certification of a User ID an Public Key Packet</a>
+     */
     public static final int CASUAL_CERTIFICATION = 0x12;
+
+    /**
+     * Positive certification over a user-id or user-attribute.
+     * The issuer of a positive certification did extensive effort to check the authenticity of the identity claim.
+     * <br>
+     * This signature type is used to bind user information to primary keys, or to certify the identity claim
+     * of a third party.
+     *
+     * @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-positive-certification-sign">
+     *     RFC9580 - Positive Certification Signature of a User ID and Public Key Packet</a>
+     */
     public static final int POSITIVE_CERTIFICATION = 0x13;
 
+    /**
+     * Subkey Binding Signature to bind a subkey to a primary key.
+     * This signature type is used to bind a subkey to the primary key of a certificate.
+     *
+     * @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-subkey-binding-signature-ty">
+     *     RFC9580 - Subkey Binding Signature</a>
+     */
     public static final int SUBKEY_BINDING = 0x18;
+
+    /**
+     * Primary-Key Binding Signature to bind a signing-capable subkey to a primary key.
+     * This (back-) signature is used as an embedded signature in a {@link #SUBKEY_BINDING} signature and acts as
+     * a claim by the subkey, stating that it is in fact a subkey of the primary key.
+     *
+     * @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-primary-key-binding-signatu">
+     *     RFC9580 - Primary Key Binding Signature</a>
+     */
     public static final int PRIMARYKEY_BINDING = 0x19;
+
+    /**
+     * The signature is made directly over a primary key.
+     * If issued as a self-signature, its contents apply to the whole certificate, meaning this signature
+     * is appropriate to set algorithm preferences which also apply to its subkeys.
+     * Issued as a signature over a third-party certificate, it can be used to mark said certificate as a CA.
+     *
+     * @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-direct-key-signature-type-i">
+     *     RFC9580 - Direct Key Signature</a>
+     */
     public static final int DIRECT_KEY = 0x1f;
+
+    /**
+     * The signature is used to revoke a primary key (and in turn the whole certificate with all its subkeys).
+     *
+     * @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-key-revocation-signature-ty">
+     *     RFC9580 - Key Revocation Signature</a>
+     */
     public static final int KEY_REVOCATION = 0x20;
+
+    /**
+     * The signature is used to revoke the binding of a particular subkey.
+     *
+     * @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-subkey-revocation-signature">
+     *     RFC9580 - Subkey Revocation Signature</a>
+     */
     public static final int SUBKEY_REVOCATION = 0x28;
+
+    /**
+     * The signature is used to revoke a user-id certification signature
+     * ({@link #DEFAULT_CERTIFICATION}, {@link #NO_CERTIFICATION}, {@link #CASUAL_CERTIFICATION},
+     * {@link #POSITIVE_CERTIFICATION}) or {@link #DIRECT_KEY} signature.
+     * Issued as a self-signature, it can be used to revoke an identity claim.
+     * Issued over a third-party certificate, it revokes the attestation of the third-party's claim.
+     *
+     * @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-certification-revocation-si">
+     *     RFC9580 - Certification Revocation Signature</a>
+     */
     public static final int CERTIFICATION_REVOCATION = 0x30;
+
+    /**
+     * The signature is only meaningful for the timestamp contained in it.
+     *
+     * @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-timestamp-signature-type-id">
+     *     RFC9580 - Timestamp Signature</a>
+     */
     public static final int TIMESTAMP = 0x40;
+
+    /**
+     * This signature is issued over another signature and can act as an attestation of that signature.
+     * This concept can be used to "approve" third-party certifications over the own key, allowing
+     * third-party certifications to be published on key-servers that usually strip such signatures
+     * to prevent certificate flooding.
+     *
+     * @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-third-party-confirmation-si">
+     *     RFC9580 - Third-Party Confirmation Signature/a>
+     */
     public static final int THIRD_PARTY_CONFIRMATION = 0x50;
 
     private final SignaturePacket sigPck;
@@ -67,6 +206,12 @@ private static SignaturePacket cast(Packet packet)
         return (SignaturePacket)packet;
     }
 
+    /**
+     * Parse a {@link PGPSignature} from an OpenPGP packet input stream.
+     * @param pIn packet input stream
+     * @throws IOException
+     * @throws PGPException
+     */
     public PGPSignature(
         BCPGInputStream pIn)
         throws IOException, PGPException
@@ -149,6 +294,13 @@ public boolean isCertification()
         return isCertification(getSignatureType());
     }
 
+    /**
+     * Initialize the signature for verification.
+     *
+     * @param verifierBuilderProvider provide the implementation for signature verification
+     * @param pubKey issuer public key
+     * @throws PGPException
+     */
     public void init(PGPContentVerifierBuilderProvider verifierBuilderProvider, PGPPublicKey pubKey)
         throws PGPException
     {
@@ -202,6 +354,14 @@ private void updateWithSalt()
         }
     }
 
+    /**
+     * Finish the verification and return true if the signature is "correct".
+     * Note: The fact that this method returned <pre>true</pre> does not yet mean that the signature is valid.
+     * A correct signature may very well be expired, the issuer key may be revoked, etc.
+     * All these constraints are not checked by this method.
+     * @return true if the signature is correct
+     * @throws PGPException
+     */
     public boolean verify()
         throws PGPException
     {
@@ -414,6 +574,13 @@ boolean doVerifyCertification(
         return verifier.verify(this.getSignature());
     }
 
+    /**
+     * Return the type id of the signature.
+     * @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-signature-types">
+     *     RFC9580 - Signature Types</a>
+     *
+     * @return type id
+     */
     public int getSignatureType()
     {
         return sigPck.getSignatureType();
@@ -454,11 +621,28 @@ public boolean hasSubpackets()
         return sigPck.getHashedSubPackets() != null || sigPck.getUnhashedSubPackets() != null;
     }
 
+    /**
+     * Return the hashed subpackets of the signature.
+     * Hashed signature subpackets are covered by the signature.
+     *
+     * @return hashed signature subpackets
+     */
     public PGPSignatureSubpacketVector getHashedSubPackets()
     {
         return createSubpacketVector(sigPck.getHashedSubPackets());
     }
 
+    /**
+     * Return the unhashed subpackets of the signature.
+     * As unhashed signature subpackets are NOT covered by the signature, an attacker might inject false
+     * information after the fact, therefore only "self-authenticating" information from this area can
+     * be trusted.
+     * Self-authenticating information are for example the {@link org.bouncycastle.bcpg.sig.IssuerKeyID}
+     * or {@link org.bouncycastle.bcpg.sig.IssuerFingerprint}, whose authenticity can be confirmed by
+     * verifying the signature using the declared key.
+     *
+     * @return unhashed signature subpackets
+     */
     public PGPSignatureSubpacketVector getUnhashedSubPackets()
     {
         return createSubpacketVector(sigPck.getUnhashedSubPackets());
@@ -474,11 +658,21 @@ private PGPSignatureSubpacketVector createSubpacketVector(SignatureSubpacket[] p
         return null;
     }
 
+    /**
+     * Return the salt of a v6 signature.
+     * @return salt
+     */
     byte[] getSalt()
     {
         return sigPck.getSalt();
     }
 
+    /**
+     * Return the cryptographic raw signature contained in the OpenPGP signature packet.
+     * The value is dependent on the signing algorithm.
+     * @return cryptographic signature
+     * @throws PGPException
+     */
     public byte[] getSignature()
         throws PGPException
     {
@@ -532,6 +726,11 @@ else if (getKeyAlgorithm() == PublicKeyAlgorithmTags.EDDSA_LEGACY)
         return signature;
     }
 
+    /**
+     * Return the OpenPGP packet encoding of the signature.
+     * @return OpenPGP packet encoding
+     * @throws IOException
+     */
     public byte[] getEncoded()
         throws IOException
     {
@@ -559,6 +758,12 @@ public byte[] getEncoded(boolean forTransfer)
         return bOut.toByteArray();
     }
 
+    /**
+     * Encode the signature to an OpenPGP packet stream.
+     * This method does not strip out any trust packets.
+     * @param outStream packet stream
+     * @throws IOException
+     */
     public void encode(
         OutputStream outStream)
         throws IOException
@@ -607,11 +812,28 @@ public static boolean isCertification(int signatureType)
             || PGPSignature.POSITIVE_CERTIFICATION == signatureType;
     }
 
+    /**
+     * Return true, if the cryptographic signature encoding of the two signatures match.
+     * @param sig1 first signature
+     * @param sig2 second signature
+     * @return true if both signatures contain the same cryptographic signature
+     */
     public static boolean isSignatureEncodingEqual(PGPSignature sig1, PGPSignature sig2)
     {
         return Arrays.areEqual(sig1.sigPck.getSignatureBytes(), sig2.sigPck.getSignatureBytes());
     }
 
+    /**
+     * Join two copies of the same signature.
+     * As an entity might append additional information to an existing signatures unhashed subpacket area
+     * (e.g. an embedded {@link #THIRD_PARTY_CONFIRMATION} signature), an implementation might want to
+     * join an existing instance of a signature with an updated copy, e.g. retrieved from a key server.
+     * This method merges both signature instances by joining unhashed subpackets.
+     * @param sig1 first signature
+     * @param sig2 second signature
+     * @return merged signature
+     * @throws PGPException
+     */
     public static PGPSignature join(PGPSignature sig1, PGPSignature sig2)
         throws PGPException
     {