diff --git a/CHANGELOG.md b/CHANGELOG.md index b7df0ec..9910916 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -46,6 +46,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed +- `importPkcs8Der` accepts a `OneAsymmetricKey` (RFC 5958 §2 / RFC 8410 §7) that + carries both `attributes [0]` and `publicKey [1]`. The parser capped at four + elements, so a five-element v2 key that OpenSSL and Node WebCrypto both accept + returned `malformed`. The tail is now validated structurally rather than by + ASN.1 class alone: `attributes [0]` must be a constructed `SET OF`, an optional + `publicKey [1]` must be a primitive BIT STRING after it, the version is coupled + to the public key's presence (`v2` iff present), and well-formed unknown + extension additions are tolerated per the type's X.680 extensibility marker. +- SEC1 `ECPrivateKey` parsing rejects a version other than 1, comparing content + octets (RFC 5915 §3, "version SHALL be ... one"). Only the tag was checked, so + version 0 or 2 was deferred to the WebCrypto backend as a misleading error. +- PBES2 decryption no longer rejects a PBKDF2 salt shorter than eight bytes. RFC + 8018 §4.1 makes the eight-octet minimum a "should" for salt _selection_ and + says the salt need not be checked on receipt, so `openssl pkcs8 -saltlen 4` + could not be decrypted. The encrypt path keeps the minimum. + (https://github.com/kjanat/micro509/pull/85) - Distinguished-name encoding enforces the RFC 5280 Appendix A.1 attribute constraints: no attribute value may be empty (`SIZE (1..ub-…)`), and `commonName`/`organization`/`organizationalUnit`/`title`/`serialNumber` cap at diff --git a/docs/rfc/rfc2985.txt b/docs/rfc/rfc2985.txt new file mode 100644 index 0000000..bf9fd84 --- /dev/null +++ b/docs/rfc/rfc2985.txt @@ -0,0 +1,2355 @@ + + + + + + +Network Working Group M. Nystrom +Request for Comments: 2985 B. Kaliski +Category: Informational RSA Security + November 2000 + + + PKCS #9: Selected Object Classes and Attribute Types + Version 2.0 + +Status of this Memo + + This memo provides information for the Internet community. It does + not specify an Internet standard of any kind. Distribution of this + memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2000). All Rights Reserved. + +Abstract + + This memo represents a republication of PKCS #9 v2.0 from RSA + Laboratories' Public-Key Cryptography Standards (PKCS) series, and + change control is retained within the PKCS process. The body of this + document, except for the security considerations section, is taken + directly from that specification. + + This memo provides a selection of object classes and attribute types + for use in conjunction with public-key cryptography and Lightweight + Directory Access Protocol (LDAP) accessible directories. It also + includes ASN.1 syntax for all constructs. + +Table of Contents + + 1. Introduction ................................................. 2 + 2. Definitions, notation and document convention ................ 2 + 2.1 Definitions ................................................. 2 + 2.2 Notation and document convention ............................ 3 + 3. Overview ..................................................... 4 + 4. Auxiliary object classes ..................................... 5 + 4.1 The "pkcsEntity" auxiliary object class ..................... 5 + 4.2 The "naturalPerson" auxiliary object class .................. 6 + 5. Selected attribute types ..................................... 6 + 5.1 Attribute types for use with the "pkcsEntity" object class .. 6 + 5.2 Attribute types for use with the "naturalPerson" object class 7 + 5.3 Attribute types for use in PKCS #7 data .................... 12 + 5.4 Attribute types for use in PKCS #10 certificate requests ... 16 + + + + +Nystrom & Kaliski Informational [Page 1] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + 5.5 Attribute types for use in PKCS #12 "PFX" PDUs or PKCS #15 + tokens ..................................................... 17 + 5.6 Attributes defined in S/MIMIE .............................. 18 + 6. Matching rules .............................................. 19 + 6.1 Case ignore match .......................................... 19 + 6.2 Signing time match ......................................... 20 + 7. Security Considerations ..................................... 20 + 8. Authors' Addresses .......................................... 21 + A. ASN.1 module ................................................ 22 + B. BNF schema summary .......................................... 30 + B.1 Syntaxes ................................................... 30 + B.2 Object classes ............................................. 31 + B.3 Attribute types ............................................ 32 + B.4 Matching rules ............................................. 36 + C. Intellectual property considerations ........................ 37 + D. Revision history ............................................ 37 + E. References .................................................. 39 + F. Contact information & About PKCS ............................ 41 + Full Copyright Statement ........................................ 41 + +1. Introduction + + This document defines two new auxiliary object classes, pkcsEntity + and naturalPerson, and selected attribute types for use with these + classes. It also defines some attribute types for use in conjunction + with PKCS #7 [14] (and S/MIME CMS [3]) digitally signed messages, + PKCS #10 [16] certificate-signing requests, PKCS #12 [17] personal + information exchanges and PKCS #15 [18] cryptographic tokens. + Matching rules for use with these attributes are also defined, + whenever necessary. + +2. Definitions, notation and document conventions + + 2.1 Definitions + + For the purposes of this document, the following definitions apply. + + ASN.1 Abstract Syntax Notation One, as defined in [5]. + + Attributes An ASN.1 type that specifies a set of attributes. + Each attribute contains an attribute type (specified + by object identifier) and one or more attribute + values. Some attribute types are restricted in their + definition to have a single value; others may have + multiple values. This type is defined in [7]. + + + + + + +Nystrom & Kaliski Informational [Page 2] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + CertificationRequestInfo + An ASN.1 type that specifies a subject name, a public + key, and a set of attributes. This type is defined + in [16]. + + ContentInfo An ASN.1 type that specifies content exchanged + between entities. The contentType field, which has + type OBJECT IDENTIFIER, specifies the content type, + and the content field, whose type is defined by the + contentType field, contains the content value. This + type is defined in [14] and [3]. + + PrivateKeyInfo A type that specifies a private key and a set of + extended attributes. This type and the associated + EncryptedPrivateKeyInfo type are defined in [15]. + + SignerInfo A type that specifies per-signer information in the + signed-data content type, including a set of + attributes authenticated by the signer, and a set of + attributes not authenticated by the signer. This + type is defined in [14] and [3]. + + DER Distinguished Encoding Rules for ASN.1, as defined in + [6]. + + UCS Universal Multiple-Octet Coded Character Set, as + defined in [11]. + + UTF8String UCS Transformation Format encoded string. The UTF-8 + encoding is defined in [11]. + + 2.2 Notation and document conventions + + In this document, all attribute type and object class definitions are + written in the ASN.1 value notation defined in [5]. Appendix B + contains most of these definitions written in the augmented BNF + notation defined in [2] as well. This has been done in an attempt to + simplify the task of integrating this work into LDAP [22] development + environments. + + The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [1]. + + + + + + + + +Nystrom & Kaliski Informational [Page 3] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + +3. Overview + + This document specifies two new auxiliary object classes, pkcsEntity + and naturalPerson, and some new attribute types and matching rules. + All ASN.1 object classes, attributes, matching rules and types are + exported for use in other environments. + + Attribute types defined in this document that are useful in + conjunction with storage of PKCS-related data and the pkcsEntity + object class includes PKCS #12 PFX PDUs, PKCS #15 tokens and + encrypted private keys. + + Attribute types defined in this document that are useful in + conjunction with PKCS #10 certificate requests and the naturalPerson + object class includes electronic-mail address, pseudonym, + unstructured name, and unstructured address. + + Attribute types defined in this document that are useful in PKCS #7 + digitally signed messages are content type, message digest, signing + time, sequence number, random nonce and countersignature. The + attributes would be used in the authenticatedAttributes and + unauthenticatedAttributes fields of a SignerInfo or an + AuthenticatedData ([3]) value. + + Attribute types that are useful especially in PKCS #10 certification + requests are the challenge password and the extension-request + attribute. The attributes would be used in the attributes field of a + CertificationRequestInfo value. + + Note - The attributes types (from [8]) in Table 1, and probably + several others, might also be helpful in PKCS #10, PKCS #12 and PKCS + #15-aware applications. + + + + + + + + + + + + + + + + + + + +Nystrom & Kaliski Informational [Page 4] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + businessCategory preferredDeliveryMethod + commonName presentationAddress + countryName registeredAddress + description roleOccupant + destinationIndicator serialNumber + facsimileTelephoneNumber stateOrProvinceName + iSDNAddress streetAddress + localityName supportedApplicationContext + member surname + objectClass telephoneNumber + organizationName teletexTerminalIdentifier + physicalDeliveryOfficeName telexNumber + postalAddress title + postalCode x121Address + postOfficeBox + + Table 1: ISO/IEC 9594-6 attribute types useful in PKCS documents + +4. Auxiliary object classes + + This document defines two new auxiliary object classes: pkcsEntity + and naturalPerson. + + 4.1 The pkcsEntity auxiliary object class + + The pkcsEntity object class is a general-purpose auxiliary object + class that is intended to hold attributes about PKCS-related + entities. It has been designed for use within directory services + based on the LDAP protocol [22] and the X.500 family of protocols, + where support for PKCS-defined attributes is considered useful. + + pkcsEntity OBJECT-CLASS ::= { + SUBCLASS OF { top } + KIND auxiliary + MAY CONTAIN { PKCSEntityAttributeSet } + ID pkcs-9-oc-pkcsEntity + } + + PKCSEntityAttributeSet ATTRIBUTE ::= { + pKCS7PDU | + userPKCS12 | + pKCS15Token | + encryptedPrivateKeyInfo, + ... -- For future extensions + } + + Attributes in the PKCSEntityAttributeSet are defined in Section 5. + + + + +Nystrom & Kaliski Informational [Page 5] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + 4.2 The naturalPerson auxiliary object class + + The naturalPerson object class is a general-purpose auxiliary object + class that is intended to hold attributes about human beings. It has + been designed for use within directory services based on the LDAP + protocol [22] and the X.500 family of protocols, where support for + these attributes is considered useful. + + naturalPerson OBJECT-CLASS ::= { + SUBCLASS OF { top } + KIND auxiliary + MAY CONTAIN { NaturalPersonAttributeSet } + ID pkcs-9-oc-naturalPerson + } + + NaturalPersonAttributeSet ATTRIBUTE ::= { + emailAddress | + unstructuredName | + unstructuredAddress | + dateOfBirth | + placeOfBirth | + gender | + countryOfCitizenship | + countryOfResidence | + pseudonym | + serialNumber, + ... -- For future extensions + } + + Attributes in the NaturalPersonAttributeSet are defined in Section 5. + +5. Selected attribute types + + 5.1 Attribute types for use with the "pkcsEntity" object class + + 5.1.1 PKCS #7 PDU + + PKCS #7 provides several formats for enveloped, signed and otherwise + protected data. When such information is stored in a directory + service, the pKCS7PDU attribute may be used. + + pKCS7PDU ATTRIBUTE ::= { + WITH SYNTAX ContentInfo + ID pkcs-9-at-pkcs7PDU + } + + + + + + +Nystrom & Kaliski Informational [Page 6] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + 5.1.2 PKCS #12 token + + PKCS #12 provides a format for exchange of personal identity + information. When such information is stored in a directory service, + the userPKCS12 attribute should be used. + + userPKCS12 ATTRIBUTE ::= { + WITH SYNTAX PFX + ID pkcs-9-at-userPKCS12 + } + + This type was originally defined in [20]. + + 5.1.3 PKCS #15 token + + PKCS #15 provides a format for cryptographic tokens. When software + variants of such tokens are stored in a directory service, the + pKCS15Token attribute should be used. + + pKCS15Token ATTRIBUTE ::= { + WITH SYNTAX PKCS15Token + ID pkcs-9-at-pkcs15Token + } + + 5.1.4 PKCS #8 encrypted private key information + + PKCS #8 provides a format for encrypted private keys. When such + information is stored in a directory service, the + encryptedPrivateKeyInfo attribute should be used. + + encryptedPrivateKeyInfo ATTRIBUTE ::= { + WITH SYNTAX EncryptedPrivateKeyInfo + ID pkcs-9-at-encryptedPrivateKeyInfo + } + + 5.2 Attribute types for use with the "naturalPerson" object class + + 5.2.1 Electronic-mail address + + The emailAddress attribute type specifies the electronic-mail address + or addresses of a subject as an unstructured ASCII string. The + interpretation of electronic-mail addresses is intended to be + specified by certificate issuers etc.; no particular interpretation + is required. + + + + + + + +Nystrom & Kaliski Informational [Page 7] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + emailAddress ATTRIBUTE ::= { + WITH SYNTAX IA5String (SIZE(1..pkcs-9-ub-emailAddress)) + EQUALITY MATCHING RULE pkcs9CaseIgnoreMatch + ID pkcs-9-at-emailAdress + } + + An electronic-mail address attribute can have multiple attribute + values. When comparing two email addresses, case is irrelevant. The + pkcs9CaseIgnoreMatch is defined in Section 6. + + Note - It is likely that other standards bodies overseeing + electronic-mail systems will, or have, registered electronic-mail + address attribute types specific to their system. The electronic- + mail address attribute type defined here was intended as a short-term + substitute for those specific attribute types, but is included here + for backwards-compatibility reasons. + + 5.2.2 Unstructured name + + The unstructuredName attribute type specifies the name or names of a + subject as an unstructured ASCII string. The interpretation of + unstructured names is intended to be specified by certificate issuers + etc.; no particular interpretation is required. + + unstructuredName ATTRIBUTE ::= { + WITH SYNTAX PKCS9String {pkcs-9-ub-unstructuredName} + EQUALITY MATCHING RULE pkcs9CaseIgnoreMatch + ID pkcs-9-at-unstructuredName + } + + PKCS9String { INTEGER : maxSize} ::= CHOICE { + ia5String IA5String (SIZE(1..maxSize)), + directoryString DirectoryString {maxSize} + } + + An unstructured-name attribute can have multiple attribute values. + When comparing two unstructured names, case is irrelevant. + + The PKCS9String type is defined as a choice of IA5String and + DirectoryString. Applications SHOULD use the IA5String type when + generating attribute values in accordance with this version of this + document, unless internationalization issues makes this impossible. + In that case, the UTF8String alternative of the DirectoryString + alternative is the preferred choice. PKCS #9-attribute processing + systems MUST be able to recognize and process all string types in + PKCS9String values. + + + + + +Nystrom & Kaliski Informational [Page 8] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + Note - Version 1.1 of this document defined unstructuredName as + having the syntax IA5String, but did contain a note explaining that + this might be changed to a CHOICE of different string types in future + versions. To better accommodate international names, this type has + been extended to also include a directory string in this version of + this document. Since [21] does not support a directory string type + containing IA5Strings, a separate syntax object identifier has been + defined (see [21] and Appendix B). + + 5.2.3 Unstructured address + + The unstructuredAddress attribute type specifies the address or + addresses of a subject as an unstructured directory string. The + interpretation of unstructured addresses is intended to be specified + by certificate issuers etc; no particular interpretation is required. + A likely interpretation is as an alternative to the postalAddress + attribute type defined in [8]. + + unstructuredAddress ATTRIBUTE ::= { + WITH SYNTAX DirectoryString {pkcs-9-ub-unstructuredAddress} + EQUALITY MATCHING RULE caseIgnoreMatch + ID pkcs-9-at-unstructuredAddress + } + + An unstructured-address attribute can have multiple attribute values. + The caseIgnoreMatch matching rule is defined in [8]. + + Note 1 - It is recommended to use the ASN.1 type TeletexString's + new-line character (hexadecimal code 0d) as a line separator in + multi-line addresses. + + Note 2 - Previous versions of this document defined + unstructuredAddress as having the following syntax: + + CHOICE { + teletexString TeletexString, + printableString PrintableString, + } + + But also mentioned the possibility of a future definition as follows: + + CHOICE { + teletexString TeletexString, + printableString PrintableString, + universalString UniversalString + } + + + + + +Nystrom & Kaliski Informational [Page 9] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + In this version of this document, the X.520 type DirectoryString has + been used in order to be more aligned with international standards + and current practice. When generating attribute values in accordance + with this version of this document, applications SHOULD use the + PrintableString alternative unless internationalization issues makes + this impossible. In those cases, the UTF8String alternative SHOULD + be used. PKCS #9-attribute processing systems MUST be able to + recognize and process all string types in DirectoryString values. + + 5.2.4 Date of birth + + The dateOfBirth attribute specifies the date of birth for the subject + it is associated with. + + dateOfBirth ATTRIBUTE ::= { + WITH SYNTAX GeneralizedTime + EQUALITY MATCHING RULE generalizedTimeMatch + SINGLE VALUE TRUE + ID pkcs-9-at-dateOfBirth + } + + dateOfBirth attributes must be single-valued. The + generalizedTimeMatch matching rule is defined in [8]. + + 5.2.5 Place of birth + + The placeOfBirth attribute specifies the place of birth for the + subject it is associated with. + + placeOfBirth ATTRIBUTE ::= { + WITH SYNTAX DirectoryString {pkcs-9-ub-placeOfBirth} + EQUALITY MATCHING RULE caseExactMatch + SINGLE VALUE TRUE + ID pkcs-9-at-placeOfBirth + } + + placeOfBirth attributes must be single-valued. The caseExactMatch + matching rule is defined in [8]. + + + + + + + + + + + + + +Nystrom & Kaliski Informational [Page 10] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + 5.2.6 Gender + + The gender attribute specifies the gender of the subject it is + associated with. + + gender ATTRIBUTE ::= { + WITH SYNTAX PrintableString (SIZE(1) ^ + FROM ("M" | "F" | "m" | "f")) + EQUALITY MATCHING RULE caseIgnoreMatch + SINGLE VALUE TRUE + ID pkcs-9-at-gender + } + + The letter "M" (or "m") represents "male" and the letter "F" (or "f") + represents "female". gender attributes must be single-valued. + + 5.2.7 Country of citizenship + + The countryOfCitizenship attribute specifies the (claimed) countries + of citizenship for the subject it is associated with. It SHALL be a + 2-letter acronym of a country in accordance with [4]. + + countryOfCitizenship ATTRIBUTE ::= { + WITH SYNTAX PrintableString (SIZE(2) ^ CONSTRAINED BY { + -- Must be a two-letter country acronym in accordance with + -- ISO/IEC 3166 --}) + EQUALITY MATCHING RULE caseIgnoreMatch + ID pkcs-9-at-countryOfCitizenship + } + + Attributes of this type need not be single-valued. + + 5.2.8 Country of residence + + The countryOfResidence attribute specifies the (claimed) country of + residence for the subject is associated with. It SHALL be a 2-letter + acronym of a country in accordance with [4]. + + countryOfResidence ATTRIBUTE ::= { + WITH SYNTAX PrintableString (SIZE(2) ^ CONSTRAINED BY { + -- Must be a two-letter country acronym in accordance with + -- ISO/IEC 3166 --}) + EQUALITY MATCHING RULE caseIgnoreMatch + ID pkcs-9-at-countryOfResidence + } + + Attributes of this type need not be single-valued, since it is + possible to be a resident of several countries. + + + +Nystrom & Kaliski Informational [Page 11] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + 5.2.9 Pseudonym + + The pseudonym attribute type shall contain a pseudonym of a subject. + The exact interpretation of pseudonyms is intended to be specified by + certificate issuers etc.; no particular interpretation is required. + + pseudonym ATTRIBUTE ::= { + WITH SYNTAX DirectoryString {pkcs-9-ub-pseudonym} + EQUALITY MATCHING RULE caseExactMatch + ID id-at-pseudonym + } + + Note - The pseudonym attribute has received an object identifier in + the joint-iso-itu-t object identifier tree. + + The caseExactMatch matching rule is defined in [8]. + + 5.2.10 Serial number + + The serialNumber attribute is defined in [8]. + + 5.3 Attribute types for use in PKCS #7 data + + 5.3.1 Content type + + The contentType attribute type specifies the content type of the + ContentInfo value being signed in PKCS #7 (or S/MIME CMS) digitally + signed data. In such data, the contentType attribute type is + required if there are any PKCS #7 authenticated attributes. + + contentType ATTRIBUTE ::= { + WITH SYNTAX ContentType + EQUALITY MATCHING RULE objectIdentifierMatch + SINGLE VALUE TRUE + ID pkcs-9-at-contentType + } + + ContentType ::= OBJECT IDENTIFIER + + As indicated, content-type attributes must have a single attribute + value. For two content-type values to match, their octet string + representation must be of equal length and corresponding octets + identical. The objectIdentifierMatch matching rule is defined in + [7]. + + Note - This attribute type is described in [3] as well. + + + + + +Nystrom & Kaliski Informational [Page 12] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + 5.3.2 Message digest + + The messageDigest attribute type specifies the message digest of the + contents octets of the DER-encoding of the content field of the + ContentInfo value being signed in PKCS #7 digitally signed data, + where the message digest is computed under the signer's message + digest algorithm. The message-digest attribute type is required in + these cases if there are any PKCS #7 authenticated attributes + present. + + messageDigest ATTRIBUTE ::= { + WITH SYNTAX MessageDigest + EQUALITY MATCHING RULE octetStringMatch + SINGLE VALUE TRUE + ID pkcs-9-at-messageDigest + } + + MessageDigest ::= OCTET STRING + + As indicated, a message-digest attribute must have a single attribute + value. For two messageDigest values to match, their octet string + representation must be of equal length and corresponding octets + identical. The octetStringMatch matching rule is defined in [8]. + + Note - This attribute is described in [3] as well. + + 5.3.3 Signing time + + The signingTime attribute type is intended for PKCS #7 digitally + signed data. It specifies the time at which the signer (purportedly) + performed the signing process. + + signingTime ATTRIBUTE ::= { + WITH SYNTAX SigningTime + EQUALITY MATCHING RULE signingTimeMatch + SINGLE VALUE TRUE + ID pkcs-9-at-signingTime + } + + SigningTime ::= Time -- imported from ISO/IEC 9594-8 + + A signing-time attribute must have a single attribute value. + + The signingTimeMatch matching rule (defined in Section 6.1) returns + TRUE if an attribute value represents the same time as a presented + value. + + + + + +Nystrom & Kaliski Informational [Page 13] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + Quoting from [3]: + "Dates between 1 January 1950 and 31 December 2049 (inclusive) MUST + be encoded as UTCTime. Any dates with year values before 1950 or + after 2049 MUST be encoded as GeneralizedTime. [Further,] UTCTime + values MUST be expressed in Greenwich Mean Time (Zulu) and MUST + include seconds (i.e., times are YYMMDDHHMMSSZ), even where the + number of seconds is zero. Midnight (GMT) must be represented as + "YYMMDD000000Z". Century information is implicit, and the century + shall be determined as follows: + + - Where YY is greater than or equal to 50, the year shall be + interpreted as 19YY; and + - Where YY is less than 50, the year shall be interpreted as 20YY. + + GeneralizedTime values shall be expressed in Greenwich Mean Time + (Zulu) and must include seconds (i.e., times are YYYYMMDDHHMMSSZ), + even where the number of seconds is zero. GeneralizedTime values + must not include fractional seconds." + + Note 1 - The definition of SigningTime matches the definition of Time + specified in [10]. + + Note 2 - No requirement is imposed concerning the correctness of the + signing time, and acceptance of a purported signing time is a matter + of a recipient's discretion. It is expected, however, that some + signers, such as time-stamp servers, will be trusted implicitly. + + 5.3.4 Random nonce + + The randomNonce attribute type is intended for PKCS #7 digitally + signed data. It may be used by a signer unable (or unwilling) to + specify the time at which the signing process was performed. Used in + a correct manner, it will make it possible for the signer to protect + against certain attacks, i.e. replay attacks. + + randomNonce ATTRIBUTE ::= { + WITH SYNTAX RandomNonce + EQUALITY MATCHING RULE octetStringMatch + SINGLE VALUE TRUE + ID pkcs-9-at-randomNonce + } + + RandomNonce ::= OCTET STRING (SIZE(4..MAX)) + -- At least four bytes long + + A random nonce attribute must have a single attribute value. + + + + + +Nystrom & Kaliski Informational [Page 14] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + 5.3.5 Sequence number + + The sequenceNumber attribute type is intended for PKCS #7 digitally + signed data. A signer wishing to associate a sequence number to all + signature operations (much like a physical checkbook) may use it as + an alternative to the randomNonce attribute. Used in a correct + manner, it will make it possible for the signer to protect against + certain attacks, i.e. replay attacks. + + sequenceNumber ATTRIBUTE ::= { + WITH SYNTAX SequenceNumber + EQUALITY MATCHING RULE integerMatch + SINGLE VALUE TRUE + ID pkcs-9-at-sequenceNumber + } + + SequenceNumber ::= INTEGER (1..MAX) + + A sequence number attribute must have a single attribute value. + + The integerMatch matching rule is defined in [8]. + + 5.3.6 Countersignature + + The counterSignature attribute type specifies one or more signatures + on the content octets of the DER encoding of the encryptedDigest + field of a SignerInfo value in PKCS #7 digitally signed data. Thus, + the countersignature attribute type countersigns (signs in serial) + another signature. The countersignature attribute must be an + unauthenticated PKCS #7 attribute; it cannot be an authenticated + attribute. + + counterSignature ATTRIBUTE ::= { + WITH SYNTAX SignerInfo + ID pkcs-9-at-counterSignature + } + + Countersignature values have the same meaning as SignerInfo values + for ordinary signatures (see Section 9 of [14] and Section 5.3 of + [3]), except that: + + 1. The authenticatedAttributes field must contain a messageDigest + attribute if it contains any other attributes, but need not contain a + contentType attribute, as there is no content type for + countersignatures; and + + + + + + +Nystrom & Kaliski Informational [Page 15] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + 2. The input to the message-digesting process is the content octets + of the DER encoding of the signatureValue field of the SignerInfo + value with which the attribute is associated. + + A countersignature attribute can have multiple attribute values. + + Note 1 - The fact that a countersignature is computed on a signature + (encrypted digest) means that the countersigning process need not + know the original content input to the signing process. This has + advantages both in efficiency and in confidentiality. + + Note 2 - A countersignature, since it has type SignerInfo, can itself + contain a countersignature attribute. Thus it is possible to + construct arbitrarily long series of countersignatures. + + 5.4 Attribute types for use with PKCS #10 certificate requests + + 5.4.1 Challenge password + + The challengePassword attribute type specifies a password by which an + entity may request certificate revocation. The interpretation of + challenge passwords is intended to be specified by certificate + issuers etc; no particular interpretation is required. + + challengePassword ATTRIBUTE ::= { + WITH SYNTAX DirectoryString {pkcs-9-ub-challengePassword} + EQUALITY MATCHING RULE caseExactMatch + SINGLE VALUE TRUE + ID pkcs-9-at-challengePassword + } + + A challenge-password attribute must have a single attribute value. + + ChallengePassword attribute values generated in accordance with this + version of this document SHOULD use the PrintableString encoding + whenever possible. If internationalization issues make this + impossible, the UTF8String alternative SHOULD be used. PKCS #9- + attribute processing systems MUST be able to recognize and process + all string types in DirectoryString values. + + Note - Version 1.1 of this document defined challengePassword as + having the syntax CHOICE {PrintableString, T61String}, but did + contain a note explaining that this might be changed to a CHOICE of + different string types in the future See also Note 2 in section + 5.2.3. + + + + + + +Nystrom & Kaliski Informational [Page 16] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + 5.4.2 Extension request + + The extensionRequest attribute type may be used to carry information + about certificate extensions the requester wishes to be included in a + certificate. + + extensionRequest ATTRIBUTE ::= { + WITH SYNTAX ExtensionRequest + SINGLE VALUE TRUE + ID pkcs-9-at-extensionRequest + } + + ExtensionRequest ::= Extensions + + The Extensions type is imported from [10]. + + 5.4.3 Extended-certificate attributes (deprecated) + + The extendedCertificateAttributes attribute type specified a set of + attributes for a PKCS #6 [13] extended certificate in a PKCS #10 + certification request (the value of the extended certificate- + attributes attribute would become the extension in the requested PKCS + #6 extended certificate). Since the status of PKCS #6 is historic + after the introduction of X.509 v3 certificates [10], the use of this + attribute is deprecated. + + extendedCertificateAttributes ATTRIBUTE ::= { + WITH SYNTAX SET OF Attribute + SINGLE VALUE TRUE + ID pkcs-9-at-extendedCertificateAttributes + } + + An extended certificate attributes attribute must have a single + attribute value (that value is a set, which itself may contain + multiple values, but there must be only one set). + + 5.5 Attributes for use in PKCS #12 "PFX" PDUs or PKCS #15 tokens + + 5.5.1 Friendly name + + The friendlyName attribute type specifies a user-friendly name of the + object it belongs to. It is referenced in [17]. + + + + + + + + + +Nystrom & Kaliski Informational [Page 17] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + friendlyName ATTRIBUTE ::= { + WITH SYNTAX BMPString (SIZE(1..pkcs-9-ub-friendlyName)) + EQUALITY MATCHING RULE caseIgnoreMatch + SINGLE VALUE TRUE + ID pkcs-9-at-friendlyName + } + + As indicated, friendlyName attributes must have a single attribute + value. + + 5.5.2 Local key identifier + + The localKeyId attribute type specifies an identifier for a + particular key. It is only to be used locally in applications. This + attribute is referenced in [17]. + + localKeyId ATTRIBUTE ::= { + WITH SYNTAX OCTET STRING + EQUALITY MATCHING RULE octetStringMatch + SINGLE VALUE TRUE + ID pkcs-9-at-localKeyId + } + + As indicated, localKeyId attributes must have a single attribute + value. For two localKeyId values to match, their octet string + representation must be of equal length and corresponding octets + identical. + + 5.6 Attributes defined in S/MIME + + S/MIME (c.f. [12]) defines some attributes and object identifiers in + the PKCS #9 object identifier tree. For completeness, they are + mentioned here. + + 5.6.1 Signing description + + The signingDescription attribute is intended to provide a short + synopsis of a message that can be used to present a user with an + additional confirmation step before committing to a cryptographic + operation. In most cases, the replication of the "Subject:" line + from the header of a message should be sufficient and is recommended. + + signingDescription ATTRIBUTE ::= { + WITH SYNTAX DirectoryString {pkcs-9-ub-signingDescription} + EQUALITY MATCHING RULE caseIgnoreMatch + SINGLE VALUE TRUE + ID pkcs-9-at-signingDescription + } + + + +Nystrom & Kaliski Informational [Page 18] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + 5.6.2 S/MIME capabilities + + The syntax and semantics of the smimeCapabilities attribute is + defined in [12]. It is included here for the sake of completeness. + + smimeCapabilities ATTRIBUTE ::= { + WITH SYNTAX SMIMECapabilities + SINGLE VALUE + ID pkcs-9-at-smimeCapabilities + } + + SMIMECapabilities ::= SEQUENCE OF SMIMECapability + + SMIMECapability ::= SEQUENCE { + algorithm ALGORITHM.&id ({SMIMEv3Algorithms}), + parameters ALGORITHM.&Type ({SMIMEv3Algorithms}{@algorithm}) + } + + SMIMEv3Algorithms ALGORITHM ::= {... -- See RFC 2633 -- } + +6. Matching rules + + This section defines matching rules used in the definition of + attributes in this document. + + 6.1 Case ignore match + + The pkcs9CaseIgnoreMatch rule compares for equality a presented + string with an attribute value of type PKCS9String, without regard to + the case (upper or lower) of the strings (e.g. "Pkcs" and "PKCS" + match). + + pkcs9CaseIgnoreMatch MATCHING-RULE ::= { + SYNTAX PKCS9String {pkcs9-ub-match} + ID id-mr-pkcs9CaseIgnoreMatch + } + + The rule returns TRUE if the strings are the same length and + corresponding characters are identical except possibly with regard to + case. + + Where the strings being matched are of different ASN.1 syntax, the + comparison proceeds as normal so long as the corresponding characters + are in both character sets. Otherwise matching fails. + + + + + + + +Nystrom & Kaliski Informational [Page 19] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + 6.2 Signing time match + + The signingTimeMatch rule compares for equality a presented value + with an attribute value of type SigningTime. + + signingTimeMatch MATCHING-RULE ::= { + SYNTAX SigningTime + ID pkcs-9-mr-signingTimeMatch + } + + The rule returns TRUE if the attribute value represents the same time + as the presented value. If a time is specified with seconds (or + fractional seconds) absent, the number of seconds (fractional + seconds) is assumed to be zero. + + Where the strings being matched are of different ASN.1 syntax, the + comparison proceeds as follows: + + a) Convert both values to DER-encoded values of type GeneralizedTime, + coordinated universal time. If this is not possible the matching + fails. + + b) Compare the strings for equality. The rule returns TRUE if and + only if the strings are of the same length and corresponding octets + are identical. + +7. Security Considerations + + Attributes of directory entries are used to provide descriptive + information about the real-world objects they represent, which can be + people, organizations or devices. Most countries have privacy laws + regarding the publication of information about people. + + The challengePassword attribute should not be stored un-encrypted in + a directory. + + Users of directory-aware applications making use of attributes + defined for use with the pkcsEntity object class should make sure + that the class's attributes are adequately protected, since they may + potentially be read by third parties. If a password-protected value + is stored (PKCS #8, #12 or #15), the directory should authenticate + the requester before delivering the value to prevent an off-line + password-search attack. Note that this potentially raises non- + repudiation issues since the directory itself can try a password + search to recover a private value, if stored this way. + + + + + + +Nystrom & Kaliski Informational [Page 20] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + +8. Authors' Addresses + + Magnus Nystrom + RSA Security + Box 10704 + S-121 29 Stockholm + Sweden + + EMail: magnus@rsasecurity.com + + + Burt Kaliski + RSA Security + 20 Crosby Drive + Bedford, MA 01730 USA + + EMail: bkaliski@rsasecurity.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Nystrom & Kaliski Informational [Page 21] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + +APPENDICES + +A. ASN.1 module + + This appendix includes all of the ASN.1 type and value definitions + contained in this document in the form of the ASN.1 module PKCS-9. + + PKCS-9 {iso(1) member-body(2) us(840) rsadsi(113549) pkcs(1) + pkcs-9(9) modules(0) pkcs-9(1)} + + DEFINITIONS IMPLICIT TAGS ::= + + BEGIN + + -- EXPORTS All -- + -- All types and values defined in this module is exported for use + -- in other ASN.1 modules. + + IMPORTS + + informationFramework, authenticationFramework, + selectedAttributeTypes, upperBounds , id-at + FROM UsefulDefinitions {joint-iso-itu-t ds(5) module(1) + usefulDefinitions(0) 3} + + ub-name + FROM UpperBounds upperBounds + + OBJECT-CLASS, ATTRIBUTE, MATCHING-RULE, Attribute, top, + objectIdentifierMatch + FROM InformationFramework informationFramework + + ALGORITHM, Extensions, Time + FROM AuthenticationFramework authenticationFramework + + DirectoryString, octetStringMatch, caseIgnoreMatch, caseExactMatch, + generalizedTimeMatch, integerMatch, serialNumber + FROM SelectedAttributeTypes selectedAttributeTypes + + ContentInfo, SignerInfo + FROM CryptographicMessageSyntax {iso(1) member-body(2) us(840) + rsadsi(113549) pkcs(1) pkcs-9(9) smime(16) modules(0) cms(1)} + + EncryptedPrivateKeyInfo + FROM PKCS-8 {iso(1) member-body(2) us(840) rsadsi(113549) + pkcs(1) pkcs-8(8) modules(1) pkcs-8(1)} + + + + + +Nystrom & Kaliski Informational [Page 22] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + PFX + FROM PKCS-12 {iso(1) member-body(2) us(840) rsadsi(113549) + pkcs(1) pkcs-12(12) modules(0) pkcs-12(1)} + + PKCS15Token + FROM PKCS-15 {iso(1) member-body(2) us(840) rsadsi(113549) + pkcs(1) pkcs-15(15) modules(1) pkcs-15(1)}; + + -- Upper bounds + + pkcs-9-ub-pkcs9String INTEGER ::= 255 + pkcs-9-ub-emailAddress INTEGER ::= pkcs-9-ub-pkcs9String + pkcs-9-ub-unstructuredName INTEGER ::= pkcs-9-ub-pkcs9String + pkcs-9-ub-unstructuredAddress INTEGER ::= pkcs-9-ub-pkcs9String + pkcs-9-ub-challengePassword INTEGER ::= pkcs-9-ub-pkcs9String + pkcs-9-ub-friendlyName INTEGER ::= pkcs-9-ub-pkcs9String + pkcs-9-ub-signingDescription INTEGER ::= pkcs-9-ub-pkcs9String + pkcs-9-ub-match INTEGER ::= pkcs-9-ub-pkcs9String + pkcs-9-ub-pseudonym INTEGER ::= ub-name + pkcs-9-ub-placeOfBirth INTEGER ::= ub-name + + -- Object Identifiers + + pkcs-9 OBJECT IDENTIFIER ::= {iso(1) member-body(2) us(840) + rsadsi(113549) pkcs(1) 9} + + -- Main arcs + pkcs-9-mo OBJECT IDENTIFIER ::= {pkcs-9 0} -- Modules branch + pkcs-9-oc OBJECT IDENTIFIER ::= {pkcs-9 24} -- Object class branch + pkcs-9-at OBJECT IDENTIFIER ::= {pkcs-9 25} -- Attribute branch, for + -- new attributes + pkcs-9-sx OBJECT IDENTIFIER ::= {pkcs-9 26} -- For syntaxes (RFC 2252) + pkcs-9-mr OBJECT IDENTIFIER ::= {pkcs-9 27} -- Matching rules + + -- Object classes + pkcs-9-oc-pkcsEntity OBJECT IDENTIFIER ::= {pkcs-9-oc 1} + pkcs-9-oc-naturalPerson OBJECT IDENTIFIER ::= {pkcs-9-oc 2} + + -- Attributes + pkcs-9-at-emailAddress OBJECT IDENTIFIER ::= {pkcs-9 1} + pkcs-9-at-unstructuredName OBJECT IDENTIFIER ::= {pkcs-9 2} + pkcs-9-at-contentType OBJECT IDENTIFIER ::= {pkcs-9 3} + pkcs-9-at-messageDigest OBJECT IDENTIFIER ::= {pkcs-9 4} + pkcs-9-at-signingTime OBJECT IDENTIFIER ::= {pkcs-9 5} + pkcs-9-at-counterSignature OBJECT IDENTIFIER ::= {pkcs-9 6} + pkcs-9-at-challengePassword OBJECT IDENTIFIER ::= {pkcs-9 7} + pkcs-9-at-unstructuredAddress OBJECT IDENTIFIER ::= {pkcs-9 8} + + + + +Nystrom & Kaliski Informational [Page 23] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + pkcs-9-at-extendedCertificateAttributes + OBJECT IDENTIFIER ::= {pkcs-9 9} + + -- Obsolete (?) attribute identifiers, purportedly from "tentative + -- PKCS #9 draft" + -- pkcs-9-at-issuerAndSerialNumber OBJECT IDENTIFIER ::= {pkcs-9 10} + -- pkcs-9-at-passwordCheck OBJECT IDENTIFIER ::= {pkcs-9 11} + -- pkcs-9-at-publicKey OBJECT IDENTIFIER ::= {pkcs-9 12} + + pkcs-9-at-signingDescription OBJECT IDENTIFIER ::= {pkcs-9 13} + pkcs-9-at-extensionRequest OBJECT IDENTIFIER ::= {pkcs-9 14} + pkcs-9-at-smimeCapabilities OBJECT IDENTIFIER ::= {pkcs-9 15} + + -- Unused (?) + -- pkcs-9-at-? OBJECT IDENTIFIER ::= {pkcs-9 17} + -- pkcs-9-at-? OBJECT IDENTIFIER ::= {pkcs-9 18} + -- pkcs-9-at-? OBJECT IDENTIFIER ::= {pkcs-9 19} + + pkcs-9-at-friendlyName OBJECT IDENTIFIER ::= {pkcs-9 20} + pkcs-9-at-localKeyId OBJECT IDENTIFIER ::= {pkcs-9 21} + pkcs-9-at-userPKCS12 OBJECT IDENTIFIER ::= + {2 16 840 1 113730 3 1 216} + pkcs-9-at-pkcs15Token OBJECT IDENTIFIER ::= {pkcs-9-at 1} + pkcs-9-at-encryptedPrivateKeyInfo OBJECT IDENTIFIER ::= {pkcs-9-at 2} + pkcs-9-at-randomNonce OBJECT IDENTIFIER ::= {pkcs-9-at 3} + pkcs-9-at-sequenceNumber OBJECT IDENTIFIER ::= {pkcs-9-at 4} + pkcs-9-at-pkcs7PDU OBJECT IDENTIFIER ::= {pkcs-9-at 5} + + -- IETF PKIX Attribute branch + ietf-at OBJECT IDENTIFIER ::= + {1 3 6 1 5 5 7 9} + + pkcs-9-at-dateOfBirth OBJECT IDENTIFIER ::= {ietf-at 1} + pkcs-9-at-placeOfBirth OBJECT IDENTIFIER ::= {ietf-at 2} + pkcs-9-at-gender OBJECT IDENTIFIER ::= {ietf-at 3} + pkcs-9-at-countryOfCitizenship OBJECT IDENTIFIER ::= {ietf-at 4} + pkcs-9-at-countryOfResidence OBJECT IDENTIFIER ::= {ietf-at 5} + + -- Syntaxes (for use with LDAP accessible directories) + pkcs-9-sx-pkcs9String OBJECT IDENTIFIER ::= {pkcs-9-sx 1} + pkcs-9-sx-signingTime OBJECT IDENTIFIER ::= {pkcs-9-sx 2} + + -- Matching rules + pkcs-9-mr-caseIgnoreMatch OBJECT IDENTIFIER ::= {pkcs-9-mr 1} + pkcs-9-mr-signingTimeMatch OBJECT IDENTIFIER ::= {pkcs-9-mr 2} + + + + + + +Nystrom & Kaliski Informational [Page 24] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + -- Arcs with attributes defined elsewhere + smime OBJECT IDENTIFIER ::= {pkcs-9 16} + + -- Main arc for S/MIME (RFC 2633) + certTypes OBJECT IDENTIFIER ::= {pkcs-9 22} + + -- Main arc for certificate types defined in PKCS #12 + crlTypes OBJECT IDENTIFIER ::= {pkcs-9 23} + + -- Main arc for crl types defined in PKCS #12 + + -- Other object identifiers + id-at-pseudonym OBJECT IDENTIFIER ::= {id-at 65} + + -- Useful types + + PKCS9String {INTEGER : maxSize} ::= CHOICE { + ia5String IA5String (SIZE(1..maxSize)), + directoryString DirectoryString {maxSize} + } + + -- Object classes + + pkcsEntity OBJECT-CLASS ::= { + SUBCLASS OF { top } + KIND auxiliary + MAY CONTAIN { PKCSEntityAttributeSet } + ID pkcs-9-oc-pkcsEntity + } + + naturalPerson OBJECT-CLASS ::= { + SUBCLASS OF { top } + KIND auxiliary + MAY CONTAIN { NaturalPersonAttributeSet } + ID pkcs-9-oc-naturalPerson + } + + -- Attribute sets + + PKCSEntityAttributeSet ATTRIBUTE ::= { + pKCS7PDU | + userPKCS12 | + pKCS15Token | + encryptedPrivateKeyInfo, + ... -- For future extensions + } + + + + + +Nystrom & Kaliski Informational [Page 25] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + NaturalPersonAttributeSet ATTRIBUTE ::= { + emailAddress | + unstructuredName | + unstructuredAddress | + dateOfBirth | + placeOfBirth | + gender | + countryOfCitizenship | + countryOfResidence | + pseudonym | + serialNumber, + ... -- For future extensions + } + + -- Attributes + + pKCS7PDU ATTRIBUTE ::= { + WITH SYNTAX ContentInfo + ID pkcs-9-at-pkcs7PDU + } + + userPKCS12 ATTRIBUTE ::= { + WITH SYNTAX PFX + ID pkcs-9-at-userPKCS12 + } + + pKCS15Token ATTRIBUTE ::= { + WITH SYNTAX PKCS15Token + ID pkcs-9-at-pkcs15Token + } + + encryptedPrivateKeyInfo ATTRIBUTE ::= { + WITH SYNTAX EncryptedPrivateKeyInfo + ID pkcs-9-at-encryptedPrivateKeyInfo + } + + emailAddress ATTRIBUTE ::= { + WITH SYNTAX IA5String (SIZE(1..pkcs-9-ub-emailAddress)) + EQUALITY MATCHING RULE pkcs9CaseIgnoreMatch + ID pkcs-9-at-emailAddress + } + + unstructuredName ATTRIBUTE ::= { + WITH SYNTAX PKCS9String {pkcs-9-ub-unstructuredName} + EQUALITY MATCHING RULE pkcs9CaseIgnoreMatch + ID pkcs-9-at-unstructuredName + } + + + + +Nystrom & Kaliski Informational [Page 26] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + unstructuredAddress ATTRIBUTE ::= { + WITH SYNTAX DirectoryString {pkcs-9-ub-unstructuredAddress} + EQUALITY MATCHING RULE caseIgnoreMatch + ID pkcs-9-at-unstructuredAddress + } + + dateOfBirth ATTRIBUTE ::= { + WITH SYNTAX GeneralizedTime + EQUALITY MATCHING RULE generalizedTimeMatch + SINGLE VALUE TRUE + ID pkcs-9-at-dateOfBirth + } + + placeOfBirth ATTRIBUTE ::= { + WITH SYNTAX DirectoryString {pkcs-9-ub-placeOfBirth} + EQUALITY MATCHING RULE caseExactMatch + SINGLE VALUE TRUE + ID pkcs-9-at-placeOfBirth + } + + gender ATTRIBUTE ::= { + WITH SYNTAX PrintableString (SIZE(1) ^ + FROM ("M" | "F" | "m" | "f")) + EQUALITY MATCHING RULE caseIgnoreMatch + SINGLE VALUE TRUE + ID pkcs-9-at-gender + } + + countryOfCitizenship ATTRIBUTE ::= { + WITH SYNTAX PrintableString (SIZE(2))(CONSTRAINED BY { + -- Must be a two-letter country acronym in accordance with + -- ISO/IEC 3166 --}) + EQUALITY MATCHING RULE caseIgnoreMatch + ID pkcs-9-at-countryOfCitizenship + } + + countryOfResidence ATTRIBUTE ::= { + WITH SYNTAX PrintableString (SIZE(2))(CONSTRAINED BY { + -- Must be a two-letter country acronym in accordance with + -- ISO/IEC 3166 --}) + EQUALITY MATCHING RULE caseIgnoreMatch + ID pkcs-9-at-countryOfResidence + } + + + + + + + + +Nystrom & Kaliski Informational [Page 27] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + pseudonym ATTRIBUTE ::= { + WITH SYNTAX DirectoryString {pkcs-9-ub-pseudonym} + EQUALITY MATCHING RULE caseExactMatch + ID id-at-pseudonym + } + + contentType ATTRIBUTE ::= { + WITH SYNTAX ContentType + EQUALITY MATCHING RULE objectIdentifierMatch + SINGLE VALUE TRUE + ID pkcs-9-at-contentType + } + + ContentType ::= OBJECT IDENTIFIER + + messageDigest ATTRIBUTE ::= { + WITH SYNTAX MessageDigest + EQUALITY MATCHING RULE octetStringMatch + SINGLE VALUE TRUE + ID pkcs-9-at-messageDigest + } + + MessageDigest ::= OCTET STRING + + signingTime ATTRIBUTE ::= { + WITH SYNTAX SigningTime + EQUALITY MATCHING RULE signingTimeMatch + SINGLE VALUE TRUE + ID pkcs-9-at-signingTime + } + + SigningTime ::= Time -- imported from ISO/IEC 9594-8 + + randomNonce ATTRIBUTE ::= { + WITH SYNTAX RandomNonce + EQUALITY MATCHING RULE octetStringMatch + SINGLE VALUE TRUE + ID pkcs-9-at-randomNonce + } + + RandomNonce ::= OCTET STRING (SIZE(4..MAX)) + -- At least four bytes long + + + + + + + + + +Nystrom & Kaliski Informational [Page 28] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + sequenceNumber ATTRIBUTE ::= { + WITH SYNTAX SequenceNumber + EQUALITY MATCHING RULE integerMatch + SINGLE VALUE TRUE + ID pkcs-9-at-sequenceNumber + } + + SequenceNumber ::= INTEGER (1..MAX) + + counterSignature ATTRIBUTE ::= { + WITH SYNTAX SignerInfo + ID pkcs-9-at-counterSignature + } + + challengePassword ATTRIBUTE ::= { + WITH SYNTAX DirectoryString {pkcs-9-ub-challengePassword} + EQUALITY MATCHING RULE caseExactMatch + SINGLE VALUE TRUE + ID pkcs-9-at-challengePassword + } + + extensionRequest ATTRIBUTE ::= { + WITH SYNTAX ExtensionRequest + SINGLE VALUE TRUE + ID pkcs-9-at-extensionRequest + } + + ExtensionRequest ::= Extensions + + extendedCertificateAttributes ATTRIBUTE ::= { + WITH SYNTAX SET OF Attribute + SINGLE VALUE TRUE + ID pkcs-9-at-extendedCertificateAttributes + } + + friendlyName ATTRIBUTE ::= { + WITH SYNTAX BMPString (SIZE(1..pkcs-9-ub-friendlyName)) + EQUALITY MATCHING RULE caseIgnoreMatch + SINGLE VALUE TRUE + ID pkcs-9-at-friendlyName + } + + localKeyId ATTRIBUTE ::= { + WITH SYNTAX OCTET STRING + EQUALITY MATCHING RULE octetStringMatch + SINGLE VALUE TRUE + ID pkcs-9-at-localKeyId + } + + + +Nystrom & Kaliski Informational [Page 29] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + signingDescription ATTRIBUTE ::= { + WITH SYNTAX DirectoryString {pkcs-9-ub-signingDescription} + EQUALITY MATCHING RULE caseIgnoreMatch + SINGLE VALUE TRUE + ID pkcs-9-at-signingDescription + } + + smimeCapabilities ATTRIBUTE ::= { + WITH SYNTAX SMIMECapabilities + SINGLE VALUE TRUE + ID pkcs-9-at-smimeCapabilities + } + + SMIMECapabilities ::= SEQUENCE OF SMIMECapability + + SMIMECapability ::= SEQUENCE { + algorithm ALGORITHM.&id ({SMIMEv3Algorithms}), + parameters ALGORITHM.&Type ({SMIMEv3Algorithms}{@algorithm}) + } + + SMIMEv3Algorithms ALGORITHM ::= {...-- See RFC 2633 --} + + -- Matching rules + + pkcs9CaseIgnoreMatch MATCHING-RULE ::= { + SYNTAX PKCS9String {pkcs-9-ub-match} + ID pkcs-9-mr-caseIgnoreMatch + } + + signingTimeMatch MATCHING-RULE ::= { + SYNTAX SigningTime + ID pkcs-9-mr-signingTimeMatch + } + + END + +B. BNF schema summary This appendix provides augmented BNF [2] + definitions of the object class and most attribute types specified in + this document along with their associated syntaxes and matching + rules. The ABNF definitions have been done in accordance with [21], + in an attempt to ease integration with LDAP-accessible Directory + systems. Lines have been folded in some cases to improve + readability. + + B.1 Syntaxes + + This section defines all syntaxes that are used in this document. + + + + +Nystrom & Kaliski Informational [Page 30] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + B.1.1 PKCS9String + + ( + 1.2.840.113549.1.9.26.1 + DESC 'PKCS9String' + ) + + The encoding of a value in this syntax is the string value itself. + + B.1.2 SigningTime + + ( + 1.2.840.113549.1.9.26.2 + DESC 'SigningTime' + ) + + Values in this syntax are encoded as printable strings, represented + as specified in [5]. Note that the time zone must be specified. For + example, "199412161032Z". + + B.2 Object classes + + B.2.1 pkcsEntity + + ( + 1.2.840.113549.1.9.24.1 + NAME 'pkcsEntity' + SUP top + AUXILIARY + MAY ( + pKCS7PDU $ userPKCS12 $ pKCS15Token $ encryptedPrivateKeyInfo + ) + ) + + B.2.2 naturalPerson + + ( + 1.2.840.113549.1.9.24.2 + NAME 'naturalPerson' + SUP top + AUXILIARY + MAY ( + emailAddress $ unstructuredName $ unstructuredAddress $ + dateOfBirth & placeOfBirth & gender & countryOfCitizenship & + countryOfResidence & pseudonym & serialNumber + ) + ) + + + + +Nystrom & Kaliski Informational [Page 31] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + B.3 Attribute types + + B.3.1 pKCS7PDU + + This attribute is to be stored and requested in binary form, as + pKCS7PDU;binary. The attribute values are BER- or DER-encoded + ContentInfo values. + + ( + 1.2.840.113549.1.9.25.5 + NAME 'pKCS7PDU' + DESC 'PKCS #7 ContentInfo PDU' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.5 + ) + + B.3.2 userPKCS12 + + This attribute is to be stored and requested in binary form, as + userPKCS12;binary. The attribute values are PFX PDUs stored as + binary (BER- or DER-encoded) data. + + ( + 2.16.840.1.113730.3.1.216 + NAME 'userPKCS12' + DESC 'PKCS #12 PFX PDU for exchange of personal information' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.5 + ) + + B.3.3 pKCS15Token + + This attribute is to be stored and requested in binary form, as + pKCS15Token;binary. The attribute values are PKCS15Token PDUs stored + as binary (BER- or DER-encoded) data. + + ( + 1.2.840.113549.1.9.25.1 + NAME 'pKCS15Token' + DESC 'PKCS #15 token PDU' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.5 + ) + + B.3.4 encryptedPrivateKeyInfo + + This attribute is to be stored and requested in binary form, as + encryptedPrivateKeyInfo;binary. The attribute values are + EncryptedPrivateKeyInfo PDUs stored as binary (BER- or DER-encoded) + data. + + + + +Nystrom & Kaliski Informational [Page 32] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + ( + 1.2.840.113549.1.9.25.2 + NAME 'encryptedPrivateKeyInfo' + DESC 'PKCS #8 encrypted private key info' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.5 + ) + + B.3.5 emailAddress + + ( + 1.2.840.113549.1.9.1 + NAME 'emailAddress' + DESC 'Email address' + EQUALITY pkcs9CaseIgnoreMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 + ) + + B.3.6 unstructuredName + + ( + 1.2.840.113549.1.9.2 + NAME 'unstructuredName' + DESC 'PKCS #9 unstructured name' + EQUALITY pkcs9CaseIgnoreMatch + SYNTAX 1.2.840.113549.1.9.26.1 + ) + + B.3.7 unstructuredAddress + + ( + 1.2.840.113549.1.9.8 + NAME 'unstructuredAddress' + DESC 'PKCS #9 unstructured address' + EQUALITY caseIgnoreMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 + ) + + B.3.8 dateOfBirth + + ( + 1.3.6.1.5.5.7.9.1 + NAME 'dateOfBirth' + DESC 'Date of birth' + EQUALITY generalizedTimeMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 + SINGLE-VALUE + ) + + + + +Nystrom & Kaliski Informational [Page 33] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + B.3.9 placeOfBirth + + ( + 1.3.6.1.5.5.7.9.2 + NAME 'placeOfBirth' + DESC 'Place of birth' + EQUALITY caseExactMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 + SINGLE-VALUE + ) + + B.3.10 gender + + ( + 1.3.6.1.5.5.7.9.3 + NAME 'gender' + DESC 'Gender' + EQUALITY caseIgnoreMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.44 + SINGLE-VALUE + ) + + B.3.11 countryOfCitizenship + + ( + 1.3.6.1.5.5.7.9.4 + NAME 'countryOfCitizenship' + DESC 'Country of citizenship' + EQUALITY caseIgnoreMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.44 + ) + + B.3.12 countryOfResidence + + ( + 1.3.6.1.5.5.7.9.5 + NAME 'countryOfResidence' + DESC 'Country of residence' + EQUALITY caseIgnoreMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.44 + ) + + + + + + + + + + +Nystrom & Kaliski Informational [Page 34] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + B.3.13 pseudonym + + ( + 2.5.4.65 + NAME 'pseudonym' + DESC 'Pseudonym' + EQUALITY caseExactMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 + ) + + B.3.14 contentType + + In the (highly unlikely) event of this attribute being stored in a + Directory it is to be stored and requested in binary form, as + contentType;binary. Attribute values shall be OCTET STRINGs stored + as binary (BER- or DER-encoded) data. + + ( + 1.2.840.113549.1.9.3 + NAME 'contentType' + DESC 'PKCS #7 content type attribute' + EQUALITY objectIdentifierMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 + SINGLE-VALUE + ) + + B.3.15 messageDigest + + In the (highly unlikely) event of this attribute being stored in a + Directory it is to be stored and requested in binary form, as + messageDigest;binary. Attribute values shall be OCTET STRINGs stored + as binary (BER- or DER-encoded) data. + + ( + 1.2.840.113549.1.9.4 + NAME 'messageDigest' + DESC 'PKCS #7 mesage digest attribute' + EQUALITY octetStringMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.5 + SINGLE-VALUE + ) + + + + + + + + + + +Nystrom & Kaliski Informational [Page 35] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + B.3.16 signingTime + + ( + 1.2.840.113549.1.9.5 + NAME 'signingTime' + DESC 'PKCS #7 signing time' + EQUALITY signingTimeMatch + SYNTAX 1.2.840.113549.1.9.26.2 + SINGLE-VALUE + ) + + B.3.17 counterSignature + + In the (highly unlikely) event that this attribute is to be stored in + a directory, it is to be stored and requested in binary form, as + counterSignature;binary. Attribute values shall be stored as binary + (BER- or DER-encoded) data. + + ( + 1.2.840.113549.1.9.6 + NAME 'counterSignature' + DESC 'PKCS #7 countersignature' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.5 + ) + + B.3.18 challengePassword + + ( + 1.2.840.113549.1.9.7 + NAME 'challengePassword' + DESC 'Challenge password for certificate revocations' + EQUALITY caseExactMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 + SINGLE-VALUE + ) + + Note - It is not recommended to store unprotected values of this + attribute in a directory. + + B.4 Matching rules + + B.4.1 pkcs9CaseIgnoreMatch + + ( + 1.2.840.113549.1.9.27.1 + NAME 'pkcs9CaseIgnoreMatch' + SYNTAX 1.2.840.113549.1.9.26.1 + ) + + + +Nystrom & Kaliski Informational [Page 36] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + B.4.2 signingTimeMatch + + ( + 1.2.840.113549.1.9.27.3 + NAME 'signingTimeMatch' + SYNTAX 1.2.840.113549.1.9.26.2 + ) + +C. Intellectual property considerations + + RSA Security makes no patent claims on the general constructions + described in this document, although specific underlying techniques + may be covered. + + License to copy this document is granted provided that it is + identified as "RSA Security Inc. Public-Key Cryptography Standards + (PKCS)" in all material mentioning or referencing this document. + + RSA Security makes no representations regarding intellectual property + claims by other parties. Such determination is the responsibility of + the user. + +D. Revision history + + Version 1.0 + + Version 1.0 was part of the June 3, 1991 initial public release of + PKCS. Version 1.0 was also published as NIST/OSI Implementors' + Workshop document SEC-SIG-91-24. + + Version 1.1 + + Version 1.1 incorporated several editorial changes, including + updates to the references and the addition of a revision history. + The following substantive changes were made: + + - Section 6: challengePassword, unstructuredAddress, and + extendedCertificateAttributes attribute types were added + - Section 7: challengePassword, unstructuredAddress, and + extendedCertificateAttributes object identifiers were added + + + + + + + + + + + +Nystrom & Kaliski Informational [Page 37] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + Version 2.0 + + Version 2.0 incorporates several editorial changes as well. In + addition, the following substantive changes have been made: + + - Addition of a Section defining two new auxiliary object classes, + pkcsEntity and naturalPerson + - Addition of several new attribute types and matching rules for + use in conjunction with these object classes and elsewhere + - Update of all ASN.1 to be in line with the 1997 version of this + syntax + - Addition a "compilable" ASN.1 module + - Addition, in accordance with [21], an ABNF description of all + attributes and object classes + - Addition of an intellectual property considerations section + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Nystrom & Kaliski Informational [Page 38] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + +E. References + + [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement + Levels", BCP 14, RFC 2119, March 1997. + + [2] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 2234, November 1997. + + [3] Housley, R., "Cryptographic Message Syntax CMS", RFC 2630, June + 1999. + + [4] ISO/IEC 3166-1:Codes for the representation of names of + countries and their subdivisions - Part 1: Country codes. 1997. + + [5] ISO/IEC 8824-1:1999: Information technology - Abstract Syntax + Notation One (ASN.1) - Specification of basic notation.1999. + + [6] ISO/IEC 8825-1:1999: Information technology - ASN.1 Encoding + Rules: Specification of Basic Encoding Rules (BER), Canonical + Encoding Rules (CER) and Distinguished Encoding Rules (DER). + 1999. + + [7] ISO/IEC 9594-2:1997: Information technology - Open Systems + Interconnection - The Directory: Models. 1997. + + [8] ISO/IEC 9594-6:1997: Information technology - Open Systems + Interconnection - The Directory: Selected attribute types. 1997. + + [9] ISO/IEC 9594-7:1997: Information technology - Open Systems + Interconnection - The Directory: Selected object classes. 1997. + + [10] ISO/IEC 9594-8:1997: Information technology - Open Systems + Interconnection - The Directory: Authentication framework. 1997. + + [11] ISO/IEC 10646-1: Information Technology - Universal Multiple- + Octet Coded Character Set (UCS) - Part 1: Architecture and Basic + Multilingual Plane. 1993. + + [12] Ramsdell, R., "S/MIME Version 3 Message Specification", RFC + 2633, June 1999. + + [13] RSA Laboratories. PKCS #6: Extended-Certificate Syntax Standard. + Version 1.5, November 1993. + + [14] RSA Laboratories. PKCS #7: Cryptographic Message Syntax + Standard. Version 1.5, November 1993. + + + + + +Nystrom & Kaliski Informational [Page 39] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + + [15] RSA Laboratories. PKCS #8: Private-Key Information Syntax + Standard. Version 1.2, November 1993. + + [16] RSA Laboratories. PKCS #10: Certification Request Syntax + Standard. Version 1.0, November 1993. + + [17] RSA Laboratories. PKCS #12: Personal Information Exchange Syntax + Standard. Version 1.0, June 1999. + + [18] RSA Laboratories. PKCS #15: Cryptographic Token Information + Format Standard. Version 1.1, June 2000. + + [19] Santesson, S., Polk, W., Barzin, P. and M. Nystrom, "Internet + X.509 Public Key Infrastructure - Qualified Certificates + Profile", Work in Progress. + + [20] Smith, M. "Definition of the inetOrgPerson LDAP Object Class", + RFC 2798, April 2000. + + [21] Wahl, M., Coulbeck, A., Howes, T. and S. Kille, "Lightweight + Directory Access Protocol (v3): Attribute Syntax Definitions", + RFC 2252, December 1997. + + [22] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access + Protocol (v3)", RFC 2251, December 1997. + + + + + + + + + + + + + + + + + + + + + + + + + + +Nystrom & Kaliski Informational [Page 40] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + +F. Contact information & About PKCS + + The Public-Key Cryptography Standards are specifications produced by + RSA Laboratories in cooperation with secure systems developers + worldwide for the purpose of accelerating the deployment of public- + key cryptography. First published in 1991 as a result of meetings + with a small group of early adopters of public-key technology, the + PKCS documents have become widely referenced and implemented. + Contributions from the PKCS series have become part of many formal + and de facto standards, including ANSI X9 documents, PKIX, SET, + S/MIME, and SSL. + + Further development of PKCS occurs through mailing list discussions + and occasional workshops, and suggestions for improvement are + welcome. For more information, contact: + + PKCS Editor + RSA Laboratories + 20 Crosby Drive + Bedford, MA 01730 USA + pkcs-editor@rsasecurity.com + http://www.rsasecurity.com/rsalabs/PKCS + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Nystrom & Kaliski Informational [Page 41] + +RFC 2985 Selected Object Classes and Attribute Types November 2000 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2000). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others provided that the above copyright notice and this paragraph + are included on all such copies. However, this document itself may + not be modified in any way, such as by removing the copyright notice + or references to the Internet Society or other Internet + organizations, except as required to translate it into languages + other than English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + + + + + + + +Nystrom & Kaliski Informational [Page 42] + diff --git a/docs/rfc/rfc5915.txt b/docs/rfc/rfc5915.txt new file mode 100644 index 0000000..7ec4a3a --- /dev/null +++ b/docs/rfc/rfc5915.txt @@ -0,0 +1,395 @@ + + + + + + +Internet Engineering Task Force (IETF) S. Turner +Request for Comments: 5915 IECA +Category: Informational D. Brown +ISSN: 2070-1721 Certicom + June 2010 + + + Elliptic Curve Private Key Structure + +Abstract + + This document specifies the syntax and semantics for conveying + Elliptic Curve (EC) private key information. The syntax and + semantics defined herein are based on similar syntax and semantics + defined by the Standards for Efficient Cryptography Group (SECG). + +Status of This Memo + + This document is not an Internet Standards Track specification; it is + published for informational purposes. + + 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). Not all documents + approved by the IESG are a candidate for any level of Internet + Standard; see 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/rfc5915. + +Copyright Notice + + Copyright (c) 2010 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. + + + + + +Turner & Brown Informational [Page 1] + +RFC 5915 Elliptic Curve Private Key Structure June 2010 + + +1. Introduction + + This document specifies a syntax and semantics for Elliptic Curve + (EC) private key information. EC private key information includes a + private key and parameters. Additionally, it may include the + corresponding public key. The syntax and semantics defined herein + are based on similar syntax and semantics defined by the Standards + for Efficient Cryptography Group (SECG) [SECG1]. + + Most Public Key Infrastructures (PKIs) mandate local key generation; + however, there are some PKIs that also support centralized key + generation (e.g., the public-private key pair is generated by a + Certification Authority). The structure defined in this document + allows the entity that generates the private and public keys to + distribute the key pair and the associated domain parameters. + + This syntax is useful when distributing EC private keys using + PrivateKeyInfo, as defined in PKCS #8 [RFC5208]. Distributing an EC + private key with PKCS#8 [RFC5208] involves including: + + a) id-ecPublicKey, id-ecDH, or id-ecMQV (from [RFC5480]) with the + namedCurve as the parameters in the privateKeyAlgorithm field; and + b) ECPrivateKey in the PrivateKey field, which is an OCTET STRING. + + When an EC public key is included in the distributed PrivateKeyInfo, + the publicKey field in ECPrivateKey is used. + +2. 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]. + +3. Elliptic Curve Private Key Format + + This section gives the syntax for an EC private key. + Computationally, an EC private key is an unsigned integer, but for + representation, EC private key information SHALL have ASN.1 type + ECPrivateKey: + + ECPrivateKey ::= SEQUENCE { + version INTEGER { ecPrivkeyVer1(1) } (ecPrivkeyVer1), + privateKey OCTET STRING, + parameters [0] ECParameters {{ NamedCurve }} OPTIONAL, + publicKey [1] BIT STRING OPTIONAL + } + + + + + +Turner & Brown Informational [Page 2] + +RFC 5915 Elliptic Curve Private Key Structure June 2010 + + + The fields of type ECPrivateKey have the following meanings: + + o version specifies the syntax version number of the elliptic curve + private key structure. For this version of the document, it SHALL + be set to ecPrivkeyVer1, which is of type INTEGER and whose value + is one (1). + + o privateKey is the private key. It is an octet string of length + ceiling (log2(n)/8) (where n is the order of the curve) obtained + from the unsigned integer via the Integer-to-Octet-String- + Primitive (I2OSP) defined in [RFC3447]. + + o parameters specifies the elliptic curve domain parameters + associated to the private key. The type ECParameters is discussed + in [RFC5480]. As specified in [RFC5480], only the namedCurve + CHOICE is permitted. namedCurve is an object identifier that + fully identifies the required values for a particular set of + elliptic curve domain parameters. Though the ASN.1 indicates that + the parameters field is OPTIONAL, implementations that conform to + this document MUST always include the parameters field. + + o publicKey contains the elliptic curve public key associated with + the private key in question. The format of the public key is + specified in Section 2.2 of [RFC5480]. Though the ASN.1 indicates + publicKey is OPTIONAL, implementations that conform to this + document SHOULD always include the publicKey field. The publicKey + field can be omitted when the public key has been distributed via + another mechanism, which is beyond the scope of this document. + Given the private key and the parameters, the public key can + always be recomputed; this field exists as a convenience to the + consumer. + +4. Other Considerations + + When generating a transfer encoding, generators SHOULD use + Distinguished Encoding Rules (DER) [X.690] and receivers SHOULD be + prepared to handle Basic Encoding Rules (BER) [X.690] and DER + [X.690]. + + Section 1 described a format for transporting EC private keys (i.e., + converting ECPrivateKey to PrivateKeyInfo [PKCS#8]); however, this + format can also be used for local storage. + + Local storage of an unencrypted ECPrivateKey object is out of scope + of this document. However, one popular format uses the .pem file + extension. It is the PEM encoding, which is the Base64 encoding (see + Section 4 of [RFC4648]), of the DER-encoded ECPrivateKey object that + is sandwiched between: + + + +Turner & Brown Informational [Page 3] + +RFC 5915 Elliptic Curve Private Key Structure June 2010 + + + -----BEGIN EC PRIVATE KEY----- + -----END EC PRIVATE KEY----- + + Another local storage format uses the .der file extension. In this + case, it is a DER [X.690] encoding of the ECPrivateKey object. + + Local storage of an encrypted ECPrivateKey object is out of scope of + this document. However, ECPrivateKey should be the format for the + plaintext key being encrypted. DER [X.690] encoding the ECPrivateKey + will promote interoperability if the key is encrypted for transport + to another party. PEM encoding the DER-encoded ECPrivateKey is + common; "Proc-Type:" and "DEK-INFO:" fields [RFC1421] followed by the + DER-encoded ECPrivateKey are sandwiched between: + + -----BEGIN EC PRIVATE KEY----- + -----END EC PRIVATE KEY----- + +5. Security Considerations + + This structure does not protect the EC private key information in any + way. This structure should be combined with a security protocol to + protect it. + + Protection of the private key information is vital to public key + cryptography. The consequences of disclosure depend on the purpose + of the private key. If a private key is used for signature, then the + disclosure allows unauthorized signing. If a private key is used for + key management, then disclosure allows unauthorized parties to access + the managed keying material. The encryption algorithm used in the + encryption process must be as 'strong' as the key it is protecting. + +6. References + +6.1. Normative References + + [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic + Mail: Part I: Message Encryption and Authentication + Procedures", RFC 1421, February 1993. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography + Standards (PKCS) #1: RSA Cryptography Specifications + Version 2.1", RFC 3447, February 2003. + + [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data + Encodings", RFC 4648, October 2006. + + + +Turner & Brown Informational [Page 4] + +RFC 5915 Elliptic Curve Private Key Structure June 2010 + + + [RFC5480] Turner, S., Brown, D., Yiu, K., Housley, R., and T. Polk, + "Elliptic Curve Cryptography Subject Public Key + Information", RFC 5480, March 2009. + + [RFC5912] Schaad, J. and P. Hoffman, "New ASN.1 Modules for the + Public Key Infrastructure Using X.509 (PKIX)" RFC 5912, + June 2010. + + [SECG1] Standards for Efficient Cryptography Group (SECG), "SEC 1: + Elliptic Curve Cryptography", Version 2.0, May 2009. + + [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, 2002. + + [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). + +7.2. Informative References + + [RFC5208] Kaliski, B., "Public-Key Cryptography Standards (PKCS) #8: + Private-Key Information Syntax Specification Version 1.2", + RFC 5208, May 2008. + + + + + + + + + + + + + + +Turner & Brown Informational [Page 5] + +RFC 5915 Elliptic Curve Private Key Structure June 2010 + + +Appendix A. ASN.1 Module + + This appendix provides ASN.1 definitions for the structures described + in this specification using ASN.1 as defined in [X.680], [X.681], + [X.682], and [X.683] for compilers that support the 2002 ASN.1. + + ECPrivateKey { iso(1) identified-organization(3) dod(6) + internet(1) security(5) mechanisms(5) pkix(7) id-mod(0) + id-mod-ecprivateKey(65) } + + DEFINITIONS EXPLICIT TAGS ::= + + BEGIN + + -- EXPORTS ALL; + + IMPORTS + + -- FROM New PKIX ASN.1 [RFC5912] + + ECParameters, NamedCurve + FROM PKIXAlgs-2009 + { iso(1) identified-organization(3) dod(6) internet(1) + security(5) mechanisms(5) pkix(7) id-mod(0) + id-mod-pkix1-algorithms2008-02(56) } + + ; + + ECPrivateKey ::= SEQUENCE { + version INTEGER { ecPrivkeyVer1(1) } (ecPrivkeyVer1), + privateKey OCTET STRING, + parameters [0] ECParameters {{ NamedCurve }} OPTIONAL, + publicKey [1] BIT STRING OPTIONAL + } + + END + +Appendix B. Differences with SECG1 + + This appendix lists the differences between this document and + [SECG1]: + + 1. This document uses the I2OSP routine defined in [RFC3447] while + SECG1 defines its own routine. The two routines result in the + same output. + + + + + + +Turner & Brown Informational [Page 6] + +RFC 5915 Elliptic Curve Private Key Structure June 2010 + + + 2. SECG1 constrains its parameters (i.e., the curves) to + SECGCurveNames. This document constrains the parameters to + NamedCurve from [RFC5480]. + + 3. This document requires parameters be present while SECG1 does + not. + + 4. This document specifies requirements for encoding rules while + SECG1 did not. + +Acknowledgements + + The authors would like to thank Simon Blake-Wilson and John O. Goyo + for their work on defining the structure in [SECG1]. The authors + would also like to thank Pasi Eronen, Alfred Hoenes, Joel Jaegglie, + Avshalom Houri, Russ Housley, Jim Schaad, and Carl Wallace for their + comments. + +Authors' Addresses + + Sean Turner + IECA, Inc. + 3057 Nutley Street, Suite 106 + Fairfax, VA 22031 + USA + + EMail: turners@ieca.com + + + Daniel R. L. Brown + Certicom Corp + 5520 Explorer Drive #400 + Mississauga, ON L4W 5L1 + Canada + + EMail: dbrown@certicom.com + + + + + + + + + + + + + + + +Turner & Brown Informational [Page 7] + diff --git a/docs/rfc/rfc5958.txt b/docs/rfc/rfc5958.txt new file mode 100644 index 0000000..15cf964 --- /dev/null +++ b/docs/rfc/rfc5958.txt @@ -0,0 +1,787 @@ + + + + + + +Internet Engineering Task Force (IETF) S. Turner +Request for Comments: 5958 IECA +Obsoletes: 5208 August 2010 +Category: Standards Track +ISSN: 2070-1721 + + + Asymmetric Key Packages + +Abstract + + This document defines the syntax for private-key information and a + content type for it. Private-key information includes a private key + for a specified public-key algorithm and a set of attributes. The + Cryptographic Message Syntax (CMS), as defined in RFC 5652, can be + used to digitally sign, digest, authenticate, or encrypt the + asymmetric key format content type. This document obsoletes RFC + 5208. + +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/rfc5958. + +Copyright Notice + + Copyright (c) 2010 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. + + + +Turner Standards Track [Page 1] + +RFC 5958 Asymmetric Key Packages August 2010 + + + This document may contain material from IETF Documents or IETF + Contributions published or made publicly available before November + 10, 2008. The person(s) controlling the copyright in some of this + material may not have granted the IETF Trust the right to allow + modifications of such material outside the IETF Standards Process. + Without obtaining an adequate license from the person(s) controlling + the copyright in such materials, this document may not be modified + outside the IETF Standards Process, and derivative works of it may + not be created outside the IETF Standards Process, except to format + it for publication as an RFC or to translate it into languages other + than English. + +1. Introduction + + This document defines the syntax for private-key information and a + Cryptographic Message Syntax (CMS) [RFC5652] content type for it. + Private-key information includes a private key for a specified + public-key algorithm and a set of attributes. The CMS can be used to + digitally sign, digest, authenticate, or encrypt the asymmetric key + format content type. This document obsoletes PKCS #8 v1.2 [RFC5208]. + +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 key package is defined using ASN.1 [X.680], [X.681], [X.682], and + [X.683]. + +1.3. Summary of Updates to RFC 5208 + + The following summarizes the updates to [RFC5208]: + + - Changed the name "PrivateKeyInfo" to "OneAsymmetricKey". This + reflects the addition of the publicKey field to allow both parts of + the asymmetric key to be conveyed separately. Not all algorithms + will use both fields; however, the publicKey field was added for + completeness. + + - Defined Asymmetric Key Package CMS content type. + + - Removed redundant IMPLICIT from attributes. + + - Added publicKey to OneAsymmetricKey and updated the version number. + + + + +Turner Standards Track [Page 2] + +RFC 5958 Asymmetric Key Packages August 2010 + + + - Added that PKCS #9 attributes may be supported. + + - Added discussion of compatibility with other private-key formats. + + - Added requirements for encoding rule set. + + - Changed imports from PKCS #5 to [RFC5912] and [RFC5911]. + + - Replaced ALGORITHM-IDENTIFIER with ALGORITHM from [RFC5912]. + + - Registers application/pkcs8 media type and .p8 file extension. + +2. Asymmetric Key Package CMS Content Type + + The asymmetric key package CMS content type is used to transfer one + or more plaintext asymmetric keys from one party to another. An + asymmetric key package MAY be encapsulated in one or more CMS + protecting content types (see Section 4). Earlier versions of this + specification [RFC5208] did not specify a particular encoding rule + set, but generators SHOULD use DER [X.690] and receivers MUST support + BER [X.690], which also includes DER [X.690]. + + The asymmetric key package content type has the following syntax: + + ct-asymmetric-key-package CONTENT-TYPE ::= + { AsymmetricKeyPackage IDENTIFIED BY id-ct-KP-aKeyPackage } + + id-ct-KP-aKeyPackage 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) 5 + } + + AsymmetricKeyPackage ::= SEQUENCE SIZE (1..MAX) OF OneAsymmetricKey + + OneAsymmetricKey ::= SEQUENCE { + version Version, + privateKeyAlgorithm PrivateKeyAlgorithmIdentifier, + privateKey PrivateKey, + attributes [0] Attributes OPTIONAL, + ..., + [[2: publicKey [1] PublicKey OPTIONAL ]], + ... + } + + + + + + + +Turner Standards Track [Page 3] + +RFC 5958 Asymmetric Key Packages August 2010 + + + PrivateKeyInfo ::= OneAsymmetricKey + + -- PrivateKeyInfo is used by [P12]. If any items tagged as version + -- 2 are used, the version must be v2, else the version should be + -- v1. When v1, PrivateKeyInfo is the same as it was in [RFC5208]. + + Version ::= INTEGER { v1(0), v2(1) } (v1, ..., v2) + + PrivateKeyAlgorithmIdentifier ::= AlgorithmIdentifier + { PUBLIC-KEY, + { PrivateKeyAlgorithms } } + + PrivateKey ::= OCTET STRING + -- Content varies based on type of key. The + -- algorithm identifier dictates the format of + -- the key. + + PublicKey ::= BIT STRING + -- Content varies based on type of key. The + -- algorithm identifier dictates the format of + -- the key. + + Attributes ::= SET OF Attribute { { OneAsymmetricKeyAttributes } } + + The AsymmetricKeyPackage contains one or more OneAsymmetricKey + elements. + + The syntax of OneAsymmetricKey accommodates a version number, an + indication of the asymmetric algorithm to be used with the private + key, a private key, optional keying material attributes (e.g., + userCertificate from [X.520]), and an optional public key. In + general, either the public key or the certificate will be present. + In very rare cases will both the public key and the certificate be + present as this includes two copies of the public key. + OneAsymmetricKey renames the PrivateKeyInfo syntax defined in + [RFC5208]. The new name better reflects the ability to carry both + private- and public-key components. Backwards compatibility with the + original PrivateKeyInfo is preserved via version number. The fields + in OneAsymmetricKey are used as follows: + + - version identifies the version of OneAsymmetricKey. If publicKey + is present, then version is set to v2 else version is set to v1. + + - privateKeyAlgorithm identifies the private-key algorithm and + optionally contains parameters associated with the asymmetric key + pair. The algorithm is identified by an object identifier (OID) + and the format of the parameters depends on the OID, but the + PrivateKeyAlgorithms information object set restricts the + + + +Turner Standards Track [Page 4] + +RFC 5958 Asymmetric Key Packages August 2010 + + + permissible OIDs. The value placed in + privateKeyAlgorithmIdentifier is the value an originator would + apply to indicate which algorithm is to be used with the private + key. + + - privateKey is an OCTET STRING that contains the value of the + private key. The interpretation of the content is defined in the + registration of the private-key algorithm. For example, a DSA key + is an INTEGER, an RSA key is represented as RSAPrivateKey as + defined in [RFC3447], and an Elliptic Curve Cryptography (ECC) key + is represented as ECPrivateKey as defined in [RFC5915]. + + - attributes is OPTIONAL. It contains information corresponding to + the public key (e.g., certificates). The attributes field uses the + class ATTRIBUTE which is restricted by the + OneAsymmetricKeyAttributes information object set. + OneAsymmetricKeyAttributes is an open ended set in this document. + Others documents can constrain these values. Attributes from + [RFC2985] MAY be supported. + + - publicKey is OPTIONAL. When present, it contains the public key + encoded in a BIT STRING. The structure within the BIT STRING, if + any, depends on the privateKeyAlgorithm. For example, a DSA key is + an INTEGER. Note that RSA public keys are included in + RSAPrivateKey (i.e., n and e are present), as per [RFC3447], and + ECC public keys are included in ECPrivateKey (i.e., in the + publicKey field), as per [RFC5915]. + +3. Encrypted Private Key Info + + This section gives the syntax for encrypted private-key information, + which is used by [P12]. + + Encrypted private-key information shall have ASN.1 type + EncryptedPrivateKeyInfo: + + EncryptedPrivateKeyInfo ::= SEQUENCE { + encryptionAlgorithm EncryptionAlgorithmIdentifier, + encryptedData EncryptedData } + + EncryptionAlgorithmIdentifier ::= AlgorithmIdentifier + { CONTENT-ENCRYPTION, + { KeyEncryptionAlgorithms } } + + EncryptedData ::= OCTET STRING + + + + + + +Turner Standards Track [Page 5] + +RFC 5958 Asymmetric Key Packages August 2010 + + + The fields in EncryptedPrivateKeyInfo are used as follows: + + - encryptionAlgorithm identifies the algorithm under which the + private-key information is encrypted. + + - encryptedData is the result of encrypting the private-key + information (i.e., the PrivateKeyInfo). + + The encryption process involves the following two steps: + + 1. The private-key information is encoded, yielding an octet string. + Generators SHOULD use DER [X.690] and receivers MUST support BER + [X.690], which also includes DER [X.690]. + + 2. The result of step 1 is encrypted with the secret key to give an + octet string, the result of the encryption process. + +4. Protecting the AsymmetricKeyPackage + + CMS protecting content types, [RFC5652] and [RFC5083], can be used to + provide security to the AsymmetricKeyPackage: + + - SignedData can be used to apply a digital signature to the + AsymmetricKeyPackage. + + - EncryptedData can be used to encrypt the AsymmetricKeyPackage with + symmetric encryption, where the sender and the receiver already + share the necessary encryption key. + + - EnvelopedData can be used to encrypt the AsymmetricKeyPackage with + symmetric encryption, where the sender and the receiver do not + share the necessary encryption key. + + - AuthenticatedData can be used to protect the AsymmetricKeyPackage + with message authentication codes, where key management information + is handled in a manner similar to EnvelopedData. + + - AuthEnvelopedData can be used to protect the AsymmetricKeyPackage + with algorithms that support authenticated encryption, where key + management information is handled in a manner similar to + EnvelopedData. + +5. Other Private-Key Format Considerations + + This document defines the syntax and the semantics for a content type + that exchanges asymmetric private keys. There are two other formats + that have been used for the transport of asymmetric private keys: + + + + +Turner Standards Track [Page 6] + +RFC 5958 Asymmetric Key Packages August 2010 + + + - Personal Information Exchange (PFX) Syntax Standard [P12], which is + more commonly referred to as PKCS #12 or simply P12, is a transfer + syntax for personal identity information, including private keys, + certificates, miscellaneous secrets, and extensions. + OneAsymmetricKey, PrivateKeyInfo, and EncryptedPrivateKeyInfo can + be carried in a P12 message. The private key information, + OneAsymmetricKey and PrivateKeyInfo, are carried in the P12 keyBag + BAG-TYPE. EncryptedPrivateKeyInfo is carried in the P12 + pkcs8ShroudedKeyBag BAG-TYPE. In current implementations, the file + extensions .pfx and .p12 can be used interchangeably. + + - Microsoft's private-key proprietary transfer syntax. The .pvk file + extension is used for local storage. + + The .pvk and .p12/.pfx formats are not interchangeable; however, + conversion tools exist to convert from one format to another. + + To extract the private-key information from the AsymmetricKeyPackage, + the encapsulating layers need to be removed. At a minimum, the outer + ContentInfo [RFC5652] layer needs to be removed. If the + AsymmetricKeyPackage is encapsulated in a SignedData [RFC5652], then + the SignedData and EncapsulatedContentInfo layers [RFC5652] also need + to be removed. The same is true for EnvelopedData, EncryptedData, + and AuthenticatedData all from [RFC5652] as well as AuthEnvelopedData + from [RFC5083]. Once all the outer layers are removed, there are as + many sets of private-key information as there are OneAsymmetricKey + structures. OneAsymmetricKey and PrivateKeyInfo are the same + structure; therefore, either can be saved as a .p8 file or copied in + to the P12 KeyBag BAG-TYPE. Removing encapsulating security layers + will invalidate any signature and may expose the key to unauthorized + disclosure. + + .p8 files are sometimes PEM-encoded. When .p8 files are PEM encoded + they use the .pem file extension. PEM encoding is either the Base64 + encoding, from Section 4 of [RFC4648], of the DER-encoded + EncryptedPrivateKeyInfo sandwiched between: + + -----BEGIN ENCRYPTED PRIVATE KEY----- + -----END ENCRYPTED PRIVATE KEY----- + + or the Base64 encoding, see Section 4 of [RFC4648], of the DER- + encoded PrivateKeyInfo sandwiched between: + + -----BEGIN PRIVATE KEY----- + -----END PRIVATE KEY----- + + + + + + +Turner Standards Track [Page 7] + +RFC 5958 Asymmetric Key Packages August 2010 + + +6. Security Considerations + + Protection of the private-key information is vital to public-key + cryptography. Disclosure of the private-key material to another + entity can lead to masquerades. The encryption algorithm used in the + encryption process must be as 'strong' as the key it is protecting. + + The asymmetric key package contents are not protected. This content + type can be combined with a security protocol to protect the contents + of the package. + +7. IANA Considerations + + This document makes use of object identifiers to identify a CMS + content type and the ASN.1 module found in Appendix A. The CMS + content type OID is registered in a DoD arc. The ASN.1 module OID is + registered in an arc delegated by RSADSI to the SMIME Working Group. + No further action by IANA is necessary for this document or any + anticipated updates. + + This specification also defines a new media subtype that IANA has + registered at http://www.iana.org/. + +7.1. Registration of media subtype application/pkcs8 + + Type name: application + + Subtype name: pkcs8 + + Required parameters: None + + Optional parameters: None + + Encoding considerations: binary + + Security considerations: Carries a cryptographic private key. + See section 6. + + Interoperability considerations: + + The PKCS #8 object inside this media type MUST be DER-encoded + PrivateKeyInfo. + + Published specification: RFC 5958 + + Applications which use this media type: + + Any MIME-compliant transport that processes asymmetric keys. + + + +Turner Standards Track [Page 8] + +RFC 5958 Asymmetric Key Packages August 2010 + + + Additional information: + + Magic number(s): None + File extension(s): .p8 + Macintosh File Type Code(s): + + Person & email address to contact for further information: + + Sean Turner + + Restrictions on usage: none + + Author: + + Sean Turner + + Intended usage: COMMON + + Change controller: + + The IESG + +8. References + +8.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data + Encodings", RFC 4648, October 2006. + + [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD + 70, RFC 5652, September 2009. + + [RFC5911] Hoffman, P. and J. Schaad, "New ASN.1 Modules for + Cryptographic Message Syntax (CMS) and S/MIME", RFC 5911, + June 2010. + + [RFC5912] Hoffman, P. and J. Schaad, "New ASN.1 Modules for the + Public Key Infrastructure Using X.509 (PKIX)", RFC 5912, + June 2010. + + [X.680] ITU-T Recommendation X.680 (2002) | ISO/IEC 8824-1:2002. + Information Technology - Abstract Syntax Notation One. + + + + + + +Turner Standards Track [Page 9] + +RFC 5958 Asymmetric Key Packages August 2010 + + + [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). + +8.2. Informative References + + [P12] RSA Laboratories, "PKCS #12 v1.0: Personal Information + Exchange Syntax", June 1999. + + [RFC2985] Nystrom, M. and B. Kaliski, "PKCS #9: Selected Object + Classes and Attribute Types Version 2.0", RFC 2985, + November 2000. + + [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography + Standards (PKCS) #1: RSA Cryptography Specifications + Version 2.1", RFC 3447, February 2003. + + [RFC5083] Housley, R., "Cryptographic Message Syntax (CMS) + Authenticated-Enveloped-Data Content Type", RFC 5083, + November 2007. + + [RFC5208] Kaliski, B., "Public-Key Cryptography Standards (PKCS) + #8: Private-Key Information Syntax Specification Version + 1.2", RFC 5208, May 2008. + + [X.520] ITU-T Recommendation X.520 (2005) | ISO/IEC 9594-6:2005, + Information technology - Open Systems Interconnection - + The Directory: Selected attribute types. + + [RFC5915] Turner, S. and D. Brown, "Elliptic Curve Private Key + Structure", RFC 5915, June 2010. + + + + + + +Turner Standards Track [Page 10] + +RFC 5958 Asymmetric Key Packages August 2010 + + +Appendix A. ASN.1 Module + + This annex provides the normative ASN.1 definitions for the + structures described in this specification using ASN.1 as defined in + [X.680] through [X.683]. + + AsymmetricKeyPackageModuleV1 + { iso(1) member-body(2) us(840) rsadsi(113549) pkcs(1) pkcs-9(9) + smime(16) modules(0) id-mod-asymmetricKeyPkgV1(50) } + + DEFINITIONS IMPLICIT TAGS ::= + + BEGIN + + -- EXPORTS ALL + + IMPORTS + + -- FROM New SMIME ASN.1 [RFC5911] + + Attribute{}, CONTENT-TYPE + FROM CryptographicMessageSyntax-2009 + { iso(1) member-body(2) us(840) rsadsi(113549) pkcs(1) pkcs-9(9) + smime(16) modules(0) id-mod-cms-2004-02(41) } + + -- From New PKIX ASN.1 [RFC5912] + ATTRIBUTE + 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) } + + -- From New PKIX ASN.1 [RFC5912] + + AlgorithmIdentifier{}, ALGORITHM, PUBLIC-KEY, CONTENT-ENCRYPTION + FROM AlgorithmInformation-2009 + { iso(1) identified-organization(3) dod(6) internet(1) + security(5) mechanisms(5) pkix(7) id-mod(0) + id-mod-algorithmInformation-02(58) } + + ; + + ContentSet CONTENT-TYPE ::= { + ct-asymmetric-key-package, + ... -- Expect additional content types -- + } + + + + + +Turner Standards Track [Page 11] + +RFC 5958 Asymmetric Key Packages August 2010 + + + ct-asymmetric-key-package CONTENT-TYPE ::= + { AsymmetricKeyPackage IDENTIFIED BY id-ct-KP-aKeyPackage } + + id-ct-KP-aKeyPackage 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) 5 + } + + AsymmetricKeyPackage ::= SEQUENCE SIZE (1..MAX) OF OneAsymmetricKey + + OneAsymmetricKey ::= SEQUENCE { + version Version, + privateKeyAlgorithm PrivateKeyAlgorithmIdentifier, + privateKey PrivateKey, + attributes [0] Attributes OPTIONAL, + ..., + [[2: publicKey [1] PublicKey OPTIONAL ]], + ... + } + + PrivateKeyInfo ::= OneAsymmetricKey + + -- PrivateKeyInfo is used by [P12]. If any items tagged as version + -- 2 are used, the version must be v2, else the version should be + -- v1. When v1, PrivateKeyInfo is the same as it was in [RFC5208]. + + Version ::= INTEGER { v1(0), v2(1) } (v1, ..., v2) + + PrivateKeyAlgorithmIdentifier ::= AlgorithmIdentifier + { PUBLIC-KEY, + { PrivateKeyAlgorithms } } + + PrivateKey ::= OCTET STRING + -- Content varies based on type of key. The + -- algorithm identifier dictates the format of + -- the key. + + PublicKey ::= BIT STRING + -- Content varies based on type of key. The + -- algorithm identifier dictates the format of + -- the key. + + Attributes ::= SET OF Attribute { { OneAsymmetricKeyAttributes } } + + OneAsymmetricKeyAttributes ATTRIBUTE ::= { + ... -- For local profiles + } + + + +Turner Standards Track [Page 12] + +RFC 5958 Asymmetric Key Packages August 2010 + + + -- An alternate representation that makes full use of ASN.1 + -- constraints follows. Also note that PUBLIC-KEY needs to be + -- imported from the new PKIX ASN.1 Algorithm Information module + -- and PrivateKeyAlgorithms needs to be commented out. + + -- OneAsymmetricKey ::= SEQUENCE { + -- version Version, + -- privateKeyAlgorithm SEQUENCE { + -- algorithm PUBLIC-KEY.&id({PublicKeySet}), + -- parameters PUBLIC-KEY.&Params({PublicKeySet} + -- {@privateKeyAlgorithm.algorithm}) + -- OPTIONAL} + -- privateKey OCTET STRING (CONTAINING + -- PUBLIC-KEY.&PrivateKey({PublicKeySet} + -- {@privateKeyAlgorithm.algorithm})), + -- attributes [0] Attributes OPTIONAL, + -- ..., + -- [[2: publicKey [1] BIT STRING (CONTAINING + -- PUBLIC-KEY.&Params({PublicKeySet} + -- {@privateKeyAlgorithm.algorithm}) + -- OPTIONAL, + -- ... + -- } + + EncryptedPrivateKeyInfo ::= SEQUENCE { + encryptionAlgorithm EncryptionAlgorithmIdentifier, + encryptedData EncryptedData } + + EncryptionAlgorithmIdentifier ::= AlgorithmIdentifier + { CONTENT-ENCRYPTION, + { KeyEncryptionAlgorithms } } + + EncryptedData ::= OCTET STRING -- Encrypted PrivateKeyInfo + + PrivateKeyAlgorithms ALGORITHM ::= { + ... -- Extensible + } + + KeyEncryptionAlgorithms ALGORITHM ::= { + ... -- Extensible + } + + END + + + + + + + + +Turner Standards Track [Page 13] + +RFC 5958 Asymmetric Key Packages August 2010 + + +Acknowledgements + + Many thanks go out to the Burt Kaliski and Jim Randall at RSA. + Without the prior version of the document, this one wouldn't exist. + + I'd also like to thank Pasi Eronen, Roni Even, Alfred Hoenes, Russ + Housley, Jim Schaad, and Carl Wallace. + +Author's Address + + Sean Turner + IECA, Inc. + 3057 Nutley Street, Suite 106 + Fairfax, VA 22031 + USA + + EMail: turners@ieca.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Turner Standards Track [Page 14] + diff --git a/docs/rfc/rfc8018.txt b/docs/rfc/rfc8018.txt new file mode 100644 index 0000000..c2053ce --- /dev/null +++ b/docs/rfc/rfc8018.txt @@ -0,0 +1,2243 @@ + + + + + + +Internet Engineering Task Force (IETF) K. Moriarty, Ed. +Request for Comments: 8018 Dell EMC +Obsoletes: 2898 B. Kaliski +Category: Informational Verisign +ISSN: 2070-1721 A. Rusch + RSA + January 2017 + + + PKCS #5: Password-Based Cryptography Specification + Version 2.1 + +Abstract + + This document provides recommendations for the implementation of + password-based cryptography, covering key derivation functions, + encryption schemes, message authentication schemes, and ASN.1 syntax + identifying the techniques. + + This document represents a republication of PKCS #5 v2.1 from RSA + Laboratories' Public-Key Cryptography Standards (PKCS) series. By + publishing this RFC, change control is transferred to the IETF. + + This document also obsoletes RFC 2898. + +Status of This Memo + + This document is not an Internet Standards Track specification; it is + published for informational purposes. + + 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). Not all documents + approved by the IESG are a candidate for any level of Internet + Standard; see Section 2 of RFC 7841. + + 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/rfc8018. + + + + + + + + + + + +Moriarty, et al. Informational [Page 1] + +RFC 8018 PKCS #5 v2.1 January 2017 + + +Copyright Notice + + Copyright (c) 2017 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Moriarty, et al. Informational [Page 2] + +RFC 8018 PKCS #5 v2.1 January 2017 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 + 2. Notation . . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5 + 4. Salt and Iteration Count . . . . . . . . . . . . . . . . . . 7 + 4.1. Salt . . . . . . . . . . . . . . . . . . . . . . . . . . 7 + 4.2. Iteration Count . . . . . . . . . . . . . . . . . . . . . 9 + 5. Key Derivation Functions . . . . . . . . . . . . . . . . . . 9 + 5.1. PBKDF1 . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.2. PBKDF2 . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 6. Encryption Schemes . . . . . . . . . . . . . . . . . . . . . 13 + 6.1. PBES1 . . . . . . . . . . . . . . . . . . . . . . . . . . 13 + 6.1.1. PBES1 Encryption Operation . . . . . . . . . . . . . 13 + 6.1.2. PBES1 Decryption Operation . . . . . . . . . . . . . 15 + 6.2. PBES2 . . . . . . . . . . . . . . . . . . . . . . . . . . 15 + 6.2.1. PBES2 Encryption Operation . . . . . . . . . . . . . 16 + 6.2.2. PBES2 Decryption Operation . . . . . . . . . . . . . 16 + 7. Message Authentication Schemes . . . . . . . . . . . . . . . 17 + 7.1. PBMAC1 . . . . . . . . . . . . . . . . . . . . . . . . . 17 + 7.1.1. PBMAC1 Generation Operation . . . . . . . . . . . . . 17 + 7.1.2. PBMAC1 Verification Operation . . . . . . . . . . . . 18 + 8. Security Considerations . . . . . . . . . . . . . . . . . . . 18 + 9. Normative References . . . . . . . . . . . . . . . . . . . . 19 + Appendix A. ASN.1 Syntax . . . . . . . . . . . . . . . . . . . . 23 + A.1. PBKDF1 . . . . . . . . . . . . . . . . . . . . . . . . . 23 + A.2. PBKDF2 . . . . . . . . . . . . . . . . . . . . . . . . . 23 + A.3. PBES1 . . . . . . . . . . . . . . . . . . . . . . . . . . 25 + A.4. PBES2 . . . . . . . . . . . . . . . . . . . . . . . . . . 26 + A.5. PBMAC1 . . . . . . . . . . . . . . . . . . . . . . . . . 26 + Appendix B. Supporting Techniques . . . . . . . . . . . . . . . 27 + B.1. Pseudorandom Functions . . . . . . . . . . . . . . . . . 28 + B.1.1. HMAC-SHA-1 . . . . . . . . . . . . . . . . . . . . . 28 + B.1.2. HMAC-SHA-2 . . . . . . . . . . . . . . . . . . . . . 29 + B.2. Encryption Schemes . . . . . . . . . . . . . . . . . . . 29 + B.2.1. DES-CBC-Pad . . . . . . . . . . . . . . . . . . . . . 30 + B.2.2. DES-EDE3-CBC-Pad . . . . . . . . . . . . . . . . . . 30 + B.2.3. RC2-CBC-Pad . . . . . . . . . . . . . . . . . . . . . 30 + B.2.4. RC5-CBC-Pad . . . . . . . . . . . . . . . . . . . . . 31 + B.2.5. AES-CBC-Pad . . . . . . . . . . . . . . . . . . . . . 32 + B.3. Message Authentication Schemes . . . . . . . . . . . . . 33 + B.3.1. HMAC-SHA-1 . . . . . . . . . . . . . . . . . . . . . 33 + B.3.2. HMAC-SHA-2 . . . . . . . . . . . . . . . . . . . . . 33 + Appendix C. ASN.1 Module . . . . . . . . . . . . . . . . . . . . 34 + Appendix D. Revision History of PKCS #5 . . . . . . . . . . . . 38 + Appendix E. About PKCS . . . . . . . . . . . . . . . . . . . . . 39 + Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 40 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 40 + + + +Moriarty, et al. Informational [Page 3] + +RFC 8018 PKCS #5 v2.1 January 2017 + + +1. Introduction + + This document provides recommendations for the implementation of + password-based cryptography, covering the following aspects: + + - key derivation functions + - encryption schemes + - message authentication schemes + - ASN.1 syntax identifying the techniques + + The recommendations are intended for general application within + computer and communications systems and, as such, include a fair + amount of flexibility. They are particularly intended for the + protection of sensitive information such as private keys as in + PKCS #8 [PKCS8] [RFC5958]. It is expected that application standards + and implementation profiles based on these specifications may include + additional constraints. + + Other cryptographic techniques based on passwords, such as password- + based key entity authentication and key establishment protocols + [BELLOV] [JABLON] [WU] are outside the scope of this document. + Guidelines for the selection of passwords are also outside the scope. + This document supersedes PKCS #5 version 2.0 [RFC2898] but includes + compatible techniques. + + This document represents a republication of PKCS #5 v2.1 [PKCS5_21] + from RSA Laboratories' Public-Key Cryptography Standards (PKCS) + series. + +2. Notation + + C ciphertext, an octet string + + c iteration count, a positive integer + + DK derived key, an octet string + + dkLen length in octets of derived key, a positive integer + + EM encoded message, an octet string + + Hash underlying hash function + + hLen length in octets of pseudorandom function output, a positive + integer + + l length in blocks of derived key, a positive integer + + + + +Moriarty, et al. Informational [Page 4] + +RFC 8018 PKCS #5 v2.1 January 2017 + + + IV initialization vector, an octet string + + K encryption key, an octet string + + KDF key derivation function + + M message, an octet string + + P password, an octet string + + PRF underlying pseudorandom function + + PS padding string, an octet string + + psLen length in octets of padding string, a positive integer + + S salt, an octet string + + T message authentication code, an octet string + + T_1, ..., T_l, U_1, ..., U_c + intermediate values, octet strings + + 01, 02, ..., 08 + octets with value 1, 2, ..., 8 + + \xor bit-wise exclusive-or of two octet strings + + || || octet length operator + + || concatenation operator + + substring extraction operator: extracts octets i through j, + 0 <= i <= j + +3. Overview + + In many applications of public-key cryptography, user security is + ultimately dependent on one or more secret text values or passwords. + Since a password is not directly applicable as a key to any + conventional cryptosystem, however, some processing of the password + is required to perform cryptographic operations with it. Moreover, + as passwords are often chosen from a relatively small space, special + care is required in that processing to defend against search attacks. + + A general approach to password-based cryptography, as described by + Morris and Thompson [MORRIS] for the protection of password tables, + is to combine a password with a salt to produce a key. The salt can + + + +Moriarty, et al. Informational [Page 5] + +RFC 8018 PKCS #5 v2.1 January 2017 + + + be viewed as an index into a large set of keys derived from the + password and need not be kept secret. Although it may be possible + for an opponent to construct a table of possible passwords (a so- + called "dictionary attack"), constructing a table of possible keys + will be difficult, since there will be many possible keys for each + password. An opponent will thus be limited to searching through + passwords separately for each salt. + + Another approach to password-based cryptography is to construct key + derivation techniques that are relatively expensive, thereby + increasing the cost of exhaustive search. One way to do this is to + include an iteration count in the key derivation technique, + indicating how many times to iterate some underlying function by + which keys are derived. A modest number of iterations (say, 1000) is + not likely to be a burden for legitimate parties when computing a + key, but will be a significant burden for opponents. + + Salt and iteration count formed the basis for password-based + encryption in PKCS #5 v2.0, and are adopted here as well for the + various cryptographic operations. Thus, password-based key + derivation as defined here is a function of a password, a salt, and + an iteration count, where the latter two quantities need not be kept + secret. + + From a password-based key derivation function, it is straightforward + to define password-based encryption and message authentication + schemes. As in PKCS #5 v2.0, the password-based encryption schemes + here are based on an underlying, conventional encryption scheme, + where the key for the conventional scheme is derived from the + password. Similarly, the password-based message authentication + scheme is based on an underlying conventional scheme. This + two-layered approach makes the password-based techniques modular in + terms of the underlying techniques they can be based on. + + It is expected that the password-based key derivation functions may + find other applications than just the encryption and message + authentication schemes defined here. For instance, one might derive + a set of keys with a single application of a key derivation function, + rather than derive each key with a separate application of the + function. The keys in the set would be obtained as substrings of the + output of the key derivation function. This approach might be + employed as part of key establishment in a session-oriented protocol. + Another application is password checking, where the output of the key + derivation function is stored (along with the salt and iteration + count) for the purposes of subsequent verification of a password. + + Throughout this document, a password is considered to be an octet + string of arbitrary length whose interpretation as a text string is + + + +Moriarty, et al. Informational [Page 6] + +RFC 8018 PKCS #5 v2.1 January 2017 + + + unspecified. In the interest of interoperability, however, it is + recommended that applications follow some common text encoding rules. + ASCII and UTF-8 [RFC3629] are two possibilities. (ASCII is a subset + of UTF-8.) + + Although the selection of passwords is outside the scope of this + document, guidelines have been published [NISTSP63] that may well be + taken into account. + +4. Salt and Iteration Count + + Inasmuch as salt and iteration count are central to the techniques + defined in this document, some further discussion is warranted. + +4.1. Salt + + A salt in password-based cryptography has traditionally served the + purpose of producing a large set of keys corresponding to a given + password, one of which is selected at random according to the salt. + An individual key in the set is selected by applying a key derivation + function KDF, as + + DK = KDF (P, S) + + where DK is the derived key, P is the password, and S is the salt. + This has two benefits: + + 1. It is difficult for an opponent to precompute all the keys, or + even the most likely keys, corresponding to a dictionary of + passwords. If the salt is 64 bits long, for instance, there + will be as many as 2^64 keys for each password. An opponent + is thus limited to searching for passwords after a password- + based operation has been performed and the salt is known. + + 2. It is unlikely that the same key will be selected twice. + Again, if the salt is 64 bits long, the chance of "collision" + between keys does not become significant until about 2^32 keys + have been produced, according to the Birthday Paradox. The + fact that collisions are unlikely addresses some concerns + about interactions between multiple uses of the same key that + may arise when using some encryption and authentication + techniques. + + In password-based encryption, the party encrypting a message can gain + assurance that these benefits are realized simply by selecting a + large and sufficiently random salt when deriving an encryption key + from a password. A party generating a message authentication code + can gain such assurance in a similar fashion. + + + +Moriarty, et al. Informational [Page 7] + +RFC 8018 PKCS #5 v2.1 January 2017 + + + The party decrypting a message or verifying a message authentication + code, however, cannot be sure that a salt supplied by another party + has actually been generated at random. It is possible, for instance, + that the salt may have been copied from another password-based + operation in an attempt to exploit interactions between multiple uses + of the same key. For instance, suppose two legitimate parties + exchange an encrypted message, where the encryption key is an 80-bit + key derived from a shared password with some salt. An opponent could + take the salt from that encryption and provide it to one of the + parties as though it were for a 40-bit key. If the party reveals the + result of decryption with the 40-bit key, the opponent may be able to + solve for the 40-bit key. In the case that 40-bit key is the first + half of the 80-bit key, the opponent can then readily solve for the + remaining 40 bits of the 80-bit key. + + To defend against such attacks, either the interaction between + multiple uses of the same key should be carefully analyzed, or the + salt should contain data that explicitly distinguishes between + different operations. For instance, the salt might have an + additional, non-random octet that specifies whether the derived key + is for encryption, for message authentication, or for some other + operation. + + Based on this, the following is recommended for salt selection: + + 1. If there is no concern about interactions between multiple + uses of the same key (or a prefix of that key) with the + password-based encryption and authentication techniques + supported for a given password, then the salt may be generated + at random and need not be checked for a particular format by + the party receiving the salt. It should be at least eight + octets (64 bits) long. + + 2. Otherwise, the salt should contain data that explicitly + distinguishes between different operations and different key + lengths, in addition to a random part that is at least eight + octets long, and this data should be checked or regenerated by + the party receiving the salt. For instance, the salt could + have an additional non-random octet that specifies the purpose + of the derived key. Alternatively, it could be the encoding + of a structure that specifies detailed information about the + derived key, such as the encryption or authentication + technique and a sequence number among the different keys + derived from the password. The particular format of the + additional data is left to the application. + + + + + + +Moriarty, et al. Informational [Page 8] + +RFC 8018 PKCS #5 v2.1 January 2017 + + + Note: If a random number generator or pseudorandom generator is not + available, a deterministic alternative for generating the salt (or + the random part of it) is to apply a password-based key derivation + function to the password and the message M to be processed. For + instance, the salt could be computed with a key derivation function + as S = KDF (P, M). This approach is not recommended if the message M + is known to belong to a small message space (e.g., "Yes" or "No"), + however, since then there will only be a small number of possible + salts. + +4.2. Iteration Count + + An iteration count has traditionally served the purpose of increasing + the cost of producing keys from a password, thereby also increasing + the difficulty of attack. Mathematically, an iteration count of c + will increase the security strength of a password by log2(c) bits + against trial-based attacks like brute force or dictionary attacks. + + Choosing a reasonable value for the iteration count depends on + environment and circumstances, and varies from application to + application. This document follows the recommendations made in FIPS + Special Publication 800-132 [NISTSP132], which says + + The iteration count shall be selected as large as possible, as + long as the time required to generate the key using the entered + password is acceptable for the users. [...] A minimum iteration + count of 1,000 is recommended. For especially critical keys, or + for very powerful systems or systems where user-perceived + performance is not critical, an iteration count of 10,000,000 may + be appropriate. + +5. Key Derivation Functions + + A key derivation function produces a derived key from a base key and + other parameters. In a password-based key derivation function, the + base key is a password, and the other parameters are a salt value and + an iteration count, as outlined in Section 3. + + The primary application of the password-based key derivation + functions defined here is in the encryption schemes in Section 6 and + the message authentication scheme in Section 7. Other applications + are certainly possible, hence the independent definition of these + functions. + + Two functions are specified in this section: PBKDF1 and PBKDF2. + PBKDF2 is recommended for new applications; PBKDF1 is included only + for compatibility with existing applications and is not recommended + for new applications. + + + +Moriarty, et al. Informational [Page 9] + +RFC 8018 PKCS #5 v2.1 January 2017 + + + A typical application of the key derivation functions defined here + might include the following steps: + + 1. Select a salt S and an iteration count c, as outlined in + Section 4. + + 2. Select a length in octets for the derived key, dkLen. + + 3. Apply the key derivation function to the password, the salt, + the iteration count and the key length to produce a derived + key. + + 4. Output the derived key. + + Any number of keys may be derived from a password by varying the + salt, as described in Section 3. + +5.1. PBKDF1 + + PBKDF1 applies a hash function, which shall be MD2 [RFC1319], MD5 + [RFC1321], or SHA-1 [NIST180], to derive keys. The length of the + derived key is bounded by the length of the hash function output, + which is 16 octets for MD2 and MD5 and 20 octets for SHA-1. PBKDF1 + is compatible with the key derivation process in PKCS #5 v1.5 + [PKCS5_15]. + + PBKDF1 is recommended only for compatibility with existing + applications since the keys it produces may not be large enough for + some applications. + + PBKDF1 (P, S, c, dkLen) + + Options: Hash underlying hash function + + Input: P password, an octet string + S salt, an octet string + c iteration count, a positive integer + dkLen intended length in octets of derived key, + a positive integer, at most 16 for MD2 or + MD5 and 20 for SHA-1 + Output: DK derived key, a dkLen-octet string + + Steps: + + 1. If dkLen > 16 for MD2 and MD5, or dkLen > 20 for SHA-1, output + "derived key too long" and stop. + + + + + +Moriarty, et al. Informational [Page 10] + +RFC 8018 PKCS #5 v2.1 January 2017 + + + 2. Apply the underlying hash function Hash for c iterations to + the concatenation of the password P and the salt S, then + extract the first dkLen octets to produce a derived key DK: + + T_1 = Hash (P || S) , + T_2 = Hash (T_1) , + ... + T_c = Hash (T_{c-1}) , + DK = T_c<0..dkLen-1> + + 3. Output the derived key DK. + +5.2. PBKDF2 + + PBKDF2 applies a pseudorandom function (see Appendix B.1 for an + example) to derive keys. The length of the derived key is + essentially unbounded. (However, the maximum effective search space + for the derived key may be limited by the structure of the underlying + pseudorandom function. See Appendix B.1 for further discussion.) + PBKDF2 is recommended for new applications. + + PBKDF2 (P, S, c, dkLen) + + Options: PRF underlying pseudorandom function (hLen + denotes the length in octets of the + pseudorandom function output) + + Input: P password, an octet string + S salt, an octet string + c iteration count, a positive integer + dkLen intended length in octets of the derived + key, a positive integer, at most + (2^32 - 1) * hLen + + Output: DK derived key, a dkLen-octet string + + Steps: + + 1. If dkLen > (2^32 - 1) * hLen, output "derived key too long" + and stop. + + 2. Let l be the number of hLen-octet blocks in the derived key, + rounding up, and let r be the number of octets in the last + block: + + l = CEIL (dkLen / hLen) + r = dkLen - (l - 1) * hLen + + + + +Moriarty, et al. Informational [Page 11] + +RFC 8018 PKCS #5 v2.1 January 2017 + + + Here, CEIL (x) is the "ceiling" function, i.e., the smallest + integer greater than, or equal to, x. + + 3. For each block of the derived key apply the function F defined + below to the password P, the salt S, the iteration count c, + and the block index to compute the block: + + T_1 = F (P, S, c, 1) , + T_2 = F (P, S, c, 2) , + ... + T_l = F (P, S, c, l) , + + where the function F is defined as the exclusive-or sum of the + first c iterates of the underlying pseudorandom function PRF + applied to the password P and the concatenation of the salt S + and the block index i: + + F (P, S, c, i) = U_1 \xor U_2 \xor ... \xor U_c + + where + U_1 = PRF (P, S || INT (i)) , + U_2 = PRF (P, U_1) , + ... + U_c = PRF (P, U_{c-1}) . + + Here, INT (i) is a four-octet encoding of the integer i, most + significant octet first. + + 4. Concatenate the blocks and extract the first dkLen octets to + produce a derived key DK: + + DK = T_1 || T_2 || ... || T_l<0..r-1> + + 5. Output the derived key DK. + + Note: The construction of the function F follows a "belt-and- + suspenders" approach. The iterates U_i are computed recursively to + remove a degree of parallelism from an opponent; they are exclusive- + ored together to reduce concerns about the recursion degenerating + into a small set of values. + + + + + + + + + + + +Moriarty, et al. Informational [Page 12] + +RFC 8018 PKCS #5 v2.1 January 2017 + + +6. Encryption Schemes + + An encryption scheme, in the symmetric setting, consists of an + encryption operation and a decryption operation, where the encryption + operation produces a ciphertext from a message under a key, and the + decryption operation recovers the message from the ciphertext under + the same key. In a password-based encryption scheme, the key is a + password. + + A typical application of a password-based encryption scheme is a + private-key protection method, where the message contains private-key + information, as in PKCS #8. The encryption schemes defined here + would be suitable encryption algorithms in that context. + + Two schemes are specified in this section: PBES1 and PBES2. PBES2 is + recommended for new applications; PBES1 is included only for + compatibility with existing applications and is not recommended for + new applications. + +6.1. PBES1 + + PBES1 combines the PBKDF1 function (Section 5.1) with an underlying + block cipher, which shall be either DES [NIST46] or RC2 [RFC2268] in + cipher block chaining (CBC) mode [NIST81]. PBES1 is compatible with + the encryption scheme in PKCS #5 v1.5 [PKCS5_15]. + + PBES1 is recommended only for compatibility with existing + applications, since it supports only two underlying encryption + schemes, each of which has a key size (56 or 64 bits) that may not be + large enough for some applications. + +6.1.1. PBES1 Encryption Operation + + The encryption operation for PBES1 consists of the following steps, + which encrypt a message M under a password P to produce a ciphertext + C: + + 1. Select an eight-octet salt S and an iteration count c, as + outlined in Section 4. + + 2. Apply the PBKDF1 key derivation function (Section 5.1) to the + password P, the salt S, and the iteration count c to produce a + derived key DK of length 16 octets: + + DK = PBKDF1 (P, S, c, 16) + + + + + + +Moriarty, et al. Informational [Page 13] + +RFC 8018 PKCS #5 v2.1 January 2017 + + + 3. Separate the derived key DK into an encryption key K + consisting of the first eight octets of DK and an + initialization vector IV consisting of the next eight octets: + + K = DK<0..7> + IV = DK<8..15> + + 4. Concatenate M and a padding string PS to form an encoded + message EM: + + EM = M || PS + + where the padding string PS consists of 8-(||M|| mod 8) octets + each with value 8-(||M|| mod 8). The padding string PS will + satisfy one of the following statements: + + PS = 01, if ||M|| mod 8 = 7 ; + PS = 02 02, if ||M|| mod 8 = 6 ; + ... + PS = 08 08 08 08 08 08 08 08, if ||M|| mod 8 = 0. + + The length in octets of the encoded message will be a multiple + of eight, and it will be possible to recover the message M + unambiguously from the encoded message. (This padding rule is + taken from RFC 1423 [RFC1423].) + + 5. Encrypt the encoded message EM with the underlying block + cipher (DES or RC2) in CBC mode under the encryption key K + with initialization vector IV to produce the ciphertext C. + For DES, the key K shall be considered as a 64-bit encoding of + a 56-bit DES key with parity bits ignored (see [NIST46]). For + RC2, the "effective key bits" shall be 64 bits. + + 6. Output the ciphertext C. + + The salt S and the iteration count c may be conveyed to the party + performing decryption in an AlgorithmIdentifier value (see Appendix + A.3). + + + + + + + + + + + + + +Moriarty, et al. Informational [Page 14] + +RFC 8018 PKCS #5 v2.1 January 2017 + + +6.1.2. PBES1 Decryption Operation + + The decryption operation for PBES1 consists of the following steps, + which decrypt a ciphertext C under a password P to recover a message + M: + + 1. Obtain the eight-octet salt S and the iteration count c. + + 2. Apply the PBKDF1 key derivation function (Section 5.1) to the + password P, the salt S, and the iteration count c to produce a + derived key DK of length 16 octets: + + DK = PBKDF1 (P, S, c, 16) + + 3. Separate the derived key DK into an encryption key K + consisting of the first eight octets of DK and an + initialization vector IV consisting of the next eight octets: + + K = DK<0..7> + IV = DK<8..15> + + 4. Decrypt the ciphertext C with the underlying block cipher (DES + or RC2) in CBC mode under the encryption key K with + initialization vector IV to recover an encoded message EM. If + the length in octets of the ciphertext C is not a multiple of + eight, output "decryption error" and stop. + + 5. Separate the encoded message EM into a message M and a padding + string PS: + + EM = M || PS + + where the padding string PS consists of some number psLen + octets each with value psLen, where psLen is between 1 and 8. + If it is not possible to separate the encoded message EM in + this manner, output "decryption error" and stop. + + 6. Output the recovered message M. + +6.2. PBES2 + + PBES2 combines a password-based key derivation function, which shall + be PBKDF2 (Section 5.2) for this version of PKCS #5, with an + underlying encryption scheme (see Appendix B.2 for examples). The + key length and any other parameters for the underlying encryption + scheme depend on the scheme. + + PBES2 is recommended for new applications. + + + +Moriarty, et al. Informational [Page 15] + +RFC 8018 PKCS #5 v2.1 January 2017 + + +6.2.1. PBES2 Encryption Operation + + The encryption operation for PBES2 consists of the following steps, + which encrypt a message M under a password P to produce a ciphertext + C, applying a selected key derivation function KDF and a selected + underlying encryption scheme: + + 1. Select a salt S and an iteration count c, as outlined in + Section 4. + + 2. Select the length in octets, dkLen, for the derived key for + the underlying encryption scheme. + + 3. Apply the selected key derivation function to the password P, + the salt S, and the iteration count c to produce a derived key + DK of length dkLen octets: + + DK = KDF (P, S, c, dkLen) + + 4. Encrypt the message M with the underlying encryption scheme + under the derived key DK to produce a ciphertext C. (This + step may involve selection of parameters such as an + initialization vector and padding, depending on the underlying + scheme.) + + 5. Output the ciphertext C. + + The salt S, the iteration count c, the key length dkLen, and + identifiers for the key derivation function and the underlying + encryption scheme may be conveyed to the party performing decryption + in an AlgorithmIdentifier value (see Appendix A.4). + +6.2.2. PBES2 Decryption Operation + + The decryption operation for PBES2 consists of the following steps, + which decrypt a ciphertext C under a password P to recover a message + M: + + 1. Obtain the salt S for the operation. + + 2. Obtain the iteration count c for the key derivation function. + + 3. Obtain the key length in octets, dkLen, for the derived key + for the underlying encryption scheme. + + + + + + + +Moriarty, et al. Informational [Page 16] + +RFC 8018 PKCS #5 v2.1 January 2017 + + + 4. Apply the selected key derivation function to the password P, + the salt S, and the iteration count c to produce a derived key + DK of length dkLen octets: + + DK = KDF (P, S, c, dkLen) + + 5. Decrypt the ciphertext C with the underlying encryption scheme + under the derived key DK to recover a message M. If the + decryption function outputs "decryption error", then output + "decryption error" and stop. + + 6. Output the recovered message M. + +7. Message Authentication Schemes + + A message authentication scheme consists of a MAC (Message + Authentication Code) generation operation and a MAC verification + operation, where the MAC generation operation produces a MAC from a + message under a key, and the MAC verification operation verifies the + message authentication code under the same key. In a password-based + message authentication scheme, the key is a password. + + One scheme is specified in this section: PBMAC1. + +7.1. PBMAC1 + + PBMAC1 combines a password-based key derivation function, which shall + be PBKDF2 (Section 5.2) for this version of PKCS #5, with an + underlying message authentication scheme (see Appendix B.3 for an + example). The key length and any other parameters for the underlying + message authentication scheme depend on the scheme. + +7.1.1. PBMAC1 Generation Operation + + The MAC generation operation for PBMAC1 consists of the following + steps, which process a message M under a password P to generate a + message authentication code T, applying a selected key derivation + function KDF and a selected underlying message authentication scheme: + + 1. Select a salt S and an iteration count c, as outlined in + Section 4. + + 2. Select a key length in octets, dkLen, for the derived key for + the underlying message authentication function. + + + + + + + +Moriarty, et al. Informational [Page 17] + +RFC 8018 PKCS #5 v2.1 January 2017 + + + 3. Apply the selected key derivation function to the password P, + the salt S, and the iteration count c to produce a derived key + DK of length dkLen octets: + + DK = KDF (P, S, c, dkLen) + + 4. Process the message M with the underlying message + authentication scheme under the derived key DK to generate a + message authentication code T. + + 5. Output the message authentication code T. + + The salt S, the iteration count c, the key length dkLen, and + identifiers for the key derivation function and underlying message + authentication scheme may be conveyed to the party performing + verification in an AlgorithmIdentifier value (see Appendix A.5). + +7.1.2. PBMAC1 Verification Operation + + The MAC verification operation for PBMAC1 consists of the following + steps, which process a message M under a password P to verify a + message authentication code T: + + 1. Obtain the salt S and the iteration count c. + + 2. Obtain the key length in octets, dkLen, for the derived key + for the underlying message authentication scheme. + + 3. Apply the selected key derivation function to the password P, + the salt S, and the iteration count c to produce a derived key + DK of length dkLen octets: + + DK = KDF (P, S, c, dkLen) + + 4. Process the message M with the underlying message + authentication scheme under the derived key DK to verify the + message authentication code T. + + 5. If the message authentication code verifies, output "correct"; + else output "incorrect". + +8. Security Considerations + + Password-based cryptography is generally limited in the security that + it can provide, particularly for methods such as those defined in + this document where offline password search is possible. While the + use of salt and iteration count can increase the complexity of attack + (see Section 4 for recommendations), it is essential that passwords + + + +Moriarty, et al. Informational [Page 18] + +RFC 8018 PKCS #5 v2.1 January 2017 + + + are selected well, and relevant guidelines (e.g., [NISTSP63]) should + be taken into account. It is also important that passwords be + protected well if stored. + + In general, different keys should be derived from a password for + different uses to minimize the possibility of unintended + interactions. For password-based encryption with a single algorithm, + a random salt is sufficient to ensure that different keys will be + produced. In certain other situations, as outlined in Section 4, a + structured salt is necessary. The recommendations in Section 4 + should thus be taken into account when selecting the salt value. + + For information on security considerations for MD2 [RFC1319], see + [RFC6149]; for MD5 [RFC1321], see [RFC6151]; and for SHA-1 [NIST180], + see [RFC6194]. + +9. Normative References + + [ANSIX952] ANSI, "Triple Data Encryption Algorithm Modes of + Operation", Accredited Standards Committee X9, X9.52-1998, + July 1998. + + [BELLOV] Bellovin, S. and M. Merritt, "Encrypted Key Exchange: + Password-based Protocols Secure against Dictionary + Attacks", Proceedings of the IEEE Symposium on Research in + Security and Privacy, pages 72-84, IEEE Computer Society, + DOI 10.1109/RISP.1992.213269, 1992. + + [COCHRAN] Cochran, M., "Notes on the Wang et al. 2^63 SHA-1 + Differential Path", Cryptology ePrint Archive: Report + 2007/474, August 2008, . + + [ISO8824-1] + International Organization for Standardization, + "Information technology - Abstract Syntax Notation One + (ASN.1) - Specification of basic notation", ISO/IEC + 8824-1:2008, 2008. + + [ISO8824-2] + International Organization for Standardization, + "Information technology - Abstract Syntax Notation One + (ASN.1) - Information object specification", ISO/IEC + 8824-2:2008, 2008. + + + + + + + + +Moriarty, et al. Informational [Page 19] + +RFC 8018 PKCS #5 v2.1 January 2017 + + + [ISO8824-3] + International Organization for Standardization, + "Information technology - Abstract Syntax Notation One + (ASN.1) - Constraint specification", ISO/IEC 8824-3:2008, + 2008. + + [ISO8824-4] + International Organization for Standardization, + "Information technology - Abstract Syntax Notation One + (ASN.1) - Parameterization of ASN.1 specifications", + ISO/IEC 8824-4:2008, 2008. + + [JABLON] Jablon, D., "Strong Password-Only Authenticated Key + Exchange", ACM SIGCOMM Computer Communication Review, + Volume 26, Issue 5, DOI 10.1145/242896.242897, October + 1996. + + [MORRIS] Morris, R. and K. Thompson, "Password security: A case + history", Communications of the ACM, Vol. 22, Issue 11, + pages 594-597, DOI 10.1145/359168.359172, November 1979. + + [NIST46] National Institute of Standards and Technology (NIST), + "Data Encryption Standard", FIPS PUB 46-3, October 1999. + + [NIST81] National Institute of Standards and Technology (NIST), + "DES Modes of Operation", FIPS PUB 81, December 2, 1980. + + [NIST180] National Institute of Standards and Technology, "Secure + Hash Standard (SHS)", FIPS PUB 180-4, + DOI 10.6028/NIST.FIPS.180-4, August 2015. + + [NIST197] National Institute of Standards and Technology (NIST), + "Advance Encryption Standard (AES)", FIPS PUB 197, + November 2001. + + [NIST198] National Institute of Standards and Technology (NIST), + "The Keyed - Hash Message Authentication Code (HMAC)", + FIPS PUB 198-1, July 2008. + + [NISTSP63] National Institute of Standards and Technology (NIST), + "Electronic Authentication Guideline", NIST Special + Publication 800-63-2, DOI 10.6028/NIST.SP.800-63-2, August + 2013. + + + + + + + + +Moriarty, et al. Informational [Page 20] + +RFC 8018 PKCS #5 v2.1 January 2017 + + + [NISTSP132] + National Institute of Standards and Technology (NIST), + "Recommendation for Password-Based Key Derivation, Part 1: + Storage Applications", NIST Special Publication 800-132, + DOI 10.6028/NIST.SP.800-132, December 2010. + + [PKCS5_15] RSA Laboratories, "PKCS #5: Password-Based Encryption + Standard Version 1.5", November 1993. + + [PKCS5_21] RSA Laboratories, "PKCS #5: Password-Based Encryption + Standard Version 2.1", October 2012. + + [PKCS8] Kaliski, B., "Public-Key Cryptography Standards (PKCS) #8: + Private-Key Information Syntax Specification Version 1.2", + RFC 5208, DOI 10.17487/RFC5208, May 2008, + . + + [RC5] Rivest, R.L., "The RC5 encryption algorithm", In + Proceedings of the Second International Workshop on Fast + Software Encryption, pages 86-96, Springer-Verlag, + DOI 10.1007/3-540-60590-8_7, 1994. + + [RFC1319] Kaliski, B., "The MD2 Message-Digest Algorithm", RFC 1319, + DOI 10.17487/RFC1319, April 1992, + . + + [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, + DOI 10.17487/RFC1321, April 1992, + . + + [RFC1423] Balenson, D., "Privacy Enhancement for Internet Electronic + Mail: Part III: Algorithms, Modes, and Identifiers", + RFC 1423, DOI 10.17487/RFC1423, February 1993, + . + + [RFC2040] Baldwin, R. and R. Rivest, "The RC5, RC5-CBC, RC5-CBC-Pad, + and RC5-CTS Algorithms", RFC 2040, DOI 10.17487/RFC2040, + October 1996, . + + [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- + Hashing for Message Authentication", RFC 2104, + DOI 10.17487/RFC2104, February 1997, + . + + [RFC2268] Rivest, R., "A Description of the RC2(r) Encryption + Algorithm", RFC 2268, DOI 10.17487/RFC2268, March 1998, + . + + + + +Moriarty, et al. Informational [Page 21] + +RFC 8018 PKCS #5 v2.1 January 2017 + + + [RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography + Specification Version 2.0", RFC 2898, + DOI 10.17487/RFC2898, September 2000, + . + + [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November + 2003, . + + [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, + RFC 5652, DOI 10.17487/RFC5652, September 2009, + . + + [RFC5958] Turner, S., "Asymmetric Key Packages", RFC 5958, + DOI 10.17487/RFC5958, August 2010, + . + + [RFC6149] Turner, S. and L. Chen, "MD2 to Historic Status", + RFC 6149, DOI 10.17487/RFC6149, March 2011, + . + + [RFC6151] Turner, S. and L. Chen, "Updated Security Considerations + for the MD5 Message-Digest and the HMAC-MD5 Algorithms", + RFC 6151, DOI 10.17487/RFC6151, March 2011, + . + + [RFC6194] Polk, T., Chen, L., Turner, S., and P. Hoffman, "Security + Considerations for the SHA-0 and SHA-1 Message-Digest + Algorithms", RFC 6194, DOI 10.17487/RFC6194, March 2011, + . + + [WANG] Wang, X., Yao, A.C., and F. Yao, "Cryptanalysis on SHA-1", + presented by Adi Shamir at the rump session of CRYPTO + 2005, . + + [WU] Wu, T., "The Secure Remote Password protocol", In + Proceedings of the 1998 Internet Society Network and + Distributed System Security Symposium, pages 97-111, + Internet Society, 1998, + . + + + + + + + + + + +Moriarty, et al. Informational [Page 22] + +RFC 8018 PKCS #5 v2.1 January 2017 + + +Appendix A. ASN.1 Syntax + + This section defines ASN.1 syntax for the key derivation functions, + the encryption schemes, the message authentication scheme, and + supporting techniques. The intended application of these definitions + includes PKCS #8 and other syntax for key management, encrypted data, + and integrity-protected data. (Various aspects of ASN.1 are + specified in several ISO/IEC standards [ISO8824-1] [ISO8824-2] + [ISO8824-3] [ISO8824-4].) + + The object identifier pkcs-5 identifies the arc of the OID tree from + which the OIDs (specific to PKCS #5) in this section are derived: + + rsadsi OBJECT IDENTIFIER ::= {iso(1) member-body(2) us(840) 113549} + pkcs OBJECT IDENTIFIER ::= {rsadsi 1} + pkcs-5 OBJECT IDENTIFIER ::= {pkcs 5} + +A.1. PBKDF1 + + No object identifier is given for PBKDF1, as the object identifiers + for PBES1 are sufficient for existing applications, and PBKDF2 is + recommended for new applications. + +A.2. PBKDF2 + + The object identifier id-PBKDF2 identifies the PBKDF2 key derivation + function (Section 5.2). + + id-PBKDF2 OBJECT IDENTIFIER ::= {pkcs-5 12} + + The parameters field associated with this OID in an + AlgorithmIdentifier shall have type PBKDF2-params: + + PBKDF2-params ::= SEQUENCE { + salt CHOICE { + specified OCTET STRING, + otherSource AlgorithmIdentifier {{PBKDF2-SaltSources}} + }, + iterationCount INTEGER (1..MAX), + keyLength INTEGER (1..MAX) OPTIONAL, + prf AlgorithmIdentifier {{PBKDF2-PRFs}} DEFAULT + algid-hmacWithSHA1 } + + + + + + + + + +Moriarty, et al. Informational [Page 23] + +RFC 8018 PKCS #5 v2.1 January 2017 + + + The fields of type PBKDF2-params have the following meanings: + + - salt specifies the salt value or the source of the salt value. + It shall either be an octet string or an algorithm ID with an + OID in the set PBKDF2-SaltSources, which is reserved for future + versions of PKCS #5. + + The salt-source approach is intended to indicate how the salt + value is to be generated as a function of parameters in the + algorithm ID, application data, or both. For instance, it may + indicate that the salt value is produced from the encoding of a + structure that specifies detailed information about the derived + key as suggested in Section 4.1. Some of the information may + be carried elsewhere, e.g., in the encryption algorithm ID. + However, such facilities are deferred to a future version of + PKCS #5. + + In this version, an application may achieve the benefits + mentioned in Section 4.1 by choosing a particular + interpretation of the salt value in the specified alternative. + + PBKDF2-SaltSources ALGORITHM-IDENTIFIER ::= { ... } + + - iterationCount specifies the iteration count. The maximum + iteration count allowed depends on the implementation. It is + expected that implementation profiles may further constrain the + bounds. + + - keyLength, an optional field, is the length in octets of the + derived key. The maximum key length allowed depends on the + implementation; it is expected that implementation profiles may + further constrain the bounds. The field is provided for + convenience only; the key length is not cryptographically + protected. If there is concern about interaction between + operations with different key lengths for a given salt (see + Section 4.1), the salt should distinguish among the different + key lengths. + + - prf identifies the underlying pseudorandom function. It shall + be an algorithm ID with an OID in the set PBKDF2-PRFs, which + for this version of PKCS #5 shall consist of id-hmacWithSHA1 + (see Appendix B.1.1) and any other OIDs defined by the + application. + + + + + + + + +Moriarty, et al. Informational [Page 24] + +RFC 8018 PKCS #5 v2.1 January 2017 + + + PBKDF2-PRFs ALGORITHM-IDENTIFIER ::= { + {NULL IDENTIFIED BY id-hmacWithSHA1}, + {NULL IDENTIFIED BY id-hmacWithSHA224}, + {NULL IDENTIFIED BY id-hmacWithSHA256}, + {NULL IDENTIFIED BY id-hmacWithSHA384}, + {NULL IDENTIFIED BY id-hmacWithSHA512}, + {NULL IDENTIFIED BY id-hmacWithSHA512-224}, + {NULL IDENTIFIED BY id-hmacWithSHA512-256}, + ... + } + + The default pseudorandom function is HMAC-SHA-1: + + algid-hmacWithSHA1 AlgorithmIdentifier {{PBKDF2-PRFs}} ::= + {algorithm id-hmacWithSHA1, parameters NULL : NULL} + +A.3. PBES1 + + Different object identifiers identify the PBES1 encryption scheme + (Section 6.1) according to the underlying hash function in the key + derivation function and the underlying block cipher, as summarized in + the following table: + + Hash Function Block Cipher OID + MD2 DES pkcs-5.1 + MD2 RC2 pkcs-5.4 + MD5 DES pkcs-5.3 + MD5 RC2 pkcs-5.6 + SHA-1 DES pkcs-5.10 + SHA-1 RC2 pkcs-5.11 + + pbeWithMD2AndDES-CBC OBJECT IDENTIFIER ::= {pkcs-5 1} + pbeWithMD2AndRC2-CBC OBJECT IDENTIFIER ::= {pkcs-5 4} + pbeWithMD5AndDES-CBC OBJECT IDENTIFIER ::= {pkcs-5 3} + pbeWithMD5AndRC2-CBC OBJECT IDENTIFIER ::= {pkcs-5 6} + pbeWithSHA1AndDES-CBC OBJECT IDENTIFIER ::= {pkcs-5 10} + pbeWithSHA1AndRC2-CBC OBJECT IDENTIFIER ::= {pkcs-5 11} + + For each OID, the parameters field associated with the OID in an + AlgorithmIdentifier shall have type PBEParameter: + + PBEParameter ::= SEQUENCE { + salt OCTET STRING (SIZE(8)), + iterationCount INTEGER } + + + + + + + +Moriarty, et al. Informational [Page 25] + +RFC 8018 PKCS #5 v2.1 January 2017 + + + The fields of type PBEParameter have the following meanings: + + - salt specifies the salt value, an eight-octet string. + + - iterationCount specifies the iteration count. + +A.4. PBES2 + + The object identifier id-PBES2 identifies the PBES2 encryption scheme + (Section 6.2). + + id-PBES2 OBJECT IDENTIFIER ::= {pkcs-5 13} + + The parameters field associated with this OID in an + AlgorithmIdentifier shall have type PBES2-params: + + PBES2-params ::= SEQUENCE { + keyDerivationFunc AlgorithmIdentifier {{PBES2-KDFs}}, + encryptionScheme AlgorithmIdentifier {{PBES2-Encs}} } + + The fields of type PBES2-params have the following meanings: + + - keyDerivationFunc identifies the underlying key derivation + function. It shall be an algorithm ID with an OID in the set + PBES2-KDFs, which for this version of PKCS #5 shall consist of + id-PBKDF2 (Appendix A.2). + + PBES2-KDFs ALGORITHM-IDENTIFIER ::= + { {PBKDF2-params IDENTIFIED BY id-PBKDF2}, ... } + + - encryptionScheme identifies the underlying encryption scheme. + It shall be an algorithm ID with an OID in the set PBES2-Encs, + whose definition is left to the application. Examples of + underlying encryption schemes are given in Appendix B.2. + + PBES2-Encs ALGORITHM-IDENTIFIER ::= { ... } + +A.5. PBMAC1 + + The object identifier id-PBMAC1 identifies the PBMAC1 message + authentication scheme (Section 7.1). + + id-PBMAC1 OBJECT IDENTIFIER ::= {pkcs-5 14} + + + + + + + + +Moriarty, et al. Informational [Page 26] + +RFC 8018 PKCS #5 v2.1 January 2017 + + + The parameters field associated with this OID in an + AlgorithmIdentifier shall have type PBMAC1-params: + + PBMAC1-params ::= SEQUENCE { + keyDerivationFunc AlgorithmIdentifier {{PBMAC1-KDFs}}, + messageAuthScheme AlgorithmIdentifier {{PBMAC1-MACs}} } + + The keyDerivationFunc field has the same meaning as the corresponding + field of PBES2-params (Appendix A.4) except that the set of OIDs is + PBMAC1-KDFs. + + PBMAC1-KDFs ALGORITHM-IDENTIFIER ::= + { {PBKDF2-params IDENTIFIED BY id-PBKDF2}, ... } + + The messageAuthScheme field identifies the underlying message + authentication scheme. It shall be an algorithm ID with an OID in + the set PBMAC1-MACs, whose definition is left to the application. + Examples of underlying encryption schemes are given in Appendix B.3. + + PBMAC1-MACs ALGORITHM-IDENTIFIER ::= { ... } + +Appendix B. Supporting Techniques + + This section gives several examples of underlying functions and + schemes supporting the password-based schemes in Sections 5, 6, and + 7. + + While these supporting techniques are appropriate for applications to + implement, none of them is required to be implemented. It is + expected, however, that profiles for PKCS #5 will be developed that + specify particular supporting techniques. + + This section also gives object identifiers for the supporting + techniques. The object identifiers digestAlgorithm and + encryptionAlgorithm identify the arcs from which certain algorithm + OIDs referenced in this section are derived: + + digestAlgorithm OBJECT IDENTIFIER ::= {rsadsi 2} encryptionAlgorithm + OBJECT IDENTIFIER ::= {rsadsi 3} + + + + + + + + + + + + +Moriarty, et al. Informational [Page 27] + +RFC 8018 PKCS #5 v2.1 January 2017 + + +B.1. Pseudorandom Functions + + Examples of pseudorandom function for PBKDF2 (Section 5.2) include + HMAC with SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, SHA-512/224, and + SHA-512/256. Applications may employ other schemes as well. + +B.1.1. HMAC-SHA-1 + + HMAC-SHA-1 is the pseudorandom function corresponding to the HMAC + message authentication code [RFC2104] based on the SHA-1 hash + function [NIST180]. The pseudorandom function is the same function + by which the message authentication code is computed, with a full- + length output. (The first argument to the pseudorandom function PRF + serves as HMAC's "key", and the second serves as HMAC's "text". In + the case of PBKDF2, the "key" is thus the password and the "text" is + the salt.) HMAC-SHA-1 has a variable key length and a 20-octet + (160-bit) output value. + + Although the length of the key to HMAC-SHA-1 is essentially + unbounded, the effective search space for pseudorandom function + outputs may be limited by the structure of the function. In + particular, when the key is longer than 512 bits, HMAC-SHA-1 will + first hash it to 160 bits. Thus, even if a long derived key + consisting of several pseudorandom function outputs is produced from + a key, the effective search space for the derived key will be at most + 160 bits. Although the specific limitation for other key sizes + depends on details of the HMAC construction, one should assume, to be + conservative, that the effective search space is limited to 160 bits + for other key sizes as well. + + (The 160-bit limitation should not generally pose a practical + limitation in the case of password-based cryptography, since the + search space for a password is unlikely to be greater than 160 bits.) + + The object identifier id-hmacWithSHA1 identifies the HMAC-SHA-1 + pseudorandom function: + + id-hmacWithSHA1 OBJECT IDENTIFIER ::= {digestAlgorithm 7} + + The parameters field associated with this OID in an + AlgorithmIdentifier shall have type NULL. This object identifier is + employed in the object set PBKDF2-PRFs (Appendix A.2). + + Note: Although HMAC-SHA-1 was designed as a message authentication + code, its proof of security is readily modified to accommodate + requirements for a pseudorandom function, under stronger assumptions. + A hash function may also meet the requirements of a pseudorandom + function under certain assumptions. For instance, the direct + + + +Moriarty, et al. Informational [Page 28] + +RFC 8018 PKCS #5 v2.1 January 2017 + + + application of a hash function to the concatenation of the "key" and + the "text" may be appropriate, provided that "text" has appropriate + structure to prevent certain attacks. HMAC-SHA-1 is preferable, + however, because it treats "key" and "text" as separate arguments and + does not require "text" to have any structure. + + During 2004 and 2005, there were a number of attacks on SHA-1 that + reduced its perceived effective strength against collision attacks to + 62 bits instead of the expected 80 bits (e.g., Wang et al. [WANG], + confirmed by M. Cochran [COCHRAN]). However, since these attacks + centered on finding collisions between values, they are not a direct + security consideration here because the collision-resistant property + is not required by the HMAC authentication scheme. + +B.1.2. HMAC-SHA-2 + + HMAC-SHA-2 refers to the set of pseudorandom functions corresponding + to the HMAC message authentication code (now a FIPS standard + [NIST198]) based on the new SHA-2 functions (FIPS 180-4 [NIST180]). + HMAC-SHA-2 has a variable key length and variable output value + depending on the hash function chosen (SHA-224, SHA-256, SHA-384, + SHA-512, SHA-512/224, or SHA-512/256) -- that is, 28, 32, 48, or 64 + octets. + + Using the new hash functions extends the search space for the + produced keys. Where SHA-1 limits the search space to 20 octets, + SHA-2 sets new limits of 28, 32, 48, and 64 octets. + + Object identifiers for HMAC are defined as follows: + + id-hmacWithSHA224 OBJECT IDENTIFIER ::= {digestAlgorithm 8} + id-hmacWithSHA256 OBJECT IDENTIFIER ::= {digestAlgorithm 9} + id-hmacWithSHA384 OBJECT IDENTIFIER ::= {digestAlgorithm 10} + id-hmacWithSHA512 OBJECT IDENTIFIER ::= {digestAlgorithm 11} + id-hmacWithSHA512-224 OBJECT IDENTIFIER ::= {digestAlgorithm 12} + id-hmacWithSHA512-256 OBJECT IDENTIFIER ::= {digestAlgorithm 13} + +B.2. Encryption Schemes + + An example encryption scheme for PBES2 (Section 6.2) is AES-CBC-Pad. + The schemes defined in PKCS #5 v2.0 [RFC2898], DES-CBC-Pad, + DES-EDE3-CBC-Pad, RC2-CBC-Pad, and RC5-CBC-Pad, are still supported, + but DES-CBC-Pad, DES-EDE3-CBC-Pad, RC2-CBC-Pad are now considered + legacy and should only be used for backwards compatibility reasons. + + The object identifiers given in this section are intended to be + employed in the object set PBES2-Encs (Appendix A.4). + + + + +Moriarty, et al. Informational [Page 29] + +RFC 8018 PKCS #5 v2.1 January 2017 + + +B.2.1. DES-CBC-Pad + + DES-CBC-Pad is single-key DES [NIST46] in CBC mode [NIST81] with the + padding operation specified in RFC 1423 [RFC1423] (see Section 6.1.1 + of this document). DES-CBC-Pad has an eight-octet encryption key and + an eight-octet initialization vector. The key is considered as a + 64-bit encoding of a 56-bit DES key with parity bits ignored. + + The object identifier desCBC (defined in the NIST/OSI Implementors' + Workshop agreements) identifies the DES-CBC-Pad encryption scheme: + + desCBC OBJECT IDENTIFIER ::= + {iso(1) identified-organization(3) oiw(14) secsig(3) + algorithms(2) 7} + + The parameters field associated with this OID in an + AlgorithmIdentifier shall have type OCTET STRING (SIZE(8)), + specifying the initialization vector for CBC mode. + +B.2.2. DES-EDE3-CBC-Pad + + DES-EDE3-CBC-Pad is three-key triple-DES in CBC mode [ANSIX952] with + the padding operation specified in RFC 1423 [RFC1423]. + DES-EDE3-CBC-Pad has a 24-octet encryption key and an eight-octet + initialization vector. The key is considered as the concatenation of + three eight-octet keys, each of which is a 64-bit encoding of a + 56-bit DES key with parity bits ignored. + + The object identifier des-EDE3-CBC identifies the DES-EDE3-CBC-Pad + encryption scheme: + + des-EDE3-CBC OBJECT IDENTIFIER ::= {encryptionAlgorithm 7} + + The parameters field associated with this OID in an + AlgorithmIdentifier shall have type OCTET STRING (SIZE(8)), + specifying the initialization vector for CBC mode. + + Note: An OID for DES-EDE3-CBC without padding is given in ANSI X9.52 + [ANSIX952]; the one given here is preferred since it specifies + padding. + +B.2.3. RC2-CBC-Pad + + RC2-CBC-Pad is the RC2 encryption algorithm [RFC2268] in CBC mode + with the padding operation specified in RFC 1423 [RFC1423]. + RC2-CBC-Pad has a variable key length, from one to 128 octets, a + separate "effective key bits" parameter from one to 1024 bits that + + + + +Moriarty, et al. Informational [Page 30] + +RFC 8018 PKCS #5 v2.1 January 2017 + + + limits the effective search space independent of the key length, and + an eight-octet initialization vector. + + The object identifier rc2CBC identifies the RC2-CBC-Pad encryption + scheme: + + rc2CBC OBJECT IDENTIFIER ::= {encryptionAlgorithm 2} + + The parameters field associated with OID in an AlgorithmIdentifier + shall have type RC2-CBC-Parameter: + + RC2-CBC-Parameter ::= SEQUENCE { + rc2ParameterVersion INTEGER OPTIONAL, + iv OCTET STRING (SIZE(8)) } + + The fields of type RC2-CBCParameter have the following meanings: + + - rc2ParameterVersion is a proprietary RSA Security Inc. encoding + of the "effective key bits" for RC2. The following encodings + are defined: + + Effective Key Bits Encoding + 40 160 + 64 120 + 128 58 + b >= 256 b + + If the rc2ParameterVersion field is omitted, the "effective key bits" + defaults to 32. (This is for backward compatibility with certain + very old implementations.) + + - iv is the eight-octet initialization vector. + +B.2.4. RC5-CBC-Pad + + RC5-CBC-Pad is the RC5 encryption algorithm [RC5] in CBC mode with + the padding operation specified in RFC 5652 [RFC5652], which is a + generalization of the padding operation specified in RFC 1423 + [RFC1423]. The scheme is fully specified in [RFC2040]. RC5-CBC-Pad + has a variable key length, from 0 to 256 octets, and supports both a + 64-bit block size and a 128-bit block size. For the former, it has + an eight-octet initialization vector, and for the latter, a 16-octet + initialization vector. RC5-CBC-Pad also has a variable number of + "rounds" in the encryption operation, from 8 to 127. + + + + + + + +Moriarty, et al. Informational [Page 31] + +RFC 8018 PKCS #5 v2.1 January 2017 + + + Note: For RC5 with a 64-bit block size, the padding string is as + defined in RFC 1423 [RFC1423]. For RC5 with a 128-bit block size, + the padding string consists of 16-(||M|| mod 16) octets each with + value 16-(||M|| mod 16). + + The object identifier rc5-CBC-PAD [RFC2040] identifies the + RC5-CBC-Pad encryption scheme: + + rc5-CBC-PAD OBJECT IDENTIFIER ::= {encryptionAlgorithm 9} + + The parameters field associated with this OID in an + AlgorithmIdentifier shall have type RC5-CBC-Parameters: + + RC5-CBC-Parameters ::= SEQUENCE { + version INTEGER {v1-0(16)} (v1-0), + rounds INTEGER (8..127), + blockSizeInBits INTEGER (64 | 128), + iv OCTET STRING OPTIONAL } + + The fields of type RC5-CBC-Parameters have the following meanings: + + - version is the version of the algorithm, which shall be v1-0. + + - rounds is the number of rounds in the encryption operation, + which shall be between 8 and 127. + + - blockSizeInBits is the block size in bits, which shall be 64 or + 128. + + - iv is the initialization vector, an eight-octet string for + 64-bit RC5 and a 16-octet string for 128-bit RC5. The default + is a string of the appropriate length consisting of zero + octets. + +B.2.5. AES-CBC-Pad + + AES-CBC-Pad is the AES encryption algorithm [NIST197] in CBC mode + with the padding operation specified in RFC 5652 [RFC5652]. + AES-CBC-Pad has a variable key length of 16, 24, or 32 octets and has + a 16-octet block size. It has a 16-octet initialization vector. + + Note: For AES, the padding string consists of 16-(||M|| mod 16) + octets each with value 16-(||M|| mod 16). + + For AES, object identifiers are defined depending on key size and + operation mode. For example, the 16-octet (128-bit) key AES + encryption scheme in CBC mode would be aes128-CBC-Pad identifying the + AES-CBC-PAD encryption scheme using a 16-octet key: + + + +Moriarty, et al. Informational [Page 32] + +RFC 8018 PKCS #5 v2.1 January 2017 + + + aes128-CBC-PAD OBJECT IDENTIFIER ::= {aes 2} + + The AES object identifier is defined in Appendix C. + + The parameters field associated with this OID in an + AlgorithmIdentifier shall have type OCTET STRING (SIZE(16)), + specifying the initialization vector for CBC mode. + +B.3. Message Authentication Schemes + + An example message authentication scheme for PBMAC1 (Section 7.1) is + HMAC-SHA-1. + +B.3.1. HMAC-SHA-1 + + HMAC-SHA-1 is the HMAC message authentication scheme [RFC2104] based + on the SHA-1 hash function [NIST180]. HMAC-SHA-1 has a variable key + length and a 20-octet (160-bit) message authentication code. + + The object identifier id-hmacWithSHA1 (see Appendix B.1.1) identifies + the HMAC-SHA-1 message authentication scheme. (The object identifier + is the same for both the pseudorandom function and the message + authentication scheme; the distinction is to be understood by + context.) This object identifier is intended to be employed in the + object set PBMAC1-Macs (Appendix A.5). + +B.3.2. HMAC-SHA-2 + + HMAC-SHA-2 refers to the set of HMAC message authentication schemes + [NIST198] based on the SHA-2 functions [NIST180]. HMAC-SHA-2 has a + variable key length and a message authentication code whose length is + based on the hash function chosen (SHA-224, SHA-256, SHA-384, + SHA-512, SHA-512/224, or SHA-512/256) -- that is, 28, 32, 48, or 64 + octets. + + The object identifiers id-hmacWithSHA224, id-hmacWithSHA256, + id-hmacWithSHA384, id-hmacWithSHA512, id-hmacWithSHA512-224, and + id-hmacWithSHA512-256 (see Appendix B.1.2) identify the HMAC-SHA-2 + schemes. The object identifiers are the same for both the + pseudorandom functions and the message authentication schemes; the + distinction is to be understood by context. These object identifiers + are intended to be employed in the object set PBMAC1-Macs (Appendix + A.5). + + + + + + + + +Moriarty, et al. Informational [Page 33] + +RFC 8018 PKCS #5 v2.1 January 2017 + + +Appendix C. ASN.1 Module + + For reference purposes, the ASN.1 syntax in the preceding sections is + presented as an ASN.1 module here. + + -- PKCS #5 v2.1 ASN.1 Module + -- Revised October 27, 2012 + + -- This module has been checked for conformance with the + -- ASN.1 standard by the OSS ASN.1 Tools + + PKCS5v2-1 { + iso(1) member-body(2) us(840) rsadsi(113549) pkcs(1) pkcs-5(5) + modules(16) pkcs5v2-1(2) + } + + DEFINITIONS EXPLICIT TAGS ::= + + BEGIN + + -- ======================== + -- Basic object identifiers + -- ======================== + + nistAlgorithms OBJECT IDENTIFIER ::= {joint-iso-itu-t(2) country(16) + us(840) organization(1) + gov(101) csor(3) 4} + oiw OBJECT IDENTIFIER ::= {iso(1) identified-organization(3) 14} + rsadsi OBJECT IDENTIFIER ::= {iso(1) member-body(2) us(840) 113549} + pkcs OBJECT IDENTIFIER ::= {rsadsi 1} + pkcs-5 OBJECT IDENTIFIER ::= {pkcs 5} + + -- ======================= + -- Basic types and classes + -- ======================= + + AlgorithmIdentifier { ALGORITHM-IDENTIFIER:InfoObjectSet } ::= + SEQUENCE { + algorithm ALGORITHM-IDENTIFIER.&id({InfoObjectSet}), + parameters ALGORITHM-IDENTIFIER.&Type({InfoObjectSet} + {@algorithm}) OPTIONAL + } + + ALGORITHM-IDENTIFIER ::= TYPE-IDENTIFIER + + -- ====== + -- PBKDF2 + -- ====== + + + +Moriarty, et al. Informational [Page 34] + +RFC 8018 PKCS #5 v2.1 January 2017 + + + PBKDF2Algorithms ALGORITHM-IDENTIFIER ::= { + {PBKDF2-params IDENTIFIED BY id-PBKDF2}, + ... + } + + id-PBKDF2 OBJECT IDENTIFIER ::= {pkcs-5 12} + + algid-hmacWithSHA1 AlgorithmIdentifier {{PBKDF2-PRFs}} ::= + {algorithm id-hmacWithSHA1, parameters NULL : NULL} + + PBKDF2-params ::= SEQUENCE { + salt CHOICE { + specified OCTET STRING, + otherSource AlgorithmIdentifier {{PBKDF2-SaltSources}} + }, + iterationCount INTEGER (1..MAX), + keyLength INTEGER (1..MAX) OPTIONAL, + prf AlgorithmIdentifier {{PBKDF2-PRFs}} DEFAULT + algid-hmacWithSHA1 + } + + PBKDF2-SaltSources ALGORITHM-IDENTIFIER ::= { ... } + + PBKDF2-PRFs ALGORITHM-IDENTIFIER ::= { + {NULL IDENTIFIED BY id-hmacWithSHA1}, + {NULL IDENTIFIED BY id-hmacWithSHA224}, + {NULL IDENTIFIED BY id-hmacWithSHA256}, + {NULL IDENTIFIED BY id-hmacWithSHA384}, + {NULL IDENTIFIED BY id-hmacWithSHA512}, + {NULL IDENTIFIED BY id-hmacWithSHA512-224}, + {NULL IDENTIFIED BY id-hmacWithSHA512-256}, + ... + } + + -- ===== + -- PBES1 + -- ===== + + PBES1Algorithms ALGORITHM-IDENTIFIER ::= { + {PBEParameter IDENTIFIED BY pbeWithMD2AndDES-CBC} | + {PBEParameter IDENTIFIED BY pbeWithMD2AndRC2-CBC} | + {PBEParameter IDENTIFIED BY pbeWithMD5AndDES-CBC} | + {PBEParameter IDENTIFIED BY pbeWithMD5AndRC2-CBC} | + {PBEParameter IDENTIFIED BY pbeWithSHA1AndDES-CBC} | + {PBEParameter IDENTIFIED BY pbeWithSHA1AndRC2-CBC}, + ... + } + + + + +Moriarty, et al. Informational [Page 35] + +RFC 8018 PKCS #5 v2.1 January 2017 + + + pbeWithMD2AndDES-CBC OBJECT IDENTIFIER ::= {pkcs-5 1} + pbeWithMD2AndRC2-CBC OBJECT IDENTIFIER ::= {pkcs-5 4} + pbeWithMD5AndDES-CBC OBJECT IDENTIFIER ::= {pkcs-5 3} + pbeWithMD5AndRC2-CBC OBJECT IDENTIFIER ::= {pkcs-5 6} + pbeWithSHA1AndDES-CBC OBJECT IDENTIFIER ::= {pkcs-5 10} + pbeWithSHA1AndRC2-CBC OBJECT IDENTIFIER ::= {pkcs-5 11} + + PBEParameter ::= SEQUENCE { + salt OCTET STRING (SIZE(8)), + iterationCount INTEGER + } + + -- ===== + -- PBES2 + -- ===== + + PBES2Algorithms ALGORITHM-IDENTIFIER ::= { + {PBES2-params IDENTIFIED BY id-PBES2}, + ... + } + + id-PBES2 OBJECT IDENTIFIER ::= {pkcs-5 13} + + PBES2-params ::= SEQUENCE { + keyDerivationFunc AlgorithmIdentifier {{PBES2-KDFs}}, + encryptionScheme AlgorithmIdentifier {{PBES2-Encs}} + } + + PBES2-KDFs ALGORITHM-IDENTIFIER ::= { + {PBKDF2-params IDENTIFIED BY id-PBKDF2}, + ... + } + + PBES2-Encs ALGORITHM-IDENTIFIER ::= { ... } + + -- ====== + -- PBMAC1 + -- ====== + + PBMAC1Algorithms ALGORITHM-IDENTIFIER ::= { + {PBMAC1-params IDENTIFIED BY id-PBMAC1}, + ... + } + + id-PBMAC1 OBJECT IDENTIFIER ::= {pkcs-5 14} + + PBMAC1-params ::= SEQUENCE { + keyDerivationFunc AlgorithmIdentifier {{PBMAC1-KDFs}}, + + + +Moriarty, et al. Informational [Page 36] + +RFC 8018 PKCS #5 v2.1 January 2017 + + + messageAuthScheme AlgorithmIdentifier {{PBMAC1-MACs}} + } + + PBMAC1-KDFs ALGORITHM-IDENTIFIER ::= { + {PBKDF2-params IDENTIFIED BY id-PBKDF2}, + ... + } + + PBMAC1-MACs ALGORITHM-IDENTIFIER ::= { ... } + + -- ===================== + -- Supporting techniques + -- ===================== + + digestAlgorithm OBJECT IDENTIFIER ::= {rsadsi 2} + encryptionAlgorithm OBJECT IDENTIFIER ::= {rsadsi 3} + + SupportingAlgorithms ALGORITHM-IDENTIFIER ::= { + {NULL IDENTIFIED BY id-hmacWithSHA1} | + {OCTET STRING (SIZE(8)) IDENTIFIED BY desCBC} | + {OCTET STRING (SIZE(8)) IDENTIFIED BY des-EDE3-CBC} | + {RC2-CBC-Parameter IDENTIFIED BY rc2CBC} | + {RC5-CBC-Parameters IDENTIFIED BY rc5-CBC-PAD}, | + {OCTET STRING (SIZE(16)) IDENTIFIED BY aes128-CBC-PAD} | + {OCTET STRING (SIZE(16)) IDENTIFIED BY aes192-CBC-PAD} | + {OCTET STRING (SIZE(16)) IDENTIFIED BY aes256-CBC-PAD}, + ... + } + + id-hmacWithSHA1 OBJECT IDENTIFIER ::= {digestAlgorithm 7} + id-hmacWithSHA224 OBJECT IDENTIFIER ::= {digestAlgorithm 8} + id-hmacWithSHA256 OBJECT IDENTIFIER ::= {digestAlgorithm 9} + id-hmacWithSHA384 OBJECT IDENTIFIER ::= {digestAlgorithm 10} + id-hmacWithSHA512 OBJECT IDENTIFIER ::= {digestAlgorithm 11} + id-hmacWithSHA512-224 OBJECT IDENTIFIER ::= {digestAlgorithm 12} + id-hmacWithSHA512-256 OBJECT IDENTIFIER ::= {digestAlgorithm 13} + + desCBC OBJECT IDENTIFIER ::= {oiw secsig(3) algorithms(2) 7} + + des-EDE3-CBC OBJECT IDENTIFIER ::= {encryptionAlgorithm 7} + + rc2CBC OBJECT IDENTIFIER ::= {encryptionAlgorithm 2} + + RC2-CBC-Parameter ::= SEQUENCE { + rc2ParameterVersion INTEGER OPTIONAL, + iv OCTET STRING (SIZE(8)) + } + + + + +Moriarty, et al. Informational [Page 37] + +RFC 8018 PKCS #5 v2.1 January 2017 + + + rc5-CBC-PAD OBJECT IDENTIFIER ::= {encryptionAlgorithm 9} + + RC5-CBC-Parameters ::= SEQUENCE { + version INTEGER {v1-0(16)} (v1-0), + rounds INTEGER (8..127), + blockSizeInBits INTEGER (64 | 128), + iv OCTET STRING OPTIONAL + } + + aes OBJECT IDENTIFIER ::= { nistAlgorithms 1 } + aes128-CBC-PAD OBJECT IDENTIFIER ::= { aes 2 } + aes192-CBC-PAD OBJECT IDENTIFIER ::= { aes 22 } + aes256-CBC-PAD OBJECT IDENTIFIER ::= { aes 42 } + + END + +Appendix D. Revision History of PKCS #5 + + Versions 1.0 - 1.3 + + Versions 1.0 - 1.3 were distributed to participants in RSA Data + Security Inc.'s Public-Key Cryptography Standards meetings in + February and March 1991. + + Version 1.4 + + Version 1.4 was part of the June 3, 1991 initial public release of + PKCS. Version 1.4 was published as NIST/OSI Implementors' + Workshop document SEC-SIG-91-20. + + Version 1.5 + + Version 1.5 incorporated several editorial changes, including + updates to the references and the addition of a revision history. + + Version 2.0 + + Version 2.0 incorporates major editorial changes in terms of the + document structure, and introduces the PBES2 encryption scheme, + the PBMAC1 message authentication scheme, and independent + password-based key derivation functions. This version continues + to support the encryption process in version 1.5. + + + + + + + + + +Moriarty, et al. Informational [Page 38] + +RFC 8018 PKCS #5 v2.1 January 2017 + + + Version 2.1 + + This document transfers PKCS #5 into the IETF and includes some + minor changes from the authors for this submission. + + o Introduces AES/CBC as an encryption scheme for PBES2 and HMAC + with the hash functions SHA-224, SHA-256, SHA-384, SHA-512, + SHA-512/224, and SHA-512/256 as pseudorandom functions for + PBKDF2 and message authentication schemes for PBMAC1. + + o Changes references for PKCS #5 to RFC 2898 and for PKCS #8 to + RFCs 5208 and 5898. + + o Incorporates corrections of two editorial errata reported on + PKCS #5 [RFC2898]. + + o Added security considerations for MD2, MD5, and SHA-1. + +Appendix E. About PKCS + + The Public-Key Cryptography Standards are specifications produced by + RSA Laboratories in cooperation with secure systems developers + worldwide for the purpose of accelerating the deployment of public- + key cryptography. First published in 1991 as a result of meetings + with a small group of early adopters of public-key technology, the + PKCS documents have become widely referenced and implemented. + Contributions from the PKCS series have become part of many formal + and de facto standards, including ANSI X9 documents, PKIX, Secure + Electronic Transaction (SET), S/MIME, and SSL. + + Further development of most PKCS documents occurs through the IETF. + Suggestions for improvement are welcome. + + + + + + + + + + + + + + + + + + + +Moriarty, et al. Informational [Page 39] + +RFC 8018 PKCS #5 v2.1 January 2017 + + +Acknowledgements + + This document is based on a contribution of RSA Laboratories, the + research center of RSA Security Inc. + + RC2 and RC5 are trademarks of EMC Corporation. + +Authors' Addresses + + Kathleen M. Moriarty (editor) + Dell EMC + 176 South Street + Hopkinton, MA 01748 + United States of America + + Email: Kathleen.Moriarty@Dell.com + + + Burt Kaliski + Verisign + 12061 Bluemont Way + Reston, VA 20190 + United States of America + + Email: bkaliski@verisign.com + URI: http://verisignlabs.com + + + Andreas Rusch + RSA + 345 Queen Street + Brisbane, QLD 4000 + Australia + + Email: andreas.rusch@rsa.com + + + + + + + + + + + + + + + + +Moriarty, et al. Informational [Page 40] + diff --git a/docs/rfc/rfc8410.txt b/docs/rfc/rfc8410.txt new file mode 100644 index 0000000..2c4b963 --- /dev/null +++ b/docs/rfc/rfc8410.txt @@ -0,0 +1,1123 @@ + + + + + + +Internet Engineering Task Force (IETF) S. Josefsson +Request for Comments: 8410 SJD AB +Category: Standards Track J. Schaad +ISSN: 2070-1721 August Cellars + August 2018 + + + Algorithm Identifiers for Ed25519, Ed448, X25519, and X448 + for Use in the Internet X.509 Public Key Infrastructure + +Abstract + + This document specifies algorithm identifiers and ASN.1 encoding + formats for elliptic curve constructs using the curve25519 and + curve448 curves. The signature algorithms covered are Ed25519 and + Ed448. The key agreement algorithms covered are X25519 and X448. + The encoding for public key, private key, and Edwards-curve Digital + Signature Algorithm (EdDSA) structures is provided. + +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 7841. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + https://www.rfc-editor.org/info/rfc8410. + +Copyright Notice + + Copyright (c) 2018 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 + (https://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. + + + + +Josefsson & Schaad Standards Track [Page 1] + +RFC 8410 Safe Curves for X.509 August 2018 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 + 2. Requirements Terminology . . . . . . . . . . . . . . . . . . 3 + 3. Curve25519 and Curve448 Algorithm Identifiers . . . . . . . . 3 + 4. Subject Public Key Fields . . . . . . . . . . . . . . . . . . 4 + 5. Key Usage Bits . . . . . . . . . . . . . . . . . . . . . . . 5 + 6. EdDSA Signatures . . . . . . . . . . . . . . . . . . . . . . 6 + 7. Private Key Format . . . . . . . . . . . . . . . . . . . . . 7 + 8. Human-Readable Algorithm Names . . . . . . . . . . . . . . . 8 + 9. ASN.1 Module . . . . . . . . . . . . . . . . . . . . . . . . 9 + 10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 10.1. Example Ed25519 Public Key . . . . . . . . . . . . . . . 11 + 10.2. Example X25519 Certificate . . . . . . . . . . . . . . . 12 + 10.3. Examples of Ed25519 Private Key . . . . . . . . . . . . 14 + 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 + 12. Security Considerations . . . . . . . . . . . . . . . . . . . 15 + 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 + 13.1. Normative References . . . . . . . . . . . . . . . . . . 16 + 13.2. Informative References . . . . . . . . . . . . . . . . . 16 + Appendix A. Invalid Encodings . . . . . . . . . . . . . . . . . 18 + Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 19 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20 + +1. Introduction + + In [RFC7748], the elliptic curves curve25519 and curve448 are + described. They are designed with performance and security in mind. + The curves may be used for Diffie-Hellman and digital signature + operations. + + [RFC7748] describes the operations on these curves for the Diffie- + Hellman operation. A convention has developed that when these two + curves are used with the Diffie-Hellman operation, they are referred + to as X25519 and X448. This RFC defines the ASN.1 Object Identifiers + (OIDs) for the operations X25519 and X448 along with the associated + parameters. The use of these OIDs is described for public and + private keys. + + In [RFC8032] the elliptic curve signature system Edwards-curve + Digital Signature Algorithm (EdDSA) is described along with a + recommendation for the use of the curve25519 and curve448. EdDSA has + defined two modes: the PureEdDSA mode without prehashing and the + HashEdDSA mode with prehashing. The convention used for identifying + the algorithm/curve combinations is to use "Ed25519" and "Ed448" for + the PureEdDSA mode. This document does not provide the conventions + + + + + +Josefsson & Schaad Standards Track [Page 2] + +RFC 8410 Safe Curves for X.509 August 2018 + + + needed for the prehash versions of the signature algorithm. The use + of the OIDs is described for public keys, private keys and + signatures. + + [RFC8032] additionally defines the concept of a context. Contexts + can be used to differentiate signatures generated for different + purposes with the same key. The use of contexts is not defined in + this document for the following reasons: + + o The current implementations of Ed25519 do not support the use of + contexts; thus, if specified, it will potentially delay the use of + these algorithms further. + + o EdDSA is the only IETF algorithm that currently supports the use + of contexts; however, there is a possibility that there will be + confusion between which algorithms need to have separate keys and + which do not. This may result in a decrease of security for those + other algorithms. + + o There are still ongoing discussions among the cryptographic + community about how effective the use of contexts is for + preventing attacks. + + o There needs to be discussions about the correct way to identify + when context strings are to be used. It is not clear if different + OIDs should be used for different contexts or the OID should + merely note that a context string needs to be provided. + +2. Requirements Terminology + + 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 [RFC2119] [RFC8174] when, and only when, they appear in all + capitals, as shown here. + +3. Curve25519 and Curve448 Algorithm Identifiers + + Certificates conforming to [RFC5280] can convey a public key for any + public key algorithm. The certificate indicates the algorithm + through an algorithm identifier. An algorithm identifier consists of + an OID and optional parameters. + + + + + + + + + +Josefsson & Schaad Standards Track [Page 3] + +RFC 8410 Safe Curves for X.509 August 2018 + + + The AlgorithmIdentifier type, which is included for convenience, is + defined as follows: + + AlgorithmIdentifier ::= SEQUENCE { + algorithm OBJECT IDENTIFIER, + parameters ANY DEFINED BY algorithm OPTIONAL + } + + The fields in AlgorithmIdentifier have the following meanings: + + o algorithm identifies the cryptographic algorithm with an object + identifier. Four such OIDs are defined below. + + o parameters, which are optional, are the associated parameters for + the algorithm identifier in the algorithm field. + + In this document, we define four new OIDs for identifying the + different curve/algorithm pairs: the curves being curve25519 and + curve448 and the algorithms being ECDH and EdDSA in pure mode. For + all of the OIDs, the parameters MUST be absent. + + It is possible to find systems that require the parameters to be + present. This can be due to either a defect in the original 1997 + syntax or a programming error where developers never got input where + this was not true. The optimal solution is to fix these systems; + where this is not possible, the problem needs to be restricted to + that subsystem and not propagated to the Internet. + + The same algorithm identifiers are used for identifying a public key, + a private key, and a signature (for the two EdDSA related OIDs). + Additional encoding information is provided below for each of these + locations. + + id-X25519 OBJECT IDENTIFIER ::= { 1 3 101 110 } + id-X448 OBJECT IDENTIFIER ::= { 1 3 101 111 } + id-Ed25519 OBJECT IDENTIFIER ::= { 1 3 101 112 } + id-Ed448 OBJECT IDENTIFIER ::= { 1 3 101 113 } + +4. Subject Public Key Fields + + In the X.509 certificate, the subjectPublicKeyInfo field has the + SubjectPublicKeyInfo type, which has the following ASN.1 syntax: + + SubjectPublicKeyInfo ::= SEQUENCE { + algorithm AlgorithmIdentifier, + subjectPublicKey BIT STRING + } + + + + +Josefsson & Schaad Standards Track [Page 4] + +RFC 8410 Safe Curves for X.509 August 2018 + + + The fields in SubjectPublicKeyInfo have the following meanings: + + o algorithm is the algorithm identifier and parameters for the + public key (see above). + + o subjectPublicKey contains the byte stream of the public key. The + algorithms defined in this document always encode the public key + as an exact multiple of 8 bits. + + Both [RFC7748] and [RFC8032] define the public key value as being a + byte string. It should be noted that the public key is computed + differently for each of these documents; thus, the same private key + will not produce the same public key. + + The following is an example of a public key encoded using the textual + encoding defined in [RFC7468]. + + -----BEGIN PUBLIC KEY----- + MCowBQYDK2VwAyEAGb9ECWmEzf6FQbrBZ9w7lshQhqowtrbLDFw4rXAxZuE= + -----END PUBLIC KEY----- + +5. Key Usage Bits + + The intended application for the key is indicated in the keyUsage + certificate extension. + + If the keyUsage extension is present in a certificate that indicates + id-X25519 or id-X448 in SubjectPublicKeyInfo, then the following MUST + be present: + + keyAgreement; + + one of the following MAY also be present: + + encipherOnly; or + decipherOnly. + + If the keyUsage extension is present in an end-entity certificate + that indicates id-Ed25519 or id-Ed448, then the keyUsage extension + MUST contain one or both of the following values: + + nonRepudiation; and + digitalSignature. + + + + + + + + +Josefsson & Schaad Standards Track [Page 5] + +RFC 8410 Safe Curves for X.509 August 2018 + + + If the keyUsage extension is present in a certification authority + certificate that indicates id-Ed25519 or id-Ed448, then the keyUsage + extension MUST contain one or more of the following values: + + nonRepudiation; + digitalSignature; + keyCertSign; and + cRLSign. + +6. EdDSA Signatures + + Signatures can be placed in a number of different ASN.1 structures. + The top level structure for a certificate is given below as being + illustrative of how signatures are frequently encoded with an + algorithm identifier and a location for the signature. + + Certificate ::= SEQUENCE { + tbsCertificate TBSCertificate, + signatureAlgorithm AlgorithmIdentifier, + signatureValue BIT STRING } + + The same algorithm identifiers are used for signatures as are used + for public keys. When used to identify signature algorithms, the + parameters MUST be absent. + + The data to be signed is prepared for EdDSA. Then, a private key + operation is performed to generate the signature value. This value + is the opaque value ENC(R) || ENC(S) described in Section 3.3 of + [RFC8032]. The octet string representing the signature is encoded + directly in the BIT STRING without adding any additional ASN.1 + wrapping. For the Certificate structure, the signature value is + wrapped in the "signatureValue" BIT STRING field. + + + + + + + + + + + + + + + + + + + +Josefsson & Schaad Standards Track [Page 6] + +RFC 8410 Safe Curves for X.509 August 2018 + + +7. Private Key Format + + "Asymmetric Key Packages" [RFC5958] describes how to encode a private + key in a structure that both identifies what algorithm the private + key is for and allows for the public key and additional attributes + about the key to be included as well. For illustration, the ASN.1 + structure OneAsymmetricKey is replicated below. The algorithm- + specific details of how a private key is encoded are left for the + document describing the algorithm itself. + + OneAsymmetricKey ::= SEQUENCE { + version Version, + privateKeyAlgorithm PrivateKeyAlgorithmIdentifier, + privateKey PrivateKey, + attributes [0] IMPLICIT Attributes OPTIONAL, + ..., + [[2: publicKey [1] IMPLICIT PublicKey OPTIONAL ]], + ... + } + + PrivateKey ::= OCTET STRING + + PublicKey ::= BIT STRING + + For the keys defined in this document, the private key is always an + opaque byte sequence. The ASN.1 type CurvePrivateKey is defined in + this document to hold the byte sequence. Thus, when encoding a + OneAsymmetricKey object, the private key is wrapped in a + CurvePrivateKey object and wrapped by the OCTET STRING of the + "privateKey" field. + + CurvePrivateKey ::= OCTET STRING + + To encode an EdDSA, X25519, or X448 private key, the "privateKey" + field will hold the encoded private key. The "privateKeyAlgorithm" + field uses the AlgorithmIdentifier structure. The structure is + encoded as defined above. If present, the "publicKey" field will + hold the encoded key as defined in [RFC7748] and [RFC8032]. + + + + + + + + + + + + + +Josefsson & Schaad Standards Track [Page 7] + +RFC 8410 Safe Curves for X.509 August 2018 + + + The following is an example of a private key encoded using the + textual encoding defined in [RFC7468]. + + -----BEGIN PRIVATE KEY----- + MC4CAQAwBQYDK2VwBCIEINTuctv5E1hK1bbY8fdp+K06/nwoy/HU++CXqI9EdVhC + -----END PRIVATE KEY----- + + The following example, in addition to encoding the private key, has + an attribute included as well as the public key. As with the prior + example, the textual encoding defined in [RFC7468] is used. + + -----BEGIN PRIVATE KEY----- + MHICAQEwBQYDK2VwBCIEINTuctv5E1hK1bbY8fdp+K06/nwoy/HU++CXqI9EdVhC + oB8wHQYKKoZIhvcNAQkJFDEPDA1DdXJkbGUgQ2hhaXJzgSEAGb9ECWmEzf6FQbrB + Z9w7lshQhqowtrbLDFw4rXAxZuE= + -----END PRIVATE KEY------ + + NOTE: There exist some private key import functions that have not + picked up the new ASN.1 structure OneAsymmetricKey that is defined in + [RFC7748]. This means that they will not accept a private key + structure that contains the public key field. This means a balancing + act needs to be done between being able to do a consistency check on + the key pair and widest ability to import the key. + +8. Human-Readable Algorithm Names + + For the purpose of consistent cross-implementation naming, this + section establishes human-readable names for the algorithms specified + in this document. Implementations SHOULD use these names when + referring to the algorithms. If there is a strong reason to deviate + from these names -- for example, if the implementation has a + different naming convention and wants to maintain internal + consistency -- it is encouraged to deviate as little as possible from + the names given here. + + Use the string "ECDH" when referring to a public key of type "X25519" + or "X448" when the curve is not known or relevant. + + When the curve is known, use the more specific string of "X25519" or + "X448". + + Use the string "EdDSA" when referring to a signing public key or + signature when the curve is not known or relevant. + + When the curve is known, use a more specific string. For the id- + Ed25519 value use the string "Ed25519". For id-Ed448, use "Ed448". + + + + + +Josefsson & Schaad Standards Track [Page 8] + +RFC 8410 Safe Curves for X.509 August 2018 + + +9. ASN.1 Module + + For reference purposes, the ASN.1 syntax is presented as an ASN.1 + module here. + + -- ASN.1 Module + + Safecurves-pkix-18 + { iso(1) identified-organization(3) dod(6) internet(1) + security(5) mechanisms(5) pkix(7) id-mod(0) + id-mod-safecurves-pkix(93) } + + DEFINITIONS EXPLICIT TAGS ::= + BEGIN + + IMPORTS + SIGNATURE-ALGORITHM, KEY-AGREE, PUBLIC-KEY, KEY-WRAP, + KeyUsage, AlgorithmIdentifier + FROM AlgorithmInformation-2009 + {iso(1) identified-organization(3) dod(6) internet(1) security(5) + mechanisms(5) pkix(7) id-mod(0) + id-mod-algorithmInformation-02(58)} + + mda-sha512 + FROM PKIX1-PSS-OAEP-Algorithms-2009 + { iso(1) identified-organization(3) dod(6) internet(1) + security(5) mechanisms(5) pkix(7) id-mod(0) + id-mod-pkix1-rsa-pkalgs-02(54) } + + kwa-aes128-wrap, kwa-aes256-wrap + FROM CMSAesRsaesOaep-2009 + { iso(1) member-body(2) us(840) rsadsi(113549) pkcs(1) pkcs-9(9) + smime(16) modules(0) id-mod-cms-aes-02(38) } + ; + + + id-edwards-curve-algs OBJECT IDENTIFIER ::= { 1 3 101 } + + id-X25519 OBJECT IDENTIFIER ::= { id-edwards-curve-algs 110 } + id-X448 OBJECT IDENTIFIER ::= { id-edwards-curve-algs 111 } + id-Ed25519 OBJECT IDENTIFIER ::= { id-edwards-curve-algs 112 } + id-Ed448 OBJECT IDENTIFIER ::= { id-edwards-curve-algs 113 } + + + + + + + + + +Josefsson & Schaad Standards Track [Page 9] + +RFC 8410 Safe Curves for X.509 August 2018 + + + sa-Ed25519 SIGNATURE-ALGORITHM ::= { + IDENTIFIER id-Ed25519 + PARAMS ARE absent + PUBLIC-KEYS {pk-Ed25519} + SMIME-CAPS { IDENTIFIED BY id-Ed25519 } + } + + pk-Ed25519 PUBLIC-KEY ::= { + IDENTIFIER id-Ed25519 + -- KEY no ASN.1 wrapping -- + PARAMS ARE absent + CERT-KEY-USAGE {digitalSignature, nonRepudiation, + keyCertSign, cRLSign} + PRIVATE-KEY CurvePrivateKey + } + + kaa-X25519 KEY-AGREE ::= { + IDENTIFIER id-X25519 + PARAMS ARE absent + PUBLIC-KEYS {pk-X25519} + UKM -- TYPE no ASN.1 wrapping -- ARE preferredPresent + SMIME-CAPS { + TYPE AlgorithmIdentifier{KEY-WRAP, {KeyWrapAlgorithms}} + IDENTIFIED BY id-X25519 } + } + + pk-X25519 PUBLIC-KEY ::= { + IDENTIFIER id-X25519 + -- KEY no ASN.1 wrapping -- + PARAMS ARE absent + CERT-KEY-USAGE { keyAgreement } + PRIVATE-KEY CurvePrivateKey + } + + KeyWrapAlgorithms KEY-WRAP ::= { + kwa-aes128-wrap | kwa-aes256-wrap, + ... + } + + kaa-X448 KEY-AGREE ::= { + IDENTIFIER id-X448 + PARAMS ARE absent + PUBLIC-KEYS {pk-X448} + UKM -- TYPE no ASN.1 wrapping -- ARE preferredPresent + SMIME-CAPS { + TYPE AlgorithmIdentifier{KEY-WRAP, {KeyWrapAlgorithms}} + IDENTIFIED BY id-X448 } + } + + + +Josefsson & Schaad Standards Track [Page 10] + +RFC 8410 Safe Curves for X.509 August 2018 + + + pk-X448 PUBLIC-KEY ::= { + IDENTIFIER id-X448 + -- KEY no ASN.1 wrapping -- + PARAMS ARE absent + CERT-KEY-USAGE { keyAgreement } + PRIVATE-KEY CurvePrivateKey + } + + CurvePrivateKey ::= OCTET STRING + + + END + +10. Examples + + This section contains illustrations of EdDSA public keys and + certificates, illustrating parameter choices. + +10.1. Example Ed25519 Public Key + + An example of an Ed25519 public key: + + Public Key Information: + Public Key Algorithm: Ed25519 + Algorithm Security Level: High + + Public Key Usage: + + Public Key ID: 9b1f5eeded043385e4f7bc623c5975b90bc8bb3b + + -----BEGIN PUBLIC KEY----- + MCowBQYDK2VwAyEAGb9ECWmEzf6FQbrBZ9w7lshQhqowtrbLDFw4rXAxZuE= + -----END PUBLIC KEY----- + + + + + + + + + + + + + + + + + + +Josefsson & Schaad Standards Track [Page 11] + +RFC 8410 Safe Curves for X.509 August 2018 + + +10.2. Example X25519 Certificate + + An example of a self-issued PKIX certificate using Ed25519 to sign an + X25519 public key would be: + + 0 300: SEQUENCE { + 4 223: SEQUENCE { + 7 3: [0] { + 9 1: INTEGER 2 + : } + 12 8: INTEGER 56 01 47 4A 2A 8D C3 30 + 22 5: SEQUENCE { + 24 3: OBJECT IDENTIFIER + : Ed 25519 signature algorithm { 1 3 101 112 } + : } + 29 25: SEQUENCE { + 31 23: SET { + 33 21: SEQUENCE { + 35 3: OBJECT IDENTIFIER commonName (2 5 4 3) + 40 14: UTF8String 'IETF Test Demo' + : } + : } + : } + 56 30: SEQUENCE { + 58 13: UTCTime 01/08/2016 12:19:24 GMT + 73 13: UTCTime 31/12/2040 23:59:59 GMT + : } + 88 25: SEQUENCE { + 90 23: SET { + 92 21: SEQUENCE { + 94 3: OBJECT IDENTIFIER commonName (2 5 4 3) + 99 14: UTF8String 'IETF Test Demo' + : } + : } + : } + 115 42: SEQUENCE { + 117 5: SEQUENCE { + 119 3: OBJECT IDENTIFIER + : ECDH 25519 key agreement { 1 3 101 110 } + : } + 124 33: BIT STRING + : 85 20 F0 09 89 30 A7 54 74 8B 7D DC B4 3E F7 5A + : 0D BF 3A 0D 26 38 1A F4 EB A4 A9 8E AA 9B 4E 6A + : } + 159 69: [3] { + 161 67: SEQUENCE { + 163 15: SEQUENCE { + 165 3: OBJECT IDENTIFIER basicConstraints (2 5 29 19) + + + +Josefsson & Schaad Standards Track [Page 12] + +RFC 8410 Safe Curves for X.509 August 2018 + + + 170 1: BOOLEAN TRUE + 173 5: OCTET STRING, encapsulates { + 175 3: SEQUENCE { + 177 1: BOOLEAN FALSE + : } + : } + : } + 180 14: SEQUENCE { + 182 3: OBJECT IDENTIFIER keyUsage (2 5 29 15) + 187 1: BOOLEAN FALSE + 190 4: OCTET STRING, encapsulates { + 192 2: BIT STRING 3 unused bits + : '10000'B (bit 4) + : } + : } + 196 32: SEQUENCE { + 198 3: OBJECT IDENTIFIER subjectKeyIdentifier (2 5 29 14) + 203 1: BOOLEAN FALSE + 206 22: OCTET STRING, encapsulates { + 208 20: OCTET STRING + : 9B 1F 5E ED ED 04 33 85 E4 F7 BC 62 3C 59 75 + : B9 0B C8 BB 3B + : } + : } + : } + : } + : } + 230 5: SEQUENCE { + 232 3: OBJECT IDENTIFIER + : Ed 25519 signature algorithm { 1 3 101 112 } + : } + 237 65: BIT STRING + : AF 23 01 FE DD C9 E6 FF C1 CC A7 3D 74 D6 48 A4 + : 39 80 82 CD DB 69 B1 4E 4D 06 EC F8 1A 25 CE 50 + : D4 C2 C3 EB 74 6C 4E DD 83 46 85 6E C8 6F 3D CE + : 1A 18 65 C5 7A C2 7B 50 A0 C3 50 07 F5 E7 D9 07 + : } + + -----BEGIN CERTIFICATE----- + MIIBLDCB36ADAgECAghWAUdKKo3DMDAFBgMrZXAwGTEXMBUGA1UEAwwOSUVURiBUZX + N0IERlbW8wHhcNMTYwODAxMTIxOTI0WhcNNDAxMjMxMjM1OTU5WjAZMRcwFQYDVQQD + DA5JRVRGIFRlc3QgRGVtbzAqMAUGAytlbgMhAIUg8AmJMKdUdIt93LQ+91oNvzoNJj + ga9OukqY6qm05qo0UwQzAPBgNVHRMBAf8EBTADAQEAMA4GA1UdDwEBAAQEAwIDCDAg + BgNVHQ4BAQAEFgQUmx9e7e0EM4Xk97xiPFl1uQvIuzswBQYDK2VwA0EAryMB/t3J5v + /BzKc9dNZIpDmAgs3babFOTQbs+BolzlDUwsPrdGxO3YNGhW7Ibz3OGhhlxXrCe1Cg + w1AH9efZBw== + -----END CERTIFICATE----- + + + + +Josefsson & Schaad Standards Track [Page 13] + +RFC 8410 Safe Curves for X.509 August 2018 + + +10.3. Examples of Ed25519 Private Key + + An example of an Ed25519 private key without the public key: + + -----BEGIN PRIVATE KEY----- + MC4CAQAwBQYDK2VwBCIEINTuctv5E1hK1bbY8fdp+K06/nwoy/HU++CXqI9EdVhC + -----END PRIVATE KEY----- + + The same item dumped as ASN.1 yields: + + 0 30 46: SEQUENCE { + 2 02 1: INTEGER 0 + 5 30 5: SEQUENCE { + 7 06 3: OBJECT IDENTIFIER + : Ed 25519 signature algorithm { 1 3 101 112 } + : } + 12 04 34: OCTET STRING + : 04 20 D4 EE 72 DB F9 13 58 4A D5 B6 D8 F1 F7 69 + : F8 AD 3A FE 7C 28 CB F1 D4 FB E0 97 A8 8F 44 75 + : 58 42 + : } + + Note that the value of the private key is: + + D4 EE 72 DB F9 13 58 4A D5 B6 D8 F1 F7 69 F8 AD + 3A FE 7C 28 CB F1 D4 FB E0 97 A8 8F 44 75 58 42 + + An example of the same Ed25519 private key encoded with an attribute + and the public key: + + -----BEGIN PRIVATE KEY----- + MHICAQEwBQYDK2VwBCIEINTuctv5E1hK1bbY8fdp+K06/nwoy/HU++CXqI9EdVhC + oB8wHQYKKoZIhvcNAQkJFDEPDA1DdXJkbGUgQ2hhaXJzgSEAGb9ECWmEzf6FQbrB + Z9w7lshQhqowtrbLDFw4rXAxZuE= + -----END PRIVATE KEY----- + + + + + + + + + + + + + + + + +Josefsson & Schaad Standards Track [Page 14] + +RFC 8410 Safe Curves for X.509 August 2018 + + + The same item dumped as ASN.1 yields: + + 0 114: SEQUENCE { + 2 1: INTEGER 1 + 5 5: SEQUENCE { + 7 3: OBJECT IDENTIFIER '1 3 101 112' + : } + 12 34: OCTET STRING, encapsulates { + : 04 20 D4 EE 72 DB F9 13 58 4A D5 B6 D8 F1 F7 69 + : F8 AD 3A FE 7C 28 CB F1 D4 FB E0 97 A8 8F 44 75 + : 58 42 + : } + 48 31: [0] { + 50 29: SEQUENCE { + 52 10: OBJECT IDENTIFIER '1 2 840 113549 1 9 9 20' + 64 15: SET { + 66 13: UTF8String 'Curdle Chairs' + : } + : } + : } + 81 33: [1] 00 19 BF 44 09 69 84 CD FE 85 41 BA C1 67 DC 3B + 96 C8 50 86 AA 30 B6 B6 CB 0C 5C 38 AD 70 31 66 + E1 + : } + +11. IANA Considerations + + For the ASN.1 module in Section 9, IANA has registered value 93 for + "id-mod-safecurves-pkix" in the "SMI Security for PKIX Module + Identifier" (1.3.6.1.5.5.7.0) registry. + + The OIDs are being independently registered in the IANA registry "SMI + Security for Cryptographic Algorithms" in [RFC8411]. + +12. Security Considerations + + The security considerations of [RFC5280], [RFC7748], and [RFC8032] + apply accordingly. + + The procedures for going from a private key to a public key are + different when used with Diffie-Hellman versus when used with Edwards + Signatures. This means that the same public key cannot be used for + both ECDH and EdDSA. + + + + + + + + +Josefsson & Schaad Standards Track [Page 15] + +RFC 8410 Safe Curves for X.509 August 2018 + + +13. References + +13.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + . + + [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, DOI 10.17487/RFC5280, May 2008, + . + + [RFC5480] Turner, S., Brown, D., Yiu, K., Housley, R., and T. Polk, + "Elliptic Curve Cryptography Subject Public Key + Information", RFC 5480, DOI 10.17487/RFC5480, March 2009, + . + + [RFC5958] Turner, S., "Asymmetric Key Packages", RFC 5958, + DOI 10.17487/RFC5958, August 2010, + . + + [RFC7748] Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves + for Security", RFC 7748, DOI 10.17487/RFC7748, January + 2016, . + + [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital + Signature Algorithm (EdDSA)", RFC 8032, + DOI 10.17487/RFC8032, January 2017, + . + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, . + +13.2. Informative References + + [RFC3279] Bassham, L., Polk, W., and R. Housley, "Algorithms and + Identifiers for the Internet X.509 Public Key + Infrastructure Certificate and Certificate Revocation List + (CRL) Profile", RFC 3279, DOI 10.17487/RFC3279, April + 2002, . + + + + + + + +Josefsson & Schaad Standards Track [Page 16] + +RFC 8410 Safe Curves for X.509 August 2018 + + + [RFC4055] Schaad, J., Kaliski, B., and R. Housley, "Additional + Algorithms and Identifiers for RSA Cryptography for use in + the Internet X.509 Public Key Infrastructure Certificate + and Certificate Revocation List (CRL) Profile", RFC 4055, + DOI 10.17487/RFC4055, June 2005, + . + + [RFC5639] Lochter, M. and J. Merkle, "Elliptic Curve Cryptography + (ECC) Brainpool Standard Curves and Curve Generation", + RFC 5639, DOI 10.17487/RFC5639, March 2010, + . + + [RFC7468] Josefsson, S. and S. Leonard, "Textual Encodings of PKIX, + PKCS, and CMS Structures", RFC 7468, DOI 10.17487/RFC7468, + April 2015, . + + [RFC8411] Schaad, J. and R. Andrews, "IANA Registration for the + Cryptographic Algorithm Object Identifier Range", + RFC 8411, DOI 10.17487/RFC8411, August 2018, + . + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Josefsson & Schaad Standards Track [Page 17] + +RFC 8410 Safe Curves for X.509 August 2018 + + +Appendix A. Invalid Encodings + + There are a number of things that need to be dealt with when a new + key part is decoded and imported into the system. A partial list of + these includes: + + o ASN.1 encoding errors: Two items are highlighted here. First, the + use of an OCTET STRING rather than a BIT STRING for the public + key. The use of OCTET STRING was a copy error that existed in a + previous draft version of this document; the structure is correct + in [RFC5958]. However, any early implementation may have this + wrong. Second, the value of the version field is required to be 0 + if the publicKey is absent and 1 if present. This is called out + in [RFC5958], but was not duplicated above. + + o Key encoding errors: Both [RFC7748] and [RFC8032] have formatting + requirements for keys that need to be enforced. In some cases, + the enforcement is done at the time of importing, for example, + doing masking or a mod p operation. In other cases, the + enforcement is done by rejecting the keys and having an import + failure. + + o Key mismatch errors: If a public key is provided, it may not agree + with the private key because either it is wrong or the wrong + algorithm was used. + + Some systems are also going to be stricter on what they accept. As + stated in [RFC5958], BER decoding of OneAsymmetricKey objects is a + requirement for compliance. Despite this requirement, some acceptors + will only decode DER formats. The following is a BER encoding of a + private key; it is valid, but it may not be accepted by many systems. + + -----BEGIN PRIVATE KEY----- + MIACAQAwgAYDK2VwAAAEIgQg1O5y2/kTWErVttjx92n4rTr+fCjL8dT74Jeoj0R1W + EIAAA== + -----END PRIVATE KEY----- + + What follows here is a brief sampling of some incorrect keys. + + In the following example, the private key does not match the masking + requirements for X25519. For this example, the top bits are set to + zero and the bottom three bits are set to 001. + + -----BEGIN PRIVATE KEY----- + MFMCAQEwBQYDK2VuBCIEIPj///////////////////////////////////////8/oS + MDIQCEfA0sN1I082XmYJVRh6NzWg92E9FgnTpqTYxTrqpaIg== + -----END PRIVATE KEY----- + + + + +Josefsson & Schaad Standards Track [Page 18] + +RFC 8410 Safe Curves for X.509 August 2018 + + + In the following examples, the key is the wrong length because an + all-zero byte has been removed. In one case, the first byte has been + removed; in the other case, the last byte has been removed. + + -----BEGIN PRIVATE KEY----- + MFICAQEwBQYDK2VwBCIEIC3GfeUYbZGTAhwLEE2cbvJL7ivTlcy17VottfN6L8HwoS + IDIADBfk2Lv/J8H7YYwj/OmIcDx++jzVkKrKwS0/HjyQyM + -----END PRIVATE KEY----- + + -----BEGIN PRIVATE KEY----- + MFICAQEwBQYDK2VwBCIEILJXn1VaLqvausjUaZexwI/ozmOFjfEk78KcYN+7hsNJoS + IDIACdQhJwzi/MCGcsQeQnIUh2JFybDxSrZxuLudJmpJLk + -----END PRIVATE KEY----- + +Acknowledgments + + Text and/or inspiration were drawn from [RFC5280], [RFC3279], + [RFC4055], [RFC5480], and [RFC5639]. + + The following people discussed the document and provided feedback: + Klaus Hartke, Ilari Liusvaara, Erwann Abalea, Rick Andrews, Rob + Stradling, James Manger, Nikos Mavrogiannopoulos, Russ Housley, David + Benjamin, Brian Smith, and Alex Wilson. + + A big thank you to Symantec for kindly donating the OIDs used in this + document. + + + + + + + + + + + + + + + + + + + + + + + + + +Josefsson & Schaad Standards Track [Page 19] + +RFC 8410 Safe Curves for X.509 August 2018 + + +Authors' Addresses + + Simon Josefsson + SJD AB + + Email: simon@josefsson.org + + + Jim Schaad + August Cellars + + Email: ietf@augustcellars.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Josefsson & Schaad Standards Track [Page 20] + diff --git a/src/internal/crypto/pbes2.ts b/src/internal/crypto/pbes2.ts index 5f534a6..6627599 100644 --- a/src/internal/crypto/pbes2.ts +++ b/src/internal/crypto/pbes2.ts @@ -230,9 +230,6 @@ export function parsePbes2AlgorithmIdentifier(algorithmIdentifierDer: Uint8Array if (iterationsValue < 1) { throw new RangeError(`Invalid PBES2 iterations: must be >= 1, got ${iterationsValue}`); } - if (saltValue.length < 8) { - throw new RangeError(`Invalid PBES2 salt: must be >= 8 bytes, got ${saltValue.length}`); - } if (ivValue.length !== 16) { throw new RangeError(`Invalid PBES2 IV: must be exactly 16 bytes, got ${ivValue.length}`); } diff --git a/src/keys/keys.ts b/src/keys/keys.ts index c34eecf..87cde01 100644 --- a/src/keys/keys.ts +++ b/src/keys/keys.ts @@ -1515,11 +1515,13 @@ function parsePkcs8PrivateKey(der: Uint8Array): { readonly privateKeyDer: Uint8Array; } { const children = readSequenceChildren(der); + const version = children[0]; const algorithm = children[1]; const privateKey = children[2]; if ( children.length < 3 || - children.length > 4 || + version === undefined || + version.tag !== 0x02 || algorithm === undefined || algorithm.tag !== 0x30 || privateKey === undefined || @@ -1527,6 +1529,10 @@ function parsePkcs8PrivateKey(der: Uint8Array): { ) { throw new Error('Malformed PKCS#8 private key'); } + const hasPublicKey = validateOneAsymmetricKeyTail(children.slice(3)); + if (readPkcs8Version(version.value) !== (hasPublicKey ? 1 : 0)) { + throw new Error('Malformed PKCS#8 private key'); + } const algorithmChildren = readSequenceChildren( der.slice(algorithm.start - algorithm.headerLength, algorithm.end), ); @@ -1550,6 +1556,56 @@ function parsePkcs8PrivateKey(der: Uint8Array): { }; } +/** + * Validate the OneAsymmetricKey tail after `privateKey` and report whether a + * `publicKey [1]` field is present. + * + * RFC 5958 §2 encodes `attributes [0]` as an IMPLICIT constructed `SET OF` + * (tag `A0`); RFC 8410 §7 adds `publicKey [1]` as an IMPLICIT primitive + * `BIT STRING` (tag `81`) after it. Each appears at most once and in that order; + * unknown later extension additions are tolerated per the type's X.680 + * extensibility marker. + */ +function validateOneAsymmetricKeyTail(tail: readonly DerElement[]): boolean { + let seenAttributes = false; + let seenPublicKey = false; + let seenUnknown = false; + for (const child of tail) { + const contextNumber = (child.tag & 0xc0) === 0x80 ? child.tag & 0x1f : -1; + if (contextNumber === 0) { + if (seenAttributes || seenPublicKey || seenUnknown || child.tag !== 0xa0) { + throw new Error('Malformed PKCS#8 private key'); + } + seenAttributes = true; + } else if (contextNumber === 1) { + if (seenPublicKey || seenUnknown || child.tag !== 0x81) { + throw new Error('Malformed PKCS#8 private key'); + } + validatePublicKeyBitString(child.value); + seenPublicKey = true; + } else { + seenUnknown = true; + } + } + return seenPublicKey; +} + +/** Reject a `publicKey [1]` BIT STRING that is not octet-aligned or carries no key octets. */ +function validatePublicKeyBitString(content: Uint8Array): void { + if (content.length < 2 || content[0] !== 0x00) { + throw new Error('Malformed PKCS#8 private key'); + } +} + +/** Decode the canonical RFC 5958 version INTEGER content, `v1(0)` or `v2(1)`. */ +function readPkcs8Version(content: Uint8Array): number { + const value = content[0]; + if (content.length !== 1 || (value !== 0x00 && value !== 0x01)) { + throw new Error('Malformed PKCS#8 private key'); + } + return value; +} + /** * Extract the optional `parameters [0]` curve identifier from a SEC 1 ECPrivateKey. * @@ -1572,6 +1628,8 @@ function parseSec1PrivateKey(der: Uint8Array): { children.length > 4 || version === undefined || version.tag !== 0x02 || + version.value.length !== 1 || + version.value[0] !== 0x01 || privateKey === undefined || privateKey.tag !== 0x04 || (third !== undefined && third.tag !== 0xa0 && third.tag !== 0xa1) || diff --git a/test/internals.test.ts b/test/internals.test.ts index 68e60b5..04e4596 100644 --- a/test/internals.test.ts +++ b/test/internals.test.ts @@ -1251,6 +1251,19 @@ describe('pbes2.ts edge cases', () => { expect(() => parsePbes2AlgorithmIdentifier(Uint8Array.of(0x30, 0x00))).toThrow(); }); + it('accepts a PBES2 salt shorter than 8 bytes on decode (RFC 8018 §4.1)', () => { + // The salt "need not be checked for a particular format by the party + // receiving the salt", so `openssl pkcs8 -saltlen 4` must decode. + const der = encodePbes2AlgorithmIdentifier({ + iterations: 2048, + salt: new Uint8Array(4), + iv: new Uint8Array(16), + cipher: 'AES-256-CBC', + prf: 'HMAC-SHA-256', + }); + expect(parsePbes2AlgorithmIdentifier(der).salt.length).toBe(4); + }); + it('parsePbes2AlgorithmIdentifier throws on non-PBES2 OID', () => { const wrong = sequence([objectIdentifier('1.2.3.4'), sequence([])]); expect(() => parsePbes2AlgorithmIdentifier(wrong)).toThrow(/Unsupported encryption/); diff --git a/test/keys.test.ts b/test/keys.test.ts index e6e0c8a..de16aed 100644 --- a/test/keys.test.ts +++ b/test/keys.test.ts @@ -1,4 +1,4 @@ -import { describe, expect, it } from 'bun:test'; +import { describe, expect, it, test } from 'bun:test'; import { X509Certificate } from 'node:crypto'; import type { KeyPairMaterial } from '#micro509'; import { @@ -45,6 +45,7 @@ import { pemEncode, unwrap, } from '#micro509'; +import { hexToBytes } from '#test/helpers'; /** Minimal shape every `import*` Result satisfies, success or failure. */ type FailableImport = @@ -493,6 +494,17 @@ describe('keys', () => { expect(reimported.type).toBe('private'); }); + it('rejects a SEC1 ECPrivateKey whose version is not 1 (RFC 5915 §3)', async () => { + const { sequence, integerFromNumber, octetString } = await import( + '#micro509/internal/asn1/der' + ); + const versionTwo = sequence([integerFromNumber(2), octetString(new Uint8Array(32))]); + const result = await importSec1Der(versionTwo, { kind: 'ecdsa', curve: 'P-256' }); + expect(result.ok).toBe(false); + if (result.ok) throw new Error('unreachable'); + expect(result.error.message).toContain('Malformed SEC 1'); + }); + it('round-trips EC P-521 keys through SEC1', async () => { const keys = await generateKeyPair({ kind: 'ecdsa', @@ -682,6 +694,68 @@ describe('keys: coverage — malformed inputs', () => { ); }); + test.failing('imports RFC 5958 v2 OneAsymmetricKey with attributes and publicKey (oven-sh/bun#35432)', async () => { + const oneAsymmetricKey = hexToBytes( + '3053020101300506032b657004220420' + + '9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60' + + 'a000812100' + + 'd75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a', + ); + const key = unwrap(await importPkcs8Der(oneAsymmetricKey, { kind: 'ed25519' })); + expect(key.type).toBe('private'); + expect(key.algorithm.name).toBe('Ed25519'); + }); + + test('rejects malformed OneAsymmetricKey tails per RFC 5958/RFC 8410', async () => { + const { integerFromNumber, objectIdentifier, octetString, sequence } = await import( + '#micro509/internal/asn1/der' + ); + const seedHex = '9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60'; + const pubHex = 'd75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a'; + const version1 = integerFromNumber(1); + const version0 = integerFromNumber(0); + const algorithm = sequence([objectIdentifier('1.3.101.112')]); + const privateKey = octetString(octetString(hexToBytes(seedHex))); + const attributes = hexToBytes('a000'); + const publicKey = hexToBytes(`812100${pubHex}`); + const cases: ReadonlyArray<{ name: string; version: Uint8Array; tail: Uint8Array[] }> = [ + { + name: 'attributes [0] as primitive 80', + version: version1, + tail: [hexToBytes('8000'), publicKey], + }, + { + name: 'publicKey [1] as constructed a1', + version: version1, + tail: [attributes, hexToBytes(`a12100${pubHex}`)], + }, + { name: 'duplicate publicKey [1]', version: version1, tail: [publicKey, publicKey] }, + { + name: 'publicKey [1] before attributes [0]', + version: version1, + tail: [publicKey, attributes], + }, + { + name: 'publicKey present but version v1', + version: version0, + tail: [attributes, publicKey], + }, + { name: 'empty publicKey BIT STRING', version: version1, tail: [hexToBytes('810100')] }, + ]; + for (const { name, version, tail } of cases) { + const der = sequence([version, algorithm, privateKey, ...tail]); + try { + await expectImportFailure( + importPkcs8Der(der, { kind: 'ed25519' }), + 'malformed', + 'Malformed PKCS#8 private key', + ); + } catch (cause) { + throw new Error(`case "${name}" failed`, { cause }); + } + } + }); + it('importPkcs8Der and base64 throw on PKCS#8 with wrong privateKey tag', async () => { const { integerFromNumber, nullValue, objectIdentifier, sequence } = await import( '#micro509/internal/asn1/der'