test: add examples for detached payload

example_test.go

@@ -78,6 +78,77 @@ func ExampleSignMessage() {
 	// verification error as expected
 }
 
+// This example demonstrates signing and verifying COSE_Sign signatures with
+// detached payload.
+//
+// The COSE Sign API is EXPERIMENTAL and may be changed or removed in a later
+// release.
+func ExampleSignMessage_detachedPayload() {
+	// create a signature holder
+	sigHolder := cose.NewSignature()
+	sigHolder.Headers.Protected.SetAlgorithm(cose.AlgorithmES512)
+	sigHolder.Headers.Unprotected[cose.HeaderLabelKeyID] = []byte("1")
+
+	// create message to be signed
+	msgToSign := cose.NewSignMessage()
+	msgToSign.Payload = []byte("hello world")
+	msgToSign.Signatures = append(msgToSign.Signatures, sigHolder)
+
+	// create a signer
+	privateKey, err := ecdsa.GenerateKey(elliptic.P521(), rand.Reader)
+	if err != nil {
+		panic(err)
+	}
+	signer, err := cose.NewSigner(cose.AlgorithmES512, privateKey)
+	if err != nil {
+		panic(err)
+	}
+
+	// sign message
+	err = msgToSign.Sign(rand.Reader, nil, signer)
+	if err != nil {
+		panic(err)
+	}
+	msgToSign.Payload = nil // detach payload
+	sig, err := msgToSign.MarshalCBOR()
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println("message signed")
+
+	// create a verifier from a trusted public key
+	publicKey := privateKey.Public()
+	verifier, err := cose.NewVerifier(cose.AlgorithmES512, publicKey)
+	if err != nil {
+		panic(err)
+	}
+
+	// verify message
+	var msgToVerify cose.SignMessage
+	err = msgToVerify.UnmarshalCBOR(sig)
+	if err != nil {
+		panic(err)
+	}
+	msgToVerify.Payload = []byte("hello world") // reattach payload
+	err = msgToVerify.Verify(nil, verifier)
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println("message verified")
+
+	// tamper the message and verification should fail
+	msgToVerify.Payload = []byte("foobar")
+	err = msgToVerify.Verify(nil, verifier)
+	if err != cose.ErrVerification {
+		panic(err)
+	}
+	fmt.Println("verification error as expected")
+	// Output:
+	// message signed
+	// message verified
+	// verification error as expected
+}
+
 // This example demonstrates signing and verifying COSE_Sign1 signatures.
 func ExampleSign1Message() {
 	// create message to be signed
@@ -139,6 +210,70 @@ func ExampleSign1Message() {
 	// verification error as expected
 }
 
+// This example demonstrates signing and verifying COSE_Sign1 signatures with
+// detached payload.
+func ExampleSign1Message_detachedPayload() {
+	// create message to be signed
+	msgToSign := cose.NewSign1Message()
+	msgToSign.Payload = []byte("hello world")
+	msgToSign.Headers.Protected.SetAlgorithm(cose.AlgorithmES512)
+	msgToSign.Headers.Unprotected[cose.HeaderLabelKeyID] = []byte("1")
+
+	// create a signer
+	privateKey, err := ecdsa.GenerateKey(elliptic.P521(), rand.Reader)
+	if err != nil {
+		panic(err)
+	}
+	signer, err := cose.NewSigner(cose.AlgorithmES512, privateKey)
+	if err != nil {
+		panic(err)
+	}
+
+	// sign message
+	err = msgToSign.Sign(rand.Reader, nil, signer)
+	if err != nil {
+		panic(err)
+	}
+	msgToSign.Payload = nil // detach payload
+	sig, err := msgToSign.MarshalCBOR()
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println("message signed")
+
+	// create a verifier from a trusted public key
+	publicKey := privateKey.Public()
+	verifier, err := cose.NewVerifier(cose.AlgorithmES512, publicKey)
+	if err != nil {
+		panic(err)
+	}
+
+	// verify message
+	var msgToVerify cose.Sign1Message
+	err = msgToVerify.UnmarshalCBOR(sig)
+	if err != nil {
+		panic(err)
+	}
+	msgToVerify.Payload = []byte("hello world") // reattach payload
+	err = msgToVerify.Verify(nil, verifier)
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println("message verified")
+
+	// tamper the message and verification should fail
+	msgToVerify.Payload = []byte("foobar")
+	err = msgToVerify.Verify(nil, verifier)
+	if err != cose.ErrVerification {
+		panic(err)
+	}
+	fmt.Println("verification error as expected")
+	// Output:
+	// message signed
+	// message verified
+	// verification error as expected
+}
+
 // This example demonstrates signing COSE_Sign1_Tagged signatures using Sign1().
 func ExampleSign1() {
 	// create a signer