docs(v2): Improve documentation in signatures for keys

Author: lubux

openpgp/packet/public_key.go

@@ -874,13 +874,8 @@ func (pk *PublicKey) VerifyKeySignature(signed *PublicKey, sig *Signature) error
 	return nil
 }
 
-func keyRevocationHash(pk signingKey, hashFunc hash.Hash) (h hash.Hash, err error) {
-	h = hashFunc
-
-	// RFC 4880, section 5.2.4
-	err = pk.SerializeForHash(h)
-
-	return
+func keyRevocationHash(pk signingKey, hashFunc hash.Hash) (err error) {
+	return pk.SerializeForHash(hashFunc)
 }
 
 // VerifyRevocationSignature returns nil iff sig is a valid signature, made by this
@@ -890,11 +885,10 @@ func (pk *PublicKey) VerifyRevocationSignature(sig *Signature) (err error) {
 	if err != nil {
 		return err
 	}
-	h, err := keyRevocationHash(pk, preparedHash)
-	if err != nil {
+	if keyRevocationHash(pk, preparedHash); err != nil {
 		return err
 	}
-	return pk.VerifySignature(h, sig)
+	return pk.VerifySignature(preparedHash, sig)
 }
 
 // VerifySubkeyRevocationSignature returns nil iff sig is a valid subkey revocation signature,
@@ -935,16 +929,9 @@ func userIdSignatureHash(id string, pk *PublicKey, h hash.Hash) (err error) {
 	return nil
 }
 
-// directSignatureHash returns a Hash of the message that needs to be signed
+// directKeySignatureHash returns a Hash of the message that needs to be signed.
 func directKeySignatureHash(pk *PublicKey, h hash.Hash) (err error) {
-	// RFC 4880, section 5.2.4
-	if err := pk.SerializeSignaturePrefix(h); err != nil {
-		return err
-	}
-	if err := pk.serializeWithoutHeaders(h); err != nil {
-		return err
-	}
-	return nil
+	return pk.SerializeForHash(h)
 }
 
 // VerifyUserIdSignature returns nil iff sig is a valid signature, made by this
@@ -960,8 +947,8 @@ func (pk *PublicKey) VerifyUserIdSignature(id string, pub *PublicKey, sig *Signa
 	return pk.VerifySignature(h, sig)
 }
 
-// VerifyUserIdSignature returns nil iff sig is a valid signature, made by this
-// public key
+// VerifyDirectKeySignature returns nil iff sig is a valid signature, made by this
+// public key.
 func (pk *PublicKey) VerifyDirectKeySignature(sig *Signature) (err error) {
 	h, err := sig.PrepareVerify()
 	if err != nil {

openpgp/packet/signature.go

@@ -1019,11 +1019,10 @@ func (sig *Signature) RevokeKey(pub *PublicKey, priv *PrivateKey, config *Config
 	if err != nil {
 		return err
 	}
-	h, err := keyRevocationHash(pub, prepareHash)
-	if err != nil {
+	if err := keyRevocationHash(pub, prepareHash); err != nil {
 		return err
 	}
-	return sig.Sign(h, priv, config)
+	return sig.Sign(prepareHash, priv, config)
 }
 
 // RevokeSubkey computes a subkey revocation signature of pub using priv.

openpgp/v2/subkeys.go

@@ -79,6 +79,7 @@ func (s *Subkey) Serialize(w io.Writer, includeSecrets bool) error {
 	return nil
 }
 
+// ReSign resigns the latest valid subkey binding signature with the given config.
 func (s *Subkey) ReSign(config *packet.Config) error {
 	selectedSig, err := s.LatestValidBindingSignature(time.Time{})
 	if err != nil {

openpgp/v2/user.go

@@ -71,6 +71,7 @@ func readUser(e *Entity, packets *packet.Reader, pkt *packet.UserId) error {
 	return nil
 }
 
+// Serialize serializes the user id to the writer.
 func (i *Identity) Serialize(w io.Writer) error {
 	if err := i.UserId.Serialize(w); err != nil {
 		return err
@@ -135,6 +136,7 @@ func (i *Identity) Revoked(selfCertification *packet.Signature, date time.Time)
 	return false
 }
 
+// ReSign resigns the latest valid self-certification with the given config.
 func (i *Identity) ReSign(config *packet.Config) error {
 	selectedSig, err := i.LatestValidSelfCertification(config.Now())
 	if err != nil {