]>

heiko.schaefer@posteo.de

vanitasvitae@fsfe.org

int openpgp Internet-Draft This document defines a standard wire format for indicating that the secret component of an OpenPGP asymmetric key is stored externally, for example on a hardware device or other comparable subsystem. The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the OpenPGP Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction Some OpenPGP secret key material is held by a hardware device that permits the user to operate the secret key without divulging it explicitly. For example, the specification is intended specifically for this use. It is also possible for an OpenPGP implementation to use external secret key material via a standard platform library interface like . An OpenPGP Secret Key Packet (see ) is typically used as part of a Transferable Secret Key () for interoperability between OpenPGP implementations. An implementation that uses an external secret key needs a standardized way to indicate to another implementation that specific secret key material has been delegated to some external mechanism, like a hardware device. This document defines a simple mechanism for indicating that a secret key has been delegated to an external mechanism by allocating a codepoint in the "Secret Key Encryption (S2K Usage Octet)" registry (see ). It also establishes a registry of hints about how to locate the external device, and defines a minimalist "best effort" method for locating external secret keys that is implementation-specific. This document makes no attempt to specify how an OpenPGP implementation discovers, enumerates, or operates external secret keys, other than to recommend that the hardware or comparable external subsystem should be identifiable by the secret key's corresponding public key material.

Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. The key words "PRIVATE USE" and "SPECIFICATION REQUIRED" that appear in this document when used to describe namespace allocation are to be interpreted as described in .

Terminology "Secret key" refers to a single cryptographic object, for example the "56 octets of the native secret key" of X448, as described in . "Public key" likewise refers to a single cryptographic object, for example the "56 octets of the native public key" of X448, as above. "OpenPGP certificate" or just "certificate" refers to an OpenPGP Transferable Public Key (see ). "External" refers to any cryptographic device or subsystem capable of performing an asymmetric secret key operation using an embedded secret key without divulging the secret to the user. For discoverability, the external mechanism is also expected to be able to produce or be indexed by the public key corresponding to the embedded secret key. While this document talks about "external" in the abstract as referring to a cryptographic device embedding a single secret key, most actual hardware devices or other cryptographic subsystems will embed and enable the use of multiple secret keys (see ). This document uses the term "authorization" to mean any step, such as providing a PIN, password, proof of biometric identity, button-pushing, etc, that the external subsystem may require for an action.

Externally-backed Secret Key Material An OpenPGP Secret Key packet () indicates that its secret key material is stored in a cryptographic subsystem that is identifiable by public key parameters by setting the S2K usage octet to TBD (252?), known in shorthand as External. The remainder of the Secret Key packet consists of an optional hint about how the implementation might be able to locate an external subsystem that offers access to the secret key. This locator hint is entirely advisory. If the locator hint is absent (that is, if there are no bytes in the Secret Key packet following the External S2K usage octet), then the secret key is considered "unavailable" (see ).

Locator Hint If there is a locator hint, then the first octet of the hint describes the structure of the remainder of the hint, according to the "OpenPGP External Secret Key Locator Hints" registry established by this document. That registry initially only contains the value 0 for "best effort" (see ). The octet values 96-111 (inclusive) are reserved for PRIVATE USE. Adding a new entry into that registry in any other range uses IANA policy SPECIFICATION REQUIRED. Regardless of what the locator hint says, a consuming implementation SHOULD use the "best effort" approach to identify an external subsystem that can provide access to the secret key. A producing implementation that does not know how to provide a meaningful locator hint SHOULD set the locator hint to "best effort". A consuming implementation that does not understand any particular locator hint SHOULD ignore any trailing data in such a Secret Key packet. The purpose of the hinting mechanism is to enable optimized access. For example, if an OpenPGP implementation has access to several dozen hardware tokens, and if querying each attached hardware token is expensive, a locator hint can be used to preferentially access a likely token, without probing each token. This document does not describe any particular scheme of locator hint beyond "best effort".

Length constraint of locator hint The locator hint data is associated with the S2K usage octet (i.e. it is handled as "S2K parameter fields", as specified in ). Note that the "S2K parameter fields" segment of a v6 secret key packet uses an explicit length field, which limits its length to at most 255 octets Thus, a locator hint, including the locator hint ID octet, MUST NOT exceed a length of 255 octets, for any key version.

Secret Key Material is Unavailable If the locator hint is absent, the secret key material is marked as "unavailable". This signals to an application that the key material can not be accessed, including from any "external" source. An application that encounters a secret key packet that is marked as external and unavailable should signal to its user that secret key operations with that key are not available (e.g. by greying out operations in GUI interfaces). Marking secret key material as "external and unavailable" is appropriate in setups where the secret key material of a component key is entirely unavailable in a user's current operating environment. The key material may be available in a separate special environment (e.g. on an air gapped separate computer), or entirely unavailable (e.g. when a primary key packet has been generated ephemerally and the secret key material has not been persisted).

Best Effort Access to External Secret Keys When the locator hint is set to "best effort", no additional data may be stored in the locator hint field. A consuming implementation MUST ignore any additional data in the locator hint field, and perform a "best effort" search. When the locator hint is set to "best effort", or when a consuming implementation does not understand a given locator hint, or when a given locator hint fails to point to a useful device, a consuming implementation SHOULD use a "best effort" strategy to identify an external subsystem that provides access ta a secret key that matches the corresponding public key material. Each OpenPGP implementation might support different external subsystems. And, in some installations, the same external subsystem might be identified in different ways (for example, a USB smartcard might be connected to hub 2 at low speed, and in another, the same USB smartcard might be connected to hub 1 at high speed). In some cases, no external subsystem can be identified that supports access to secret key material that corresponds to the associated public key. Or, the external subsystem might be available, but for whatever reason attempting to use it could fail (for example, the hardware might advertise the availability of the key, but deny access when the implementation tries to use it). In these cases, an OpenPGP implementation that tries to use such an external secret key will fail. The implementation should fail in a similar way to how it might fail if it tried to use a typical software-backed secret key locked with a password, but the password is unavailable to the implementation.

Security Considerations External or hardware-backed secret keys promise several distinct security advantages to the user: Often, the secret key cannot be extracted from the external device, so "kleptography" (the stealing of secret key material) is harder to perform. Some hardware can be moved between machines, enabling secret key portability without expanding the kleptographic attack surface. Some hardware devices offer auditability controls in the form of rate-limiting, user-visible authorization steps (e.g., button-presses or biometric sensors), or tamper-resistant usage counters. Malicious use of a secret key on such a device should be harder, or at least more evident. Some hardware security devices can attest that key material has been generated on-card, thereby signaling that - barring a successful attack on the hardware - no other copy of the private key material exists. Such mechanisms signal that the key holder did not have a chance to mishandle (e.g.: accidentally disclose) the private key material. However, none of these purported advantages are without caveats. The hardware itself might actually not resist secret key exfiltration as expected. For example, isolated hardware devices are sometimes easier to attack physically, via temperature or voltage fluctuations (see and ). In some cases, dedicated cryptographic hardware that generates a secret key internally may have significant flaws (see ). Furthermore, the most sensitive material in the case of decryption is often the cleartext itself, not the secret key material. If the host computer itself is potentially compromised, then kleptographic exfiltration of the secret key material itself is only a small risk. For example, when handling an OpenPGP Encrypted Message, the OpenPGP symmetric session key itself could be exfiltrated, permitting access to the cleartext to anyone without access to the secret key material. Portability brings with it other risks, including the possibility of abuse by the host software on any of the devices to which the hardware is connected. Rate-limiting, user-visible authorization steps, and any other form of auditability also suffer from risks related to compromised host operating systems. Few hardware devices are capable of revealing to the user what operations specifically were performed by the device, so even if the user deliberately uses the device to, say, sign an object, the user depends on the host software to feed the correct object to the device's signing capability.

Usability Considerations External secret keys present specific usability challenges for integration with OpenPGP.

Some Hardware Might Be Unavailable To Some Implementations This specification gives no guidance for how to find the hardware device, and presumes that an implementation will be able to probe available hardware to associate it with the corresponding public key material. In particular, there is no attempt to identify specific hardware or "slots" using identifiers like PKCS #11 URIs () or smartcard serial numbers (see ). This minimalism is deliberate, as it's possible for the same key material to be available on multiple hardware devices, or for a device to be located with a particular hardware identifier on one platform, while on another platform it uses a different hardware identifier. Not every OpenPGP implementation will be able to talk to every possible hardware device. If an OpenPGP implementation encounters a hardware-backed secret key as indicated with this mechanism, but cannot identify any attached hardware that lists the corresponding secret key material, it should warn the user that the specific key claims to be hardware-backed but the corresponding hardware cannot be found. It may also want to inform the user what categories of hardware devices it is capable of probing, for debugging purposes.

Hardware Should Support Multiple Secret Keys Most reasonable OpenPGP configurations require the use of multiple secret keys by a single operator. For example, the user may use one secret key for signing, and another secret key for decryption, and the corresponding public keys of both are contained in the same OpenPGP certificate. Reasonable hardware SHOULD support embedding and identifying more than one secret key, so that a typical OpenPGP user can rely on a single device for hardware backing.

Authorization Challenges Cryptographic hardware can be difficult to use if frequent authorization is required, particularly in circumstances like reading messages in a busy e-mail inbox. This hardware MAY require authorization for each use of the secret key material as a security measure, but considerations should be made for caching authorization. If the cryptographic hardware requires authorization for listing the corresponding public key material, or for probing whether a given public key matches the device's secret keys, it becomes even more difficult to use the device in regular operation. Hardware SHOULD NOT require authorization for the action of producing the list of corresponding public keys or for probing whether a public key matches the device's secret keys. If a user has two attached pieces of hardware that both hold the same secret key, and one requires authorization while the other does not, it is reasonable for an implementation to try the one that doesn't require authorization first. Some cryptographic hardware is designed to lock the device on repeated authorization failures (e.g. 3 bad PIN entries locks the device), so this approach reduces the risk of accidental lockout.

Latency and Error Handling While hardware-backed secret key operations can be significantly slower than modern computers, and physical affordances like button-presses or NFC tapping can themselves incur delay, an implementation using a hardware-backed secret key should remain responsive to the user. It should indicate when some interaction with the hardware may be required, and it should use a sensible timeout if the hardware device appears to be unresponsive. A reasonable implementation should surface actionable errors or warnings from the hardware to the user where possible.

IANA Considerations This document asks IANA to make three changes in the "OpenPGP" protocol group. Add the following row in the "OpenPGP Secret Key Encryption (S2K Usage Octet)" registry: S2K usage octet Shorthand Encryption parameter fields Encryption Generate? TBD (252?) External External Locator Hint, see of RFC XXX (this document) no data Yes Modify this row of the "OpenPGP Symmetric Key Algorithms" registry: ID Algorithm 253, 254, and 255 Reserved to avoid collision with Secret Key Encryption to include TBD (252?) in this reserved codepoint sequence, resulting in the following entry: ID Algorithm TBD (252?), 253, 254, and 255 Reserved to avoid collision with Secret Key Encryption Establish a new registry, "OpenPGP External Secret Key Locator Hints", with the following columns and initial range: ID Shorthand Description Reference 0 Best Effort   RFC XXX (this document) 1-95 Unassigned   RFC XXX (this document) 96-111 Private or Experimental Use   RFC XXX (this document) 112-255 Unassigned   RFC XXX (this document) Assigning a new codepoint to this registry uses SPECIFICATION REQUIRED.

This document specifies the message formats used in OpenPGP. OpenPGP provides encryption with public key or symmetric cryptographic algorithms, digital signatures, compression, and key management. This document is maintained in order to publish all necessary information needed to develop interoperable applications based on the OpenPGP format. It is not a step-by-step cookbook for writing an application. It describes only the format and methods needed to read, check, generate, and write conforming packets crossing any network. It does not deal with storage and implementation questions. It does, however, discuss implementation issues necessary to avoid security flaws. This document obsoletes RFCs 4880 ("OpenPGP Message Format"), 5581 ("The Camellia Cipher in OpenPGP"), and 6637 ("Elliptic Curve Cryptography (ECC) in OpenPGP"). In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Many protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA). To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry. This is the third edition of this document; it obsoletes RFC 5226. g10 Code Trusted Computing Group arXiv Masaryk University, Ca' Foscari University of Venice, Brno, Czech Rep Masaryk University, Brno, Czech Rep Masaryk University, Brno, Czech Rep EnigmaBridge, Masaryk University, Brno, Czech Rep Masaryk University, Brno, Czech Rep ACM This memo specifies a PKCS #11 Uniform Resource Identifier (URI) Scheme for identifying PKCS #11 objects stored in PKCS #11 tokens and also for identifying PKCS #11 tokens, slots, or libraries. The URI scheme is based on how PKCS #11 objects, tokens, slots, and libraries are identified in "PKCS #11 v2.20: Cryptographic Token Interface Standard".

Historical notes Some OpenPGP implementations make use of private codepoint ranges in the OpenPGP specification within an OpenPGP Transferable Secret Key to indicate that the secret key can be found on a smartcard. For example, GnuPG uses the private/experimental codepoint 101 in the S2K Specifier registry, along with an embedded trailer with an additional codepoint, plus the serial number of the smartcard (see ). However, recent versions of that implementation ignore the embedded serial number in favor of scanning available devices for a match of the key material, since some people have multiple cards with the same secret key.

Test vectors

Example Transferable Secret Keys Example OpenPGP v6 Transferable Secret Key. It includes (unencrypted) private key material for both its primary key and one subkey:

Example OpenPGP v4 Transferable Secret Key. It includes (unencrypted) private key material for both its primary key and one subkey:

As an External Secret Key, with "best effort" locator hint The OpenPGP v6 Transferable Secret Key with the S2K Usage Octet set to 252? (External) for both the Primary Key Packet and the Subkey Packet. The locator hint 0x00 ("best effort") is included in the secret key packets, following the S2K Usage Octet and a length octet.

The (primary) Secret-Key Packet of this key looks as follows, note the trailing cumulative length octet of the conditionally included S2K parameter fields as described in :

The same OpenPGP v4 Transferable Secret Key with the S2K Usage Octet set to 252? (External) for both the Primary Key Packet and the Subkey Packet. The locator hint 0x00 ("best effort") is included in the secret key packets, following the S2K Usage Octet.

The (primary) Secret-Key Packet of this key looks as follows, in this format:

As an External Secret Key, with "unavailable" primary secret key data The OpenPGP v6 Transferable Secret Key with the S2K Usage Octet set to 252? (External) for both the Primary Key Packet and the Subkey Packet. No locator hint data is included in the primary secret key packet, marking that packet's secret key material as "unavailable".

The (primary) Secret-Key Packet of this key looks as follows, in this format:

As an External Secret Key, with experimental locator hint The OpenPGP v6 Transferable Secret Key with the S2K Usage Octet set to 252? (External) for both the Primary Key Packet and the Subkey Packet. The locator hint 0x60 (the first value in the experimental range) is included in the secret key packets, following the S2K Usage Octet and a length octet. No locator hint data is included in the primary secret key packet, marking that packet's secret key material as "unavailable".

The (primary) Secret-Key Packet of this key looks as follows, in this format:

Acknowledgements This document is based on significant work by many people, including implementations and guidance: Daniel Kahn Gillmor NIIBE Yutaka Achim Pietig Werner Koch Andrew Gallagher The people acknowledged in this section are not responsible for any proposals, errors, or omissions in this document.

Document History

Substantive Changes from draft-ietf-openpgp-external-secrets-00 to draft-ietf-openpgp-external-secrets-01 Add concept of "unavailable" external secrets, it is now the default when no locator hint is set Add explicit "best effort" locator hint Update test vectors to reflect the above changes; add test vector with an "experimental" locator hint

Substantive Changes from draft-dkg-openpgp-external-secrets-03 to draft-ietf-openpgp-external-secrets-00 Remove Daniel Kahn Gillmor, add Paul Schaub as co-author Describe length constraint of locator hint

Substantive Changes from draft-dkg-openpgp-external-secrets-02 to draft-dkg-openpgp-external-secrets-03 Add Heiko Schäfer as co-author Add v6 test vectors

Substantive Changes from draft-dkg-openpgp-external-secrets-01 to draft-dkg-openpgp-external-secrets-02 A device can support indexing (probing for public key material) instead of enumerating available public keys Encourage "best effort" even if an understood locator hint fails to identify a device Private use range is now "Private or Experimental", and aligned with a power of 2

Substantive Changes from draft-dkg-openpgp-external-secrets-00 to draft-dkg-openpgp-external-secrets-01 define the external locator hinting mechanism

Substantive Changes from draft-dkg-openpgp-hardware-secrets-02 to draft-dkg-openpgp-external-secrets-00 rename from "Hardware-backed" to "External" use RFC9580 instead of I-D.ietf-openpgp-crypto-refresh

Substantive Changes from draft-dkg-openpgp-hardware-secrets-01 to draft-dkg-openpgp-hardware-secrets-02 re-format hexdump of test vector secret key packet

Substantive Changes from draft-dkg-openpgp-hardware-secrets-00 to draft-dkg-openpgp-hardware-secrets-01 Added test vector for experimentation Mention on-device attestation update OpenPGP card spec reference to 3.4.1