From c8d77d994f578770859ad222be4a34cab848cd3b Mon Sep 17 00:00:00 2001
From: Lukas Burkhalter <lukas.burkhalter@proton.ch>
Date: Fri, 24 Nov 2023 09:45:04 +0100
Subject: [PATCH] docs(v2): Improve documentation in signatures for keys

---
 openpgp/packet/public_key.go | 29 ++++++++---------------------
 openpgp/v2/subkeys.go        |  1 +
 openpgp/v2/user.go           |  2 ++
 3 files changed, 11 insertions(+), 21 deletions(-)

diff --git a/openpgp/packet/public_key.go b/openpgp/packet/public_key.go
index 159108bd0..dd93c9870 100644
--- a/openpgp/packet/public_key.go
+++ b/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 {
diff --git a/openpgp/v2/subkeys.go b/openpgp/v2/subkeys.go
index 7ef007f21..c3063ccb2 100644
--- a/openpgp/v2/subkeys.go
+++ b/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 {
diff --git a/openpgp/v2/user.go b/openpgp/v2/user.go
index 2b85f2b1f..1b075eb22 100644
--- a/openpgp/v2/user.go
+++ b/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 {