vanitasvitae/openpgp-notes
1
0
Fork 0
mirror of https://codeberg.org/openpgp/notes.git synced 2025-09-09 11:19:41 +02:00
Code Issues Projects Releases Packages Wiki Activity

Edits for clarity

Browse source
This commit is contained in:
Heiko Schaefer 2023-12-10 19:51:31 +01:00
parent 18e0e06ff2
commit 71bf494283
No known key found for this signature in database
GPG key ID: DAE9A9050FCCF1EB
1 changed files with 30 additions and 30 deletions
Download patch file Download diff file Expand all files Collapse all files

60
book/source/15-migration.md
View file

@ -24,57 +24,59 @@ Other features can be used with existing OpenPGP version 4 keys, as soon as impl
A perfect example for a newly introduced feature that can be applied to existing v4 keys are the new SEIPD v2 packets.
Existing OpenPGP v4 keys can simply announce support for SEIPD v2 via a *Feature* subpacket in a self-signature. This signals to producers that the user's OpenPGP software is capable of handling SEIPD v2.
Existing OpenPGP v4 keys can simply announce support for SEIPD v2 via a *Feature* subpacket in their certificate. Publishing such an updated *Feature* set via their OpenPGP certificate signals that the user's OpenPGP software is capable of handling SEIPD v2.
Senders who can produce this new encryption mode can then opt to use it when encrypting to this recipient.
(migration_s2k)=
### S2K usage mode AEAD
Another good example is the S2K mechanism for secret-key encryption.
This feature concerns local copies of OpenPGP private keys on each user's machine. There is, by definition, no interoperability concern around this feature: Passphrase-protection of the private key material is a local implementation detail on each user's machine.
The RFC [states](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-avoiding-ciphertext-malleab) that: "Users are RECOMMENDED to migrate to AEAD."
In the context of this chapter, this means that encrypted private keys should be upgraded by the user's OpenPGP software to use S2K usage mode 253 (AEAD) to encrypt the user's private key material.
In the context of this chapter, this means that encrypted private keys should be upgraded by the user's OpenPGP software to use [S2K usage mode 253](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-secret-key-encryption-s2k-u) (AEAD) to encrypt the user's private key material.
Note that S2K usage mode 253 (AEAD) can be applied to both version 6 and version 4 private keys, with sufficiently up-to-date OpenPGP software. This S2K usage mode is strongly recommended for all private keys.
Note that S2K usage mode 253 (AEAD) can be applied to both version 6 and version 4 private keys, with sufficiently up-to-date OpenPGP software. This S2K usage mode is strongly recommended for private keys of all versions.
#### S2K method Argon2
Independently, the RFC recommends the use of the Argon2 S2K method to hash passphrases, when it is available.
Independently, the RFC recommends the use of the Argon2 S2K method to hash passphrases, when it is available. This mechanism also concerns the local passphrase-protection of private key material.
Argon2 is only allowed in combination with AEAD.
Use of Argon2 is only allowed in combination with AEAD.
Users can and should migrate the protection of their private keys to Argon2 combined with the AEAD usage mode.
Users can and should migrate the protection of their private keys to Argon2 (combined with the AEAD usage mode).
### v6 signatures
### OpenPGP v6 signatures
One feature that is denied from v4 keys are v6 signatures. Only v6 keys may issue v6 signatures.
Version 6 signatures can't be generated with OpenPGP v4 keys. Only OpenPGP v6 keys can issue v6 signatures.
Of course, holders of v4 certificates can still verify v6 signatures, if their OpenPGP software supports dealing with v6 certificates and v6 signature verification.
On the receiving/verifying side, v6 signatures can be checked by anyone whose OpenPGP software supports v6 certificates and v6 signature verification. This includes OpenPGP users who currently use a v4 key.
### Software migration
Over time, OpenPGP tooling will evolve and steadily more libraries and tools will add support for OpenPGP v6 features. This migration might take a while, while implementers catch up.
Over time, steadily more OpenPGP libraries and tools will add support for OpenPGP v6 features. This migration might take a while, while implementers catch up.
The OpenPGP v6 standard gives guidance for implementers by listing[^migration_steps] steps which are necessary to become an OpenPGP v6 compatible implementation.
The OpenPGP v6 standard gives guidance for library authors to extend an OpenPGP implementation to support version 6 in [Appendix B. Upgrade Guidance](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-upgrade-guidance-adapting-i).
[^migration_steps]: See [Appendix B. Upgrade Guidance](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-upgrade-guidance-adapting-i)
## Key migration
## Key material migration
Some OpenPGP v6 features are only available for use with keys in the v6 format.
Some features of OpenPGP v6 are only available for use with keys in the v6 format.
For example, only a v6 key might issue a v6 signature[^v6keyv6sig].
[^v6keyv6sig]: [v6 keys can only issue v6 signatures](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-packet-versions-in-signatur)
For example, only an [OpenPGP v6 key can issue a v6 signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-packet-versions-in-signatur).
On the other hand, a v6 key can *only* issue v6 signatures, so if you require compatibility with v4 verifiers, you shouldn't yet migrate to a v6 key/certificate.
On the other hand, an OpenPGP v6 key can *only* issue v6 signatures, so if you require compatibility with v4 verifiers, you shouldn't yet migrate to a v6 key/certificate.
When migrating to v6 key material, the user must either switch to a freshly generated v6 key, or convert their v4 keys to the v6 format. Doing the former is the recommended approach.
It is not possible to adopt v4 subkeys into a v6 key, since every subkey to a v6 primary key must itself be a v6 subkey[^v6subkey].
[^v6subkey]: See [OpenPGP v6 certificate structure](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-10.1.1-5)
When migrating to a v6 key, generating a fresh v6 key is the recommended approach.
It is not possible to adopt v4 subkeys into a v6 key, since every subkey to a v6 primary key must itself be a v6 subkey, see in [OpenPGP v6 certificate structure](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-10.1.1-5).
### Converting v4 component keys into v6 component keys
That is: Taking the existing key material from a v4 component key and re-framing it as a v6 component key, for use with an OpenPGP version 6 certificate.
```{admonition} TL;DR
:class: info
@ -85,15 +87,15 @@ don't.
It might be tempting to consider migrating existing key material to the v6 format. Such a step should be considered very carefully though.
Unfortunately, keys cannot simply be converted into the new format, as amongst others Key IDs and fingerprints will change;
Unfortunately, keys cannot simply be converted into the new format, and used seamlessly. For one thing, the Fingerprint of component keys changes for the same key material between version 4 and version 6 (and with it, the Key ID that is a shortened version of the Fingerprint).
An OpenPGP v4 fingerprint is calculated as the SHA-1 checksum of the normalized public key packet, which results in a 40 digit fingerprint. The Key ID is the *last* 64 bits of the fingerprint.
An OpenPGP v4 Fingerprint is calculated as the SHA-1 checksum of the normalized public key packet, which results in a 20 byte fingerprint (often represented as a 40 character hexadecimal string). The v4 Key ID consists of the *last* 64 bits of the fingerprint.
On the other hand, a v6 fingerprint is calculated as the SHA256 checksum of the normalized public key packet, so it has 64 characters. The Key ID are the *first* 64 bit of the fingerprint.
On the other hand, a v6 fingerprint is calculated as the SHA-256 checksum of the normalized public key packet, so it comprises 32 bytes. The v6 Key ID consists of the *first* 64 bit of the fingerprint.
As a consequence, identifiers in OpenPGP artifacts, such as issuer subpackets in signatures, or recipient Key IDs in PKESK packets issued by a v4 key no longer match the identifiers of the converted key material.
As a consequence, component key identifiers in OpenPGP artifacts, such as issuer subpackets in signatures, or recipient Key IDs in PKESK packets issued by a v4 key do not match the component key identifiers of same key material converted to v6.
Further, since v6 keys can only issue v6 signatures, they also can only verify v6 signatures, as otherwise there would be a downgrade vector where v6 keys could be tricked into verifying specially crafted v4 signatures, should a v4 vulnerability arise at some point.
Further, v6 keys can only issue v6 signatures, and v6 certificates can only be used to verify v6 signatures. Otherwise, a downgrade vector could exist, by which verifiers could be tricked into verifying specially crafted v4 signatures against OpenPGP v6 certificates. If a vulnerability arose in OpenPGP v4 at some point, which allows an attacker to craft valid v4 signatures, this could affect OpenPGP v6 certificates.
Another motivation for converting old key material might be the desire to stay able to decrypt messages encrypted for the old key.
This won't be possible out of the box, as the Key ID in the respective PKESK packet no longer matches that of the converted key, so at the bare minimum, the user's implementation needs to be able to map Key IDs. This is not a feature prevalent in the ecosystem though.
@ -103,8 +105,6 @@ What could be a better solution than manual Key ID mapping would be to replace t
In conclusion, converting v4 key material to v6 to verify old signatures is not a valid argument.
Being able to read old messages using a converted key is also not really viable, since it is equally simple to just re-create the PKESK headers for a fresh v6 key.
```{admonition} TODO
:class: warning
Also see: https://wiki.gnupg.org/OpenPGPEmailSummit202305Notes
```{note}
Also see <https://wiki.gnupg.org/OpenPGPEmailSummit202305Notes>
```