RFC 7191
Cryptographic Message Syntax (CMS) Key Package Receipt and Error Content Types
RFC 7191: Cryptographic Message Syntax (CMS) Key Package Receipt and Error Content Types 🎀
Okay bestie, RFC 7191 is giving receipts 💌 It's a standards track doc from April 2014, written by R. Housley at Vigil Security. ISSN 2070-1721. The header doesn't list anything it obsoletes or updates, so there's no drama there 🫶
Abstract
This doc defines the syntax for two CMS content types ✨: one for key package receipts and one for key package errors. A key package receipt confirms you got an identified key package (or a collection of them). A key package error says something went wrong while a key package was being processed 😭 CMS can digitally sign, digest, authenticate, or encrypt these content types, so they're super flexible.
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 5741.
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc7191.
Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
Table of Contents
1. Introduction ....................................................2
1.1. Requirements Terminology ...................................2
1.2. ASN.1 Syntax Notation ......................................2
1.3. Processing Key Package Receipt Requests ....................3
1.4. Processing Key Packages with Errors ........................3
2. SIR Entity Name .................................................3
3. Key Package Identifier and Receipt Request Attribute ............4
4. Key Package Receipt CMS Content Type ............................6
5. Key Package Error CMS Content Type ..............................8
6. Protecting the KeyPackageReceipt and KeyPackageError ...........17
7. Using the application/cms Media Type ...........................17
8. IANA Considerations ............................................17
9. Security Considerations ........................................17
10. Acknowledgements ..............................................18
11. References ....................................................18
11.1. Normative References .....................................18
11.2. Informative References ...................................20
Appendix A. ASN.1 Module ..........................................211. Introduction ✨
This doc defines the syntax for two CMS [RFC5652] content types 💖: one for key package receipts and one for key package errors. The receipt type is used to confirm receipt of an identified key package or a collection of key packages. The error type is used to indicate that an error occurred while a key package was being processed. CMS can digitally sign, digest, authenticate, or encrypt these content types.
1.1. Requirements Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].
1.2. ASN.1 Syntax Notation
The content types defined here use ASN.1 ([X.680], [X.681], [X.682], and [X.683]).
The CONTENT-TYPE definition was updated to the 2008 version of ASN.1 by [RFC6268]. However, none of the new 2008 ASN.1 tokens are used in this specification, which means compilers that only support the 2002 version of ASN.1 can still compile the module in Appendix A 🧚
1.3. Processing Key Package Receipt Requests
The key package or collection of key packages [RFC4073] [RFC5958] [RFC6031] [RFC6032] for which the receipt is being generated MUST be signed, and the key package MUST include the key-package-identifier-and-receipt-request attribute specified in Section 3.
1.4. Processing Key Packages with Errors
The key package or collection of key packages [RFC4073] [RFC5958] [RFC6031] [RFC6032] for which the error is being generated might be signed. The key package can be identified by a key-package-identifier-and-receipt-request attribute specified in Section 3.
2. SIR Entity Name 🦋
Within a key distribution system, the source, intermediary, and receiver entities are identified by a Source Intermediary Recipient (SIR) entity name. The syntax for the SIR entity name doesn't impose any particular structure, and it makes it easy to register additional SIR entity name types.
Including the nameType object identifier makes sure that two identifiers of different types that happen to contain the same values aren't treated as equivalent 🙈 More SIR entity name types are expected to be registered for different granularities. For example, one type might represent the receiver organization. At a finer granularity, another type might identify a specific device, perhaps using a manufacturer identifier and serial number. Using an object identifier means there's no need for a central registry of SIR entity name types. Very clean 💅
The nameValue is an OCTET STRING, which lets the canonical form of any name be carried. Two names of the same type are considered equal if the octet strings are the same length and contain the same string of octets.
SIREntityNames and SIREntityName have the following syntax:
SIREntityNames ::= SEQUENCE SIZE (1..MAX) OF SIREntityName
SIR-ENTITY-NAME ::= CLASS {
&sIRENType OBJECT IDENTIFIER UNIQUE,
&SIRENValue
} WITH SYNTAX {
SYNTAX &SIRENValue IDENTIFIED BY &sIRENType }
SIREntityName ::= SEQUENCE {
sirenType SIR-ENTITY-NAME.&sIRENType({SIREntityNameTypes}),
sirenValue OCTET STRING (CONTAINING
SIR-ENTITY-NAME.&SIRENValue(
{SIREntityNameTypes}{@sirenType}) ) }This doc defines one SIR entity name type: the DN type 👑 The DN type uses a nameType of id-dn and a nameValue of a Distinguished Name (DN). The nameValue OCTET STRING carries an ASN.1 encoded Name as specified in [RFC5280]. Note that other documents may define additional types.
SIREntityNameTypes SIR-ENTITY-NAME ::= {
siren-dn,
... -- Expect additional SIR Entity Name types -- }
siren-dn SIR-ENTITY-NAME ::= {
SYNTAX DistinguishedName
IDENTIFIED BY id-dn }
id-dn OBJECT IDENTIFIER ::= {
joint-iso-ccitt(2) country(16) us(840) organization(1)
gov(101) dod(2) infosec(1) sir-name-types(16) 0 }3. Key Package Identifier and Receipt Request Attribute 💜
The key-package-identifier-and-receipt-request attribute, as the name suggests, lets the originator identify the key package and, optionally, request receipts. This attribute can appear as a signed, authenticated, and content attribute. Signed attributes are carried in the CMS Signed-data content type described in Section 5 of [RFC5652]. Authenticated attributes are carried in the CMS Authenticated-data content type described in Section 9 of [RFC5652] or in the CMS Authenticated-enveloped-data content type described in Section 2 of [RFC5083]. Content attributes are carried in the Content-with-attributes content type described in Section 3 of [RFC4073].
The key-package-identifier-and-receipt-request attribute has the following syntax:
aa-keyPackageIdentifierAndReceiptRequest ATTRIBUTE ::= {
TYPE KeyPkgIdentifierAndReceiptReq
IDENTIFIED BY id-aa-KP-keyPkgIdAndReceiptReq }
id-aa-KP-keyPkgIdAndReceiptReq OBJECT IDENTIFIER ::= {
joint-iso-itu-t(2) country(16) us(840) organization(1)
gov(101) dod(2) infosec(1) attributes(5) 65 }
KeyPkgIdentifierAndReceiptReq ::= SEQUENCE {
pkgID KeyPkgID,
receiptReq KeyPkgReceiptReq OPTIONAL }
KeyPkgID ::= OCTET STRING
KeyPkgReceiptReq ::= SEQUENCE {
encryptReceipt BOOLEAN DEFAULT FALSE,
receiptsFrom [0] SIREntityNames OPTIONAL,
receiptsTo SIREntityNames }Even though the ATTRIBUTE syntax is defined as a SET OF AttributeValue, a key-package-identifier-and-receipt-request attribute MUST have a single attribute value. Zero or multiple instances of AttributeValue are not permitted 🙅♀️
The fields in the key-package-identifier-and-receipt-request attribute have these semantics:
pkgIDcontains an octet string, and this syntax doesn't impose any particular structure on the identifier.receiptReqis OPTIONAL. When it's present, it includes an encryption receipt flag, an OPTIONAL indication of which receivers should generate receipts, and an indication of where the receipts are to be sent.- The encryption receipt flag shows whether the key package originator wants the receipt to be encrypted. If the boolean is set, then the receipt SHOULD be encrypted 🔐
- The OPTIONAL
ReceiptsFromfield indicates which receivers SHOULD generate receipts. When theReceiptsFromfield is absent, all receivers of the key package are expected to return receipts. When theReceiptsFromfield is present, a list of SIR entity names shows which receivers of the key package are requested to return receipts. In this case, the receiver SHOULD return a receipt only if their SIR entity name appears on the list. - The receipt request doesn't include any key management information. However, the list of SIR entity names in the
receiptsTofield can be used to select symmetric or asymmetric keying material for the receipt receivers 🗝️
A receiver SHOULD ignore the nameValue associated with any unrecognized nameType in either the receiptsFrom field or the receiptsTo field.
When the key-package-identifier-and-receipt-request attribute appears in more than one location in the overall key package, each occurrence is evaluated independently. That means the receiver may generate more than one receipt for a single key package. However, the time at which the receipts are sent will depend on policies that are beyond the scope of this document ⏰
4. Key Package Receipt CMS Content Type ✨
okay so the key package receipt content type is how you confirm you got a key package (or a whole collection of them) 🎀 this one MUST be encoded using the Distinguished Encoding Rules (DER) [X.690], no cap 💅
The key package receipt content type has the following syntax:
ct-key-package-receipt CONTENT-TYPE ::= {
TYPE KeyPackageReceipt
IDENTIFIED BY id-ct-KP-keyPackageReceipt }
id-ct-KP-keyPackageReceipt OBJECT IDENTIFIER ::= {
joint-iso-itu-t(2) country(16) us(840) organization(1)
gov(101) dod(2) infosec(1) formats(2)
key-package-content-types(78) 3 }
KeyPackageReceipt ::= SEQUENCE {
version KeyPkgVersion DEFAULT v2,
receiptOf KeyPkgIdentifier,
receivedBy SIREntityName }
-- Revised definition of KeyPkgVersion from [RFC6031]
KeyPkgVersion ::= INTEGER { v1(1), v2(2) } (1 .. 65535)
KeyPkgIdentifier ::= CHOICE {
pkgID KeyPkgID,
attribute SingleAttribute {{ KeyPkgIdentifiers }} }
KeyPkgID ::= OCTET STRING
KeyPkgIdentifiers ATTRIBUTE ::= { ... }The KeyPackageReceipt fields are used like this:
versiontells you which version of the key package receipt content you're looking at 🌸 for this version of the spec, the default value, v2, MUST be used. v1 was in an earlier version, but using it is deprecated, so pls don't 🙈receiptOfgives you two options for pointing at the key package the receipt is for 🦋 the first one,pkgID, MUST be supported, and it carries the key package identifier of the key package or collection of key packages the receipt is being made for. That identifier value MUST exactly match the key package identifier value of the key-package-identifier-and-receipt-request attribute in the received key package or collection. That attribute is described in Section 3. The second option lets you use alternate attributes to define the identifier, which is giving flexibility ✨receivedByidentifies the entity that received the key package 🧚 the entity is named by an SIR entity name, as specified in Section 2.
Key package receipts MUST be encapsulated in a CMS SignedData content type so they carry the signature of the entity confirming receipt of the identified key package or collection of key packages 🔥 they MAY be encrypted by wrapping them in the CMS EncryptedData content type, the CMS EnvelopedData content type, or the AuthEnvelopedData content type. If a receipt is both signed and encrypted, it MUST be signed prior to being encrypted. The order matters, bestie 💜
Delivery assurance is the responsibility of the protocol that is used to transport and track key packages. The key package receipt content type can be used alongside that protocol as part of an overall delivery assurance solution. It's a team effort 🫶
Because the receipts are signed, every recipient that generates key package receipts MUST have a private signature key to sign the receipt, and MUST also store their own certificate or have a way to get the key identifier of their public key 🔐 if memory is a concern, the public key identifier can be computed from the public key, which is a nice little trick ✨
If the receipt signer has access to a real-time clock, the binary-signing-time [RFC6019] signed attribute SHOULD be included in the key package receipt to show the date and time it was generated 🕰️ very organized of them 🎀
5. Key Package Error CMS Content Type ✨
the key package error content type gives you an indication of why a key package (or a collection of them) got rejected 😭 this content type MUST be encoded using the Distinguished Encoding Rules (DER) [X.690], same as the receipt, because consistency is everything 💅
The key package error content type has the following syntax:
ct-key-package-error CONTENT-TYPE ::= {
TYPE KeyPackageError IDENTIFIED BY id-ct-KP-keyPackageError }
id-ct-KP-keyPackageError OBJECT IDENTIFIER ::= {
joint-iso-itu-t(2) country(16) us(840) organization(1)
gov(101) dod(2) infosec(1) formats(2)
key-package-content-types(78) 6 }
KeyPackageError ::= SEQUENCE {
version KeyPkgVersion DEFAULT v2,
errorOf [0] KeyPkgIdentifier OPTIONAL,
errorBy SIREntityName,
errorCode ErrorCodeChoice }
KeyPkgVersion ::= INTEGER { v1(1), v2(2) } (1 .. 65535)
KeyPkgIdentifier ::= CHOICE {
pkgID KeyPkgID,
attribute SingleAttribute {{ KeyPkgIdentifiers }} }
KeyPkgID ::= OCTET STRING
KeyPkgIdentifiers ATTRIBUTE ::= { ... }
ErrorCodeChoice ::= CHOICE {
enum EnumeratedErrorCode,
oid OBJECT IDENTIFIER }
EnumeratedErrorCode ::= ENUMERATED {
decodeFailure (1),
badContentInfo (2),
badSignedData (3),
badEncapContent (4),
badCertificate (5),
badSignerInfo (6),
badSignedAttrs (7),
badUnsignedAttrs (8),
missingContent (9),
noTrustAnchor (10),
notAuthorized (11),
badDigestAlgorithm (12),
badSignatureAlgorithm (13),
unsupportedKeySize (14),
unsupportedParameters (15),
signatureFailure (16),
insufficientMemory (17),
incorrectTarget (23),
missingSignature (29),
resourcesBusy (30),
versionNumberMismatch (31),
revokedCertificate (33),
-- Error codes with values <= 33 are aligned with [RFC5934]
ambiguousDecrypt (60),
noDecryptKey (61),
badEncryptedData (62),
badEnvelopedData (63),
badAuthenticatedData (64),
badAuthEnvelopedData (65),
badKeyAgreeRecipientInfo (66),
badKEKRecipientInfo (67),
badEncryptContent (68),
badEncryptAlgorithm (69),
missingCiphertext (70),
decryptFailure (71),
badMACAlgorithm (72),
badAuthAttrs (73),
badUnauthAttrs (74),
invalidMAC (75),
mismatchedDigestAlg (76),
missingCertificate (77),
tooManySigners (78),
missingSignedAttributes (79),
derEncodingNotUsed (80),
missingContentHints (81),
invalidAttributeLocation (82),
badMessageDigest (83),
badKeyPackage (84),
badAttributes (85),
attributeComparisonFailure (86),
unsupportedSymmetricKeyPackage (87),
unsupportedAsymmetricKeyPackage (88),
constraintViolation (89),
ambiguousDefaultValue (90),
noMatchingRecipientInfo (91),
unsupportedKeyWrapAlgorithm (92),
badKeyTransRecipientInfo (93),
other (127),
... -- Expect additional error codes -- }The KeyPackageError fields are used like this:
versiontells you which version of the key package error content structure you're looking at 🌈 for this version of the spec, the default value, v2, MUST be used. v1 was defined earlier, but its use is deprecated, so same energy as the receipt 🙈errorOfis OPTIONAL 🧩 it gives the identifier of the keying material the error is about. It's left out if the receiver or intermediary can't parse the received data to figure out the package identifier, since encryption can stop an intermediary from grabbing any of the identifiers. There are two ways to identify the keying material; see KeyPkgIdentifier as described in Section 4. The value MUST exactly match the value of the key-package-identifier-and-receipt-request attribute in the received key package or collection. That attribute is described in Section 3.errorByidentifies the entity that received the key package. The entity is named by an SIR entity name, as specified in Section 2 🫶errorCodeholds a code that shows the reason for the error 💀 it's either an enumerated error code from the list below, or an extended error code represented by an object identifier. The enumerated error code option MUST be supported. The object identifier error code MAY be supported.decodeFailuremeans the key package intermediary or receiver couldn't decode the package successfully 😭 the specified content type and the provided content don't match.badContentInfomeans the ContentInfo syntax is invalid, or the contentType inside the ContentInfo is unknown or unsupported.badSignedDatameans the SignedData syntax is invalid, the version is unknown or unsupported, or more than one entry is present in digestAlgorithms.badEncapContentmeans the EncapsulatedContentInfo syntax is invalid within a SignedData or an AuthenticatedData, or the EncryptedContentInfo syntax is invalid within an AuthEnvelopedData.badCertificatemeans the syntax for one or more certificates in CertificateSet, or elsewhere, is invalid or unsupported.badSignerInfomeans the SignerInfo syntax is invalid, or the version is unknown or unsupported.badSignedAttrsmeans the signedAttrs syntax within SignerInfo is invalid.badUnsignedAttrsmeans the unsignedAttrs within SignerInfo contains one or more attributes. Unrecognized attributes get ignored, so this code is used when the object identifier for the attribute is recognized but the value is malformed or internally inconsistent. This code can also be used when policy prohibits an implementation from supporting unsigned attributes 🤓missingContentmeans the optional eContent is missing in EncapsulatedContentInfo, which is required when including an asymmetric key package, a symmetric key package, and an encrypted key package. This error can come from problems located in SignedData or AuthenticatedData.
Note that the CMS EncapsulatedContentInfo eContent field is optional [RFC5652]. However, [RFC5958], [RFC6031], and [RFC6032] require that the eContent be present. That's a plot twist, iykyk 🎭
noTrustAnchor🙈 means thesubjectKeyIdentifierdoesn't identify the public key of a trust anchor, or of a certification path that ends at an installed trust anchor.notAuthorized🚫 means thesidinSignerInfoleads to an installed trust anchor, but that trust anchor isn't an authorized signer for the content type that was received.badDigestAlgorithmmeans thedigestAlgorithminSignerInfo,SignedData, orAuthenticatedDatais unknown or unsupported.badSignatureAlgorithmmeans thesignatureAlgorithminSignerInfois unknown or unsupported.unsupportedKeySizemeans thesignatureAlgorithminSignerInfois known and supported, but the digital signature couldn't be validated because the signer used a key size that isn't supported. It also covers the case where the algorithm used inEnvelopedData,AuthenticatedData, orAuthEnvelopedDatato generate the key-encryption key is known and supported, but the originator used an unsupported key size. 📏unsupportedParametersmeans thesignatureAlgorithminSignerInfois known, but the digital signature couldn't be validated because the signer used unsupported parameters. It also covers the case where the algorithm used inEnvelopedData,AuthenticatedData, orAuthEnvelopedDatato generate the key-encryption key is known and supported, but the originator used unsupported parameters. ⚙️signatureFailuremeans thesignatureAlgorithminSignerInfois known and supported, but the digital signature in thesignaturefield ofSignerInfocouldn't be validated. 💔insufficientMemorymeans the key package couldn't be processed because the intermediary or receiver didn't have enough memory to store the keying material. 🧠incorrectTargetmeans the receiver isn't the intended recipient. 🎯missingSignaturemeans the receiver requires the key package to be signed or authenticated with a Message Authentication Code (MAC), but the received key package wasn't signed or authenticated. ✍️resourcesBusymeans the resources needed to process the key package aren't available right now, but they might be available later. ⏳versionNumberMismatchmeans the version number in a received key package isn't acceptable. 🔢revokedCertificatemeans one or more of the certificates needed to properly process the key package has been revoked. 🚫📜ambiguousDecryptmeans theEncryptedDatacontent type was used, and the key package receiver couldn't figure out which keying material to use for decryption. 🤷♀️noDecryptKeymeans the receiver doesn't have the key named in thecontent-decryption-key-identifierattribute (see [RFC6032]). 🔑badEncryptedDatameans theEncryptedDatasyntax is invalid, or the version is unknown or unsupported.badEnvelopedDatameans theEnvelopedDatasyntax is invalid, or the version is unknown or unsupported.badAuthenticatedDatameans theAuthenticatedDatasyntax is invalid, or the version is unknown or unsupported.badAuthEnvelopedDatameans theAuthEnvelopedDatasyntax is invalid, or the version is unknown or unsupported.badKeyAgreeRecipientInfomeans theKeyAgreeRecipientInfosyntax is invalid, or the version is unknown or unsupported.badKEKRecipientInfomeans theKEKRecipientInfosyntax is invalid, or the version is unknown or unsupported.badEncryptContentmeans theEncryptedContentInfosyntax is invalid, or the content type carried within thecontentTypeis unknown or unsupported.badEncryptAlgorithmmeans the encryption algorithm identified bycontentEncryptionAlgorithminEncryptedContentInfois unknown or unsupported. This can happen withEncryptedData,EnvelopedData, orAuthEnvelopedData. 🔐missingCiphertextmeans the optionalencryptedContentis missing fromEncryptedContentInfo. It's required when including an asymmetric key package, a symmetric key package, or an encrypted key package. 👻decryptFailuremeans theencryptedContentinEncryptedContentInfodidn't decrypt properly. 💥badMACAlgorithmmeans the MAC algorithm identified byMessageAuthenticationCodeAlgorithminAuthenticatedDatais unknown or unsupported.badAuthAttrsmeans theauthAttrssyntax withinAuthenticatedDataorAuthEnvelopedDatais invalid. Unrecognized attributes just get ignored, so this code shows up when the object identifier for the attribute is recognized, but the value is malformed or internally inconsistent. 🧩badUnauthAttrsmeans theunauthAttrssyntax withinAuthenticatedDataorAuthEnvelopedDatais invalid. Same deal as above: unrecognized attributes are ignored, so this code is used when the object identifier is recognized, but the value is malformed or internally inconsistent. 🧩invalidMACmeans the message authentication code value withinAuthenticatedDataorAuthEnvelopedDatadidn't validate properly. ❌mismatchedDigestAlgmeans the digest algorithm listed in thedigestAlgorithmsfield ofSignedDatadoesn't match the digest algorithm used in the signature algorithm. 🙅♀️missingCertificatemeans a signature couldn't be verified using a trust anchor or a certificate from thecertificatesfield withinSignedData. This code can also mean a needed certificate is missing when processingEnvelopedData,AuthEnvelopedData, orAuthenticatedData. 📭tooManySignersmeansSignedDatacontent contained more than oneSignerInfofor a content type that only allows one signer. 👯♀️missingSignedAttributesmeans aSignedInfowithinSignedDatacontent didn't have any signed attributes. At a minimum, the content-type and message-digest must be present, as per [RFC5652]. This code can also mean required authenticated attributes are missing when processingAuthEnvelopedDataorAuthenticatedData. 🫥derEncodingNotUsedmeans the content used BER encoding, or some other encoding, where DER encoding was required. 🍝missingContentHintsmeansSignedDatacontent encapsulates something other than a key package or an encrypted key package, but the content-hints attribute [RFC2634] isn't included. This code can also mean the content-hints attribute was missing when processingAuthEnvelopedDataorAuthenticatedData. 💡invalidAttributeLocationmeans an attribute showed up in a place it isn't allowed. 📍badMessageDigestmeans the value of the message-digest attribute [RFC5652] didn't match the calculated value. 🧮badKeyPackagemeans theSymmetricKeyPackage[RFC6031] orAsymmetricKeyPackage[RFC5958] syntax is invalid, or the version is unknown. 📦badAttributesmeans an attribute collection either had multiple instances of the same attribute type that only allows one instance, or had an attribute instance with multiple values in an attribute that only allows one value. 🙃attributeComparisonFailuremeans multiple instances of an attribute failed the comparison rules for that attribute type. ⚖️unsupportedSymmetricKeyPackagemeans the implementation doesn't support symmetric key packages [RFC6031]. 🚫unsupportedAsymmetricKeyPackagemeans the implementation doesn't support asymmetric key packages [RFC5958]. 🚫constraintViolationmeans one or more of the attributes has a value that isn't in the set of values authorized for the signer [RFC6010]. In other words, the value conflicts with the constraints placed on the signer. 🚧ambiguousDefaultValuemeans one or more of the attributes that are part of the signer's constraints was left out of the key package, and the constraint allows more than one value. So the right default value for that attribute can't be figured out. 🤔noMatchingRecipientInfomeans a recipientInfo couldn't be found for the recipient. This can happen with aktriorkarifound inEncryptedData,EnvelopedData, orAuthEnvelopedData. 📬unsupportedKeyWrapAlgorithmmeans the key wrap algorithm isn't supported. 🎁badKeyTransRecipientInfomeans theKeyTransRecipientInfosyntax is invalid, or the version is unknown or unsupported.othermeans the key package couldn't be processed, but the reason isn't covered by any of the assigned status codes. Use of this status code SHOULD be avoided. 🙅♀️
The key package error content type MUST be signed if the entity generating it is capable of signing it. For example, a device can't sign when it's in the early stages of deployment and hasn't been set up with a private signing key, or when it has an internal error that stops it from using its private signing key. 🛠️ When it's signed, the key package error MUST be encapsulated in a CMS SignedData content type so it carries the signature of the party reporting the error. ✍️ When it's encrypted, the key package error MUST be encapsulated in a CMS EnvelopedData content type, a CMS EncryptedData content type, or a CMS AuthEnvelopedData content type. 🔒 When a key package error is both signed and encrypted, it MUST be signed before it gets encrypted. 🫶
All devices that generate signed key package error reports MUST store their own certificate, or have a way to get the key identifier of their public key. 💜 If memory is a concern, the public key identifier can be computed from the public key. 🧚
If the error report signer has a real-time clock, the binary-signing-time attribute [RFC6019] SHOULD be included in the key package error, so it shows the exact date and time it was made ⏰💖
6. Protecting the KeyPackageReceipt and KeyPackageError ✨
Okay so CMS protecting content types, [RFC5652] and [RFC5083], can be used to keep KeyPackageReceipt and KeyPackageError secure 🔐 Here's the lineup:
SignedDatacan be used to apply a digital signature 🖋️EncryptedDatacan be used to encrypt the content type with simple symmetric encryption, where the sender and the receiver already share the necessary encryption key 🗝️EnvelopedDatacan be used to encrypt the content type with symmetric encryption, where the sender and the receiver do not already share the necessary encryption key 🎀AuthenticatedDatacan be used to integrity protect the content type with message authentication algorithms that support authenticated encryption, where key management information is handled in a manner similar toEnvelopedData🫶AuthEnvelopedDatacan be used to protect the content types with algorithms that support authenticated encryption, where key management information is handled in a manner similar toEnvelopedData💅
7. Using the application/cms Media Type 🦋
The media type and parameters for carrying a key package receipt or a key package error content type are specified in [RFC7193] 📨
8. IANA Considerations 🌸
IANA has updated the reference for the following registration in the "SMI Security for S/MIME Module Identifier (1.2.840.113549.1.9.16.0)" registry:
63 id-mod-keyPkgReceiptAndErrV2 [RFC7191]9. Security Considerations 🚨
Okay this section is SO important, bestie 😭 The key package receipt and key package error contents are not necessarily protected. These content types can be combined with a security protocol to protect the contents of the package 🔒
The KeyPkgReceiptReq structure includes a receiptsFrom list and a receiptsTo list. Both lists contain SIREntityNames. The syntax does not specify a limit on the number of SIREntityNames that may be included in either of these lists. Also, there is purposefully no requirement that the receiptTo entries have any relation to the sender of the key package. To avoid these features being used as part of a denial-of-service amplification, receipts should only be returned for key packages with a valid signature from a trusted signer 🛡️
If an implementation is willing to accept key packages from more than one source, then there is a possibility that the same key package identifier could be used by more than one source. As a result, there is the potential for a receipt for one key package to be confused with the receipt for another, potentially leading to confusion about the keying material that is available to the recipient 🥺 In environments with multiple key sources, a convention for assignment of key package identifiers can avoid this potential confusion altogether ✨
In some situations, returning very detailed error information can provide an attacker with insight into the security processing. Where this is a concern, the implementation should return the most generic error code that is appropriate. However, detailed error codes are very helpful during development, debugging, and interoperability testing. For this reason, implementations may want to have a way to configure the use of a generic error code or a detailed one 🙈
10. Acknowledgements 💜
Many thanks to Radia Perlman, Sean Turner, Jim Schaad, and Carl Wallace for their insightful review 🥰 Thanks to Robert Sparks for improved wording 🌈
11. References 📚
11.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2634] Hoffman, P., Ed., "Enhanced Security Services for S/MIME",
RFC 2634, June 1999.
[RFC4073] Housley, R., "Protecting Multiple Contents with the
Cryptographic Message Syntax (CMS)", RFC 4073, May 2005.
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
Housley, R., and W. Polk, "Internet X.509 Public Key
Infrastructure Certificate and Certificate Revocation List
(CRL) Profile", RFC 5280, May 2008.
[RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70,
RFC 5652, September 2009.
[RFC5912] Hoffman, P. and J. Schaad, "New ASN.1 Modules for the
Public Key Infrastructure Using X.509 (PKIX)", RFC 5912,
June 2010.
[RFC5958] Turner, S., "Asymmetric Key Packages", RFC 5958, August
2010.
[RFC6010] Housley, R., Ashmore, S., and C. Wallace, "Cryptographic
Message Syntax (CMS) Content Constraints Extension", RFC
6010, September 2010.
[RFC6019] Housley, R., "BinaryTime: An Alternate Format for
Representing Date and Time in ASN.1", RFC 6019, September
2010.
[RFC6031] Turner, S. and R. Housley, "Cryptographic Message Syntax
(CMS) Symmetric Key Package Content Type", RFC 6031,
December 2010.
[RFC6032] Turner, S. and R. Housley, "Cryptographic Message Syntax
(CMS) Encrypted Key Package Content Type", RFC 6032,
December 2010.
[RFC6268] Schaad, J. and S. Turner, "Additional New ASN.1 Modules
for the Cryptographic Message Syntax (CMS) and the Public
Key Infrastructure Using X.509 (PKIX)", RFC 6268, July
2011.
[RFC7193] Turner, S., Housley, R., and J. Schaad, "The
application/cms Media Type", RFC 7193, April 2014.
[X.680] ITU-T Recommendation X.680 (2002) | ISO/IEC 8824-1:2002.
Information Technology - Abstract Syntax Notation One.
[X.681] ITU-T Recommendation X.681 (2002) | ISO/IEC 8824-2:2002.
Information Technology - Abstract Syntax Notation One:
Information Object Specification.
[X.682] ITU-T Recommendation X.682 (2002) | ISO/IEC 8824-3:2002.
Information Technology - Abstract Syntax Notation One:
Constraint Specification.
[X.683] ITU-T Recommendation X.683 (2002) | ISO/IEC 8824-4:2002.
Information Technology - Abstract Syntax Notation One:
Parameterization of ASN.1 Specifications.
[X.690] ITU-T Recommendation X.690 (2002) | ISO/IEC 8825- 1:2002.
Information Technology - ASN.1 encoding rules:
Specification of Basic Encoding Rules (BER), Canonical
Encoding Rules (CER) and Distinguished Encoding Rules
(DER).11.2. Informative References
[RFC5083] Housley, R., "Cryptographic Message Syntax (CMS)
Authenticated-Enveloped-Data Content Type", RFC 5083,
November 2007.
[RFC5934] Housley, R., Ashmore, S., and C. Wallace, "Trust Anchor
Management Protocol (TAMP)", RFC 5934, August 2010.Appendix A. ASN.1 Module ✨
okay bestie, this is the big ASN.1 module 🧚 it's the normative definitions for all the structures in this spec, written in ASN.1 as defined in [X.680], [X.681], [X.682], and [X.683]. it's giving "source of truth" energy, so the code below is exactly what implementers work from 💜
KeyPackageReceiptAndErrorModuleV2
{ iso(1) member-body(2) us(840) rsadsi(113549) pkcs(1) pkcs-9(9)
smime(16) modules(0) id-mod-keyPkgReceiptAndErrV2(63) }
DEFINITIONS IMPLICIT TAGS ::=
BEGIN
-- EXPORTS ALL
IMPORTS
-- FROM New SMIME ASN.1 [RFC6268]
CONTENT-TYPE
FROM CryptographicMessageSyntax-2010
{ iso(1) member-body(2) us(840) rsadsi(113549)
pkcs(1) pkcs-9(9) smime(16) modules(0) id-mod-cms-2009(58) }
-- From New PKIX ASN.1 [RFC5912]
ATTRIBUTE, SingleAttribute {}
FROM PKIX-CommonTypes-2009
{ iso(1) identified-organization(3) dod(6) internet(1)
security(5) mechanisms(5) pkix(7) id-mod(0)
id-mod-pkixCommon-02(57) }
DistinguishedName
FROM PKIX1Explicit-2009
{ iso(1) identified-organization(3) dod(6) internet(1)
security(5) mechanisms(5) pkix(7) id-mod(0)
id-mod-pkix1-explicit-02(51)}
;
---
--- Key Package Version Number (revised from [RFC6031])
---
KeyPkgVersion ::= INTEGER { v1(1), v2(2) } (1 .. 65535)
--
-- SIR Entity Name
--
SIREntityNames ::= SEQUENCE SIZE (1..MAX) OF SIREntityName
SIREntityNameTypes SIR-ENTITY-NAME ::= {
siren-dn,
... -- Expect additional SIR Entity Name types -- }
SIR-ENTITY-NAME ::= CLASS {
&sIRENType OBJECT IDENTIFIER UNIQUE,
&SIRENValue
} WITH SYNTAX {
SYNTAX &SIRENValue IDENTIFIED BY &sIRENType }
SIREntityName ::= SEQUENCE {
sirenType SIR-ENTITY-NAME.&sIRENType({SIREntityNameTypes}),
sirenValue OCTET STRING (CONTAINING
SIR-ENTITY-NAME.&SIRENValue(
{SIREntityNameTypes}{@sirenType}) ) }
siren-dn SIR-ENTITY-NAME ::= {
SYNTAX DistinguishedName
IDENTIFIED BY id-dn }
id-dn OBJECT IDENTIFIER ::= {
joint-iso-ccitt(2) country(16) us(840) organization(1)
gov(101) dod(2) infosec(1) sir-name-types(16) 0 }
--
-- Attribute Definitions
--
aa-keyPackageIdentifierAndReceiptRequest ATTRIBUTE ::= {
TYPE KeyPkgIdentifierAndReceiptReq
IDENTIFIED BY id-aa-KP-keyPkgIdAndReceiptReq }
id-aa-KP-keyPkgIdAndReceiptReq OBJECT IDENTIFIER ::= {
joint-iso-itu-t(2) country(16) us(840) organization(1)
gov(101) dod(2) infosec(1) attributes(5) 65 }
KeyPkgIdentifierAndReceiptReq ::= SEQUENCE {
pkgID KeyPkgID,
receiptReq KeyPkgReceiptReq OPTIONAL }
KeyPkgID ::= OCTET STRING
KeyPkgReceiptReq ::= SEQUENCE {
encryptReceipt BOOLEAN DEFAULT FALSE,
receiptsFrom [0] SIREntityNames OPTIONAL,
receiptsTo SIREntityNames }
--
-- Content Type Definitions
--
KeyPackageContentTypes CONTENT-TYPE ::= {
ct-key-package-receipt |
ct-key-package-error,
... -- Expect additional content types -- }
-- Key Package Receipt CMS Content Type
ct-key-package-receipt CONTENT-TYPE ::= {
TYPE KeyPackageReceipt
IDENTIFIED BY id-ct-KP-keyPackageReceipt }
id-ct-KP-keyPackageReceipt OBJECT IDENTIFIER ::= {
joint-iso-itu-t(2) country(16) us(840) organization(1)
gov(101) dod(2) infosec(1) formats(2)
key-package-content-types(78) 3 }
KeyPackageReceipt ::= SEQUENCE {
version KeyPkgVersion DEFAULT v2,
receiptOf KeyPkgIdentifier,
receivedBy SIREntityName }
KeyPkgIdentifier ::= CHOICE {
pkgID KeyPkgID,
attribute SingleAttribute {{ KeyPkgIdentifiers }} }
KeyPkgIdentifiers ATTRIBUTE ::= { ... }
-- Key Package Receipt CMS Content Type
ct-key-package-error CONTENT-TYPE ::= {
TYPE KeyPackageError IDENTIFIED BY id-ct-KP-keyPackageError }
id-ct-KP-keyPackageError OBJECT IDENTIFIER ::= {
joint-iso-itu-t(2) country(16) us(840) organization(1)
gov(101) dod(2) infosec(1) formats(2)
key-package-content-types(78) 6 }
KeyPackageError ::= SEQUENCE {
version KeyPkgVersion DEFAULT v2,
errorOf [0] KeyPkgIdentifier OPTIONAL,
errorBy SIREntityName,
errorCode ErrorCodeChoice }
ErrorCodeChoice ::= CHOICE {
enum EnumeratedErrorCode,
oid OBJECT IDENTIFIER }
EnumeratedErrorCode ::= ENUMERATED {
decodeFailure (1),
badContentInfo (2),
badSignedData (3),
badEncapContent (4),
badCertificate (5),
badSignerInfo (6),
badSignedAttrs (7),
badUnsignedAttrs (8),
missingContent (9),
noTrustAnchor (10),
notAuthorized (11),
badDigestAlgorithm (12),
badSignatureAlgorithm (13),
unsupportedKeySize (14),
unsupportedParameters (15),
signatureFailure (16),
insufficientMemory (17),
incorrectTarget (23),
missingSignature (29),
resourcesBusy (30),
versionNumberMismatch (31),
revokedCertificate (33),
-- Error codes with values <= 33 are aligned with [RFC5934]
ambiguousDecrypt (60),
noDecryptKey (61),
badEncryptedData (62),
badEnvelopedData (63),
badAuthenticatedData (64),
badAuthEnvelopedData (65),
badKeyAgreeRecipientInfo (66),
badKEKRecipientInfo (67),
badEncryptContent (68),
badEncryptAlgorithm (69),
missingCiphertext (70),
decryptFailure (71),
badMACAlgorithm (72),
badAuthAttrs (73),
badUnauthAttrs (74),
invalidMAC (75),
mismatchedDigestAlg (76),
missingCertificate (77),
tooManySigners (78),
missingSignedAttributes (79),
derEncodingNotUsed (80),
missingContentHints (81),
invalidAttributeLocation (82),
badMessageDigest (83),
badKeyPackage (84),
badAttributes (85),
attributeComparisonFailure (86),
unsupportedSymmetricKeyPackage (87),
unsupportedAsymmetricKeyPackage (88),
constraintViolation (89),
ambiguousDefaultValue (90),
noMatchingRecipientInfo (91),
unsupportedKeyWrapAlgorithm (92),
badKeyTransRecipientInfo (93),
other (127),
... -- Expect additional error codes -- }
ENDAuthor's Address 💌
Russ Housley
Vigil Security, LLC
918 Spring Knoll Drive
Herndon, VA 20170
USA
EMail: housley@vigilsec.com📦 where this page comes from
- ietf: rfc7191 2014-04
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms