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

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

# OpenPGP Signatures

Signatures are perhaps the single most central mechanism in OpenPGP. They act as the syntax that allows forming and interpreting rich statements about certificates and their components, as well as data.

Without signatures, there would only be loose keys, impossible to associate with a certificate, or their owner. Signatures are the glue that allows for components (component keys and identity components) to be assembled into hierarchical certificates, and for messages to gain authenticity.

## Terminology

The term *signature* can have two different meanings in the context of OpenPGP:

- Cryptographic keys create raw signatures which are byte sequences calculated according to some signature scheme.
- [*OpenPGP signature packets*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-packet-type-id-2), which combine a *type* setting, additional metadata, and a raw cryptographic signature.

```{figure} diag/meaning_of_signatures.png

Two meanings of the term "signature" in OpenPGP
```

For the purpose of this document, the term signature will refer to OpenPGP signature packets.

(signature_types)=
## Types of signatures in OpenPGP

The OpenPGP standard defines a set of [Signature Types](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-types), each identified by a numerical *signature type ID*. Signature types define the intent of a signature, and how it needs to be interpreted.

Most OpenPGP signature types can be classified as either:

- *Signatures over data* (type IDs `0x00` and `0x01`), or
- *Signatures on components* (that is: signatures that apply to component keys or identity components).

Signature on components are a complex topic, which we discuss in depth in {ref}`component_signatures_chapter`. They are grouped in two dimensions:

- Who issued the signature (self-signature vs. third party signature)?
- What kind of statement does the signature make (certify an identity, or bind component keys into a certificate)?

```{figure} mermaid/06-terminology.png

An overview of signature types in OpenPGP
```

```{admonition} TODO
:class: warning

Group "Third-Party Certification" and "Self-Signature" as "Signature on components", in the diagram?
```

In this chapter we discuss general principles, which apply to all types of OpenPGP signatures.

For more detail about specific types of signatures, see the chapters {ref}`signing_data` and {ref}`component_signatures_chapter`, respectively.

## Structure of an OpenPGP signature packet

As outlined above, an OpenPGP signature is a composite data structure, which combines:

- A *signature type ID* (see above), which specifies the intended meaning of the signature,
- Metadata (which is variable and depends in part on the type ID),
  - Most of this metadata is encoded as so-called "subpackets," see {ref}`signature_subpackets`,
- A raw cryptographic signature.

```{figure} diag/signature_packet.png

Structure of an OpenPGP signature packet
```

### Creating an OpenPGP signature packet

When someone creates a signature packet, their goal is to make some type of statement about a set of input data, and encode this statement in the signature packet.

The input data consists of:

- a number of packets (usually one or more packets, but in some cases none), which the signature statement is about, and
-  some of the data in the signature packet itself. This data specifies the intent of the signature.

The signature type determines which data is used as the input data. Either way, the input data always consists of the information that the signature makes a statement about.

The signature packet consists of two parts:

- The data that defines the meaning of the statement, and
- A cryptographic digital signature with which the signer formally endorses that statement.

So the signature packet hinges on that cryptographic signature. It is produced by the issuer as follows:

1. A hash digest is calculated from the set of input data.
2. The signature is calculated for this hash digest.

```{figure} diag/Signature_Creation.png

Creating a signature in OpenPGP
```

### Verifying an OpenPGP signature packet

Verification of a signature packet involves many of the same steps. There are two main differences:

- While only the signer of the signature packet can create the cryptographic signature that it contains, everyone can verify the signature, provided they have access to the public key of the signer.
- After calculating the hash digest, a signature verification mechanism is used, based on the hash digest, the cryptographic signature, and the signer public key, to check if the signature is cryptographically valid.

```{figure} diag/Signature_Verification.png

Verifying a signature in OpenPGP
```

(signature_subpackets)=
## Signature subpackets

A bare cryptographic signature - even when combined with a signature type ID - is usually not sufficiently expressive. So, to encode additional metadata in signature packets, the OpenPGP protocol introduced signature subpackets (in [RFC 2440](https://datatracker.ietf.org/doc/html/rfc2440)).

Subpackets are well-defined data structures that can be placed into signature packets as sub-elements. They provide additional context and meaning for a signature. Subpackets encode data in a key-value format. The RFC defines all possible keys as [subpacket type IDs](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-subpacket-types-r) and provides the value format (and meaning) for all of them.

Typical examples are:
- The [*issuer fingerprint*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#issuer-fingerprint-subpacket) subpacket, which encodes the fingerprint of the component key that issued the signature, or
- The [*key flags*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) subpacket, that defines which capabilities are assigned to a component key, in a certificate.

### Hashed and unhashed signature subpackets

Signature subpackets can reside in [two different areas](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-hashed-vs-unhashed-subpacke) of a signature packet:

- Subpackets in the *hashed area* are included in the hash digest for that signature. In other words: hashed subpackets are covered by the cryptographic signature in the signature packet. Recipients of the signature can be sure that these subpackets express the intent of the issuer of the signature.
- Subpackets in the *unhashed area*, by contrast, are not included in the hash digest for that signature. They are therefore not protected against tampering. The unhashed area can be used to retroactively add, change or remove metadata in a signature packet, without invalidating it.  Since the unhashed area doesn't provide any cryptographic guarantees, it is only intended for advisory packets, or packets that self-authenticate (e.g. the issuer fingerprint subpacket, whose "correctness" can be proven by successfully verifying the signature using the referenced issuer key).
 
In most cases, signature subpackets are stored in the hashed area.

### Criticality of subpackets

Each signature subpacket has a flag that indicates whether the subpacket is *critical*. When set, the criticality flag signals that a receiving implementation that does not know a subpacket type, must consider this an error, and may not consider the signature valid.

The reason for this mechanism is that OpenPGP implementations may only support subsets of the standard - and the standard may be extended over time, including by the addition of new subpacket types.

However, it would be fatal if, for example, an implementation did not understand the concept of signature expiration. Such an implementation would potentially accept an already expired signature.
By marking the expiration date subpacket as critical, the creating implementation can indicate that recipients who do not understand this of subpacket must consider the signature as invalid.

RFC Sections [5.2.3.11](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-creation-time) - [5.2.3.36](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-intended-recipient-fingerpr) give guidance on which subpackets should be marked as critical.

## Advanced topics

### Notation signature subpackets

[Notations](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#notation-data) are a signature subpacket type that can be used to effectively extend the otherwise limited set of signature subpacket types with user-defined notations. An issuer can use notations to add name-value data to an OpenPGP signature.

Notation names are UTF-8 encoded strings. They may reside in the "user namespace," which means a notation *tag* (in UTF-8 string format) followed by a DNS domain name.

#### Use of notations by Keyoxide

Notations have, for example, been used for the popular decentralized identity verification service [Keyoxide](https://keyoxide.org/). Keyoxide uses notations in the `ariadne.id` namespace. See the [Keyoxide documentation](https://docs.keyoxide.org/wiki/ariadne-identity/) for more details.

### "Negotiating" signature hash algorithm based on recipients preference subpackets

```{admonition} TODO
:class: warning

investigate, discuss: GnuPG uses preference packets for the User ID that was addressed while sequoia completely omits User ID preferences and either uses Direct Key Sigs or (I think) primary User ID.
```

### Explore viability of having multiple signatures, e.g. v4+v6?

```{admonition} TODO
:class: warning

C-R 5.2. says: An implementation MUST generate a version 6 signature when signing with a version 6 key. An implementation MUST generate a version 4 signature when signing with a version 4 key.
```