openpgp-notes/book/source/adv/signatures.md

<!--
SPDX-FileCopyrightText: 2023 The "Notes on OpenPGP" project
SPDX-License-Identifier: CC-BY-SA-4.0
-->

# Advanced material: Signatures

(notation-signature-subpackets)=
## Notation signature subpackets

[Notation signature subpackets](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#notation-data) can be used to effectively extend the otherwise limited set of {term}`signature subpacket types<OpenPGP Signature Subpacket Type>` in OpenPGP with user-defined {term}`notations<Notation>`. {term}`Issuers<Issuer>` can use these {term}`notations<Notation>` to add name-value pairs to an {term}`OpenPGP signature<OpenPGP Signature Packet>`.

{term}`Notation` names - strings encoded in UTF-8 - may reside in the "user namespace." This namespace is characterized by a {term}`notation tag`, followed by a DNS domain name, both in UTF-8 format.

{term}`Notations<Notation>`, as described earlier, allow for user-defined extensions to the {term}`OpenPGP signature subpacket types<OpenPGP Signature Subpacket Type>`. A practical and popular application of this functionality is seen in Keyoxide, a decentralized {term}`identity verification` service. Keyoxide uses {term}`notations<Notation>` in the `ariadne.id` namespace. For the details of this {term}`implementation<OpenPGP Implementation>`, refer to the [Keyoxide documentation](https://docs.keyoxide.org/wiki/ariadne-identity/).

## Choosing the hash algorithm for a signature

A central element of signature packets is the hash digest of the input data. OpenPGP software typically supports a variety of hash mechanisms. This ability to choose from multiple options is part of what makes OpenPGP flexible in its cryptography, a feature known as *cryptographic agility*. The chosen mechanism is then used to calculate the hash digest.

Different hash mechanisms offer different trade-offs:

- *Hash digest size*: The size of the hash digest is a crucial consideration. Generally, a larger hash size is more robust against cryptanalysis. Hash digests are relatively small – typically ranging in size from 32 to 64 bytes. However, in some cases - especially where messages are transmitted over bandwidth-limited networks - larger hash sizes may unacceptably increase message size.
- *Computational cost*: Different hash algorithms have different computational costs. Where computing environments are constrained, for example, some OpenPGP users may prefer to limit this cost.

Choosing the hash algorithm is not arbitrary but is guided by specific preferences associated with the OpenPGP certificates involved. The following sections discuss how these preferences influence which hash algorithm is chosen.

### General signature context, local algorithm choice

In many instances, the creation of a signature is not intended for a specific individual or entity. Instead, these signatures are designed to be valid for any recipient who might encounter them.

Take, for example, the self-signatures that are part of a certificate. These are intended for a wide audience — essentially, anyone who might interact with the certificate. Another example is the data signatures used for software packages. These signatures are not for a single recipient but for any user or system that verifies the signature, potentially spanning years.

In such cases, where there isn't a specific recipient in mind, the issuer of the signature has the freedom to select the hash algorithm. This choice is made based on the issuer's own criteria or requirements, independent of any third party.

### Specific signature context, recipient-driven choice

When a message is being prepared for a particular recipient, the selection of the hash algorithm for the signature packet should be guided by [the recipient's hash algorithm preference](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-hash-algorithm-preferences).

The recipient's hash algorithm preference is defined in the metadata of their OpenPGP certificate. See {ref}`preferences-features` for more details.

In this workflow, the signed hash digest is created with a hash algorithm representing the intersection of the recipient's preferences and the sender's capabilities and preferences.

## Signature versions

As described in the [RFC](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-packet-type-id-2), the version of a generated signature packet must conform to the version of the key that issues the signature.

That is:

- OpenPGP version 6 keys must generate version 6 signature packets
- OpenPGP version 4 keys must generate version 4 signature packets

Note that some historical version 3 signature packets may still be relevant for applications that handle old OpenPGP data[^sig-v3]. These version 3 signature packets will have been generated by version 4 keys.

[sig-v3]Version 4 signature packets were introduced in [RFC 2440](https://datatracker.ietf.org/doc/html/rfc2440#section-5.2) in 1998, which specifies that applications SHOULD generate v4 signature, however generation of v3 signature packets has remained allowed through [RFC 4880](https://www.rfc-editor.org/rfc/rfc4880.html#section-5.2).