OpenPGP for application developers

2024-03-17

• 1. Introducing OpenPGP
  • 1.1. What is OpenPGP?
  • 1.2. Who is the audience for this document?
  • 1.3. Why not just use the OpenPGP RFC?
  • 1.4. Which version of OpenPGP does this address?
• 2. A high-level view
  • 2.1. Why OpenPGP?
  • 2.2. A very brief history
  • 2.3. The RFC 4880 era
  • 2.4. The road ahead
  • 2.5. Zooming in: Internal structure of OpenPGP data
• 3. Cryptographic concepts and terms
  • 3.1. Cryptographic hash functions
  • 3.2. Message authentication codes
  • 3.3. Symmetric-key cryptography
  • 3.4. Public-key (asymmetric) cryptography
  • 3.5. Hybrid cryptosystems
• 4. Certificates
  • 4.1. Terminology: Understanding “keys”
  • 4.2. Structure of OpenPGP certificates
  • 4.3. Component keys
  • 4.4. Identity components
  • 4.5. Linking the components
  • 4.6. Metadata in certificates
  • 4.7. A typical OpenPGP certificate, revisited
  • 4.8. Revocations
  • 4.9. Third-party (identity) certifications
• 5. Managing private key material in OpenPGP
  • 5.1. Overview of private keys
  • 5.2. Terminology: “certificates” and “private keys”
  • 5.3. Transferable secret key format
  • 5.4. Protecting keys with passphrases
  • 5.5. OpenPGP cards for private keys
  • 5.6. Private key operations
• 6. OpenPGP Signatures
  • 6.1. Terminology: “cryptographic signatures” and “signature packets”
  • 6.2. Signature types in OpenPGP
  • 6.3. Structure of an OpenPGP signature packet
  • 6.4. Signature subpackets
• 7. Signatures over data
  • 7.1. Signature types
  • 7.2. Forms of OpenPGP data signatures
  • 7.3. Detached signatures
  • 7.4. Inline signatures
  • 7.5. Cleartext signatures
• 8. Signatures on components
  • 8.1. Self-signatures vs third-party signatures
  • 8.2. Self-signatures in certificate formation and management
  • 8.3. Authentication and delegation in third-party signatures
• 9. Signature verification
  • 9.1. When are signatures valid?
  • 9.2. Well-formedness of signatures
  • 9.3. Temporal validity
  • 9.4. Self-qualifying and non-self-qualifying signatures
  • 9.5. Signature qualification
  • 9.6. Revocations
• 10. Encryption
  • 10.1. Terminology
  • 10.2. High-Level overview of the message encryption process
  • 10.3. Encryption mechanism versions
  • 10.4. Encrypted session keys: PKESK, SKESK
  • 10.5. Symmetric encryption of data, SEIPD
• 11. Decryption
  • 11.1. Passphrase-protected session key (SKESK)
  • 11.2. Key-protected session key (PKESK)
  • 11.3. SEIPD (v1)
  • 11.4. SEIPD w/ AEAD (v2)
  • 11.5. SED
• 12. Compression
  • 12.1. Decompression yields a ‘wrapped’ OpenPGP packet stream
  • 12.2. Typical usage
• 13. ASCII armor
  • 13.1. Mechanism
  • 13.2. Example
  • 13.3. The cleartext signature framework
  • 13.4. Advanced topics
• 14. Pitfalls / Things to keep in mind
  • 14.1. Key IDs are really not guaranteed to be unique
  • 14.2. Signature Subpackets can have duplicates
  • 14.3. Packet Nesting can be unreasonable
• 15. Algorithms and Policy
• 16. OpenPGP versions
  • 16.1. Differences between OpenPGP versions
• 17. Migration from OpenPGP v4 to v6
  • 17.1. Adoption of new features
  • 17.2. Key migration
• 18. Advanced material: Certificates
  • 18.1. When are certificates valid?
  • 18.2. Certificates are effectively append-only data structures
  • 18.3. Merging
  • 18.4. Certificate minimization
  • 18.5. Fingerprints and beyond: “Naming” certificates in user-facing contexts
  • 18.6. Certificate freshness: Triggering updates with an expiration time
  • 18.7. Metadata leak of Social Graph
  • 18.8. Adding unbound, local User IDs to a certificate
  • 18.9. Certificate distribution mechanisms
  • 18.10. Third-party certification flooding
  • 18.11. First-Party attested third-party certifications in OpenPGP (1pa3pc)
• 19. Advanced material: Private keys
  • 19.1. Private keystores
  • 19.2. Understanding key overwriting (KO) attacks
• 20. Advanced material: Signatures
  • 20.1. Notation signature subpackets
  • 20.2. Choosing the hash algorithm for a signature
  • 20.3. Signature versions
• 21. Advanced material: Signatures over data
  • 21.1. Internals of inline signed messages
• 22. Advanced material: Signatures on components
  • 22.1. Certification recipes
  • 22.2. Managing subpacket conflicts and duplication
• 23. Advanced material: Signature verification
  • 23.1. Attribute shadowing
  • 23.2. Signature shadowing
  • 23.3. Which signatures take precedence?
  • 23.4. Complexity of the packet format
• 24. Advanced material: Encryption
  • 24.1. Encrypt to multiple/single subkey per certificate?
  • 24.2. “Negotiating” algorithms based on recipients preference subpackets
  • 24.3. AEAD modes in v2 SEIPD: GCM
• 25. Advanced material: Decryption
  • 25.1. Verify successful session key decryption
  • 25.2. Anonymous recipients
• 26. Zooming in: Packet structure of certificates
  • 26.1. A very minimal OpenPGP certificate
  • 26.2. Encryption subkey
  • 26.3. Signing subkey
  • 26.4. Adding an identity component
  • 26.5. Certifications (Third Party Signatures)
  • 26.6. Revocations
• 27. Zooming in: Packet structure of private key material
  • 27.1. A look at Alice’s (unencrypted) private key packets
  • 27.2. Bob’s (encrypted) private key material
• 28. Zooming in: Packet structure of data signatures
  • 28.1. Detached signature
  • 28.2. Inline signature
  • 28.3. Cleartext signature
• 29. Zooming in: Packet structure of encrypted data
  • 29.1. SEIPD v2
• 30. Glossary
• 31. Acknowledgements
  • 31.1. Team
  • 31.2. Expert advisors, readers, supporters
  • 31.3. Extended hat tips
  • 31.4. Funding
• 32. Appendix A: OpenPGP artifacts
  • 32.1. Alice’s OpenPGP key
  • 32.2. Bob’s OpenPGP key