RFC 6030
Portable Symmetric Key Container (PSKC)
RFC 6030: Portable Symmetric Key Container (PSKC) 🎀
Part 1 of 12 💖
- RFC number: 6030
- Stream: Internet Engineering Task Force (IETF)
- Authors: P. Hoyer (ActivIdentity), M. Pei (VeriSign), S. Machani (Diversinet)
- Category: Standards Track
- ISSN: 2070-1721
- Date: October 2010
- Obsoletes / Updates: the header doesn't list anything this RFC obsoletes or updates 🧚
Abstract ✨
okay so this doc defines a symmetric key format 🔑 for moving symmetric keys around (transport and provisioning) and getting them into different kinds of crypto modules 💅. think One-Time Password (OTP) shared secrets, or symmetric crypto keys for strong authentication devices. the big payoff? enterprises can mix and match best-of-breed solutions from different vendors in the same infrastructure, and that's literally iconic 👑
Status of This Memo ✨
this is an Internet Standards Track document 🦋
it's a product of the Internet Engineering Task Force (IETF). it represents the consensus of the IETF community, got public review, and was approved for publication by the Internet Engineering Steering Group (IESG). more info on Internet Standards is in Section 2 of RFC 5741 📚
for the current status, any errata, and how to send feedback, check http://www.rfc-editor.org/info/rfc6030 🌸
Copyright Notice ✨
Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved. ©️🎀
this doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they stand on the publication date. please actually read these, bestie, because they spell out your rights and restrictions for this document 🙈
also, any Code Components pulled out of this document must include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come without warranty, as described in the Simplified BSD License 💜
Table of Contents 🧾
1. Introduction ....................................................4
1.1. Key Words ..................................................4
1.2. Version Support ............................................4
1.3. Namespace Identifiers ......................................5
1.3.1. Defined Identifiers .................................5
1.3.2. Referenced Identifiers ..............................5
2. Terminology .....................................................6
3. Portable Key Container Entities Overview and Relationships ......6
4. <KeyContainer> Element: The Basics ..............................8
4.1. <Key>: Embedding Keying Material and Key-Related
Information ................................................8
4.2. Key Value Encoding ........................................10
4.2.1. AES Key Value Encoding .............................11
4.2.2. Triple-DES Key Value Encoding ......................11
4.3. Transmission of Supplementary Information .................12
4.3.1. <DeviceInfo> Element: Unique Device
Identification .....................................13
4.3.2. <CryptoModuleInfo> Element: CryptoModule
Identification .....................................15
4.3.3. <UserId> Element: User Identification ..............15
4.3.4. <AlgorithmParameters> Element:
Supplementary Information for OTP and CR Algorithms 15
4.4. Transmission of Key Derivation Values .....................17
5. Key Policy .....................................................19
5.1. PIN Algorithm Definition ..................................23
6. Key Protection Methods .........................................23
6.1. Encryption Based on Pre-Shared Keys .......................24
6.1.1. MAC Method .........................................26
6.2. Encryption Based on Passphrase-Based Keys .................27
6.3. Encryption Based on Asymmetric Keys .......................29
6.4. Padding of Encrypted Values for Non-Padded
Encryption Algorithms .....................................31
7. Digital Signature ..............................................31
8. Bulk Provisioning ..............................................33
9. Extensibility ..................................................35
10. PSKC Algorithm Profile ........................................36
10.1. HOTP .....................................................36
10.2. PIN ......................................................37
11. XML Schema ....................................................38
12. IANA Considerations ...........................................44
12.1. Content-Type Registration for 'application/pskc+xml' .....44
12.2. XML Schema Registration ..................................45
12.3. URN Sub-Namespace Registration ...........................46
12.4. PSKC Algorithm Profile Registry ..........................46
12.5. PSKC Version Registry ....................................47
12.6. Key Usage Registry .......................................47
13. Security Considerations .......................................48
13.1. PSKC Confidentiality .....................................49
13.2. PSKC Integrity ...........................................50
13.3. PSKC Authenticity ........................................50
14. Contributors ..................................................50
15. Acknowledgements ..............................................50
16. References ....................................................51
16.1. Normative References .....................................51
16.2. Informative References ...................................52
Appendix A. Use Cases ............................................54
A.1. Online Use Cases ..........................................54
A.1.1. Transport of Keys from Server to Cryptographic
Module ................................................54
A.1.2. Transport of Keys from Cryptographic Module to
Cryptographic Module ..................................54
A.1.3. Transport of Keys from Cryptographic Module to
Server ................................................55
A.1.4. Server-to-Server Bulk Import/Export of Keys ...........55
A.2. Offline Use Cases .........................................55
A.2.1. Server-to-Server Bulk Import/Export of Keys ...........55
Appendix B. Requirements .........................................561. Introduction ✨
okay so symmetric-key systems are everywhere now 🌈 think encrypting data at rest, or strong authentication based on One-Time Password (OTP) and Challenge/Response (CR) mechanisms. that means vendors really need to interoperate, and we need a standard format for importing and exporting (provisioning) symmetric keys. the tea is that vendors of authentication servers and service providers have traditionally used proprietary formats for this, which makes it super hard to use tokens from two different vendors 😭
so this document defines a standardized XML-based key container called Portable Symmetric Key Container (PSKC) 🎁 for transporting symmetric keys and their key-related metadata. it also lays out the information elements that are required when a symmetric key is used for a specific purpose, like the initial counter in the HMAC-Based One-Time Password (HOTP) [HOTP] algorithm 🔢. and it creates an IANA registry for algorithm profiles, so algorithms, their metadata, and their PSKC transmission profile can all be recorded in one centralized, standardized spot 🦋
1.1. Key Words 🗝️
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]. basically these words are the rulebook 📖
1.2. Version Support 🧚
there's a provision in the syntax for an explicit version number. right now only version "1.0" is specified 🌸
the numbering scheme for PSKC versions is <major>.<minor>. the major and minor numbers "MUST" be treated as separate integers, and each number "MAY" be incremented past a single digit. so "PSKC 2.4" is a lower version than "PSKC 2.13", which is lower than "PSKC 12.3" 💅 (the numbers are compared as integers, not as decimals, so no tricks!). leading zeros, like "PSKC 6.01", "MUST" be ignored by recipients and "MUST NOT" be sent 🙈
the major version number should only be incremented if the message format (for example, the element structure) has changed so dramatically that an older implementation can't interoperate with a newer one 💀 the minor version number is for new capabilities. an entity with a smaller minor version number "MUST" ignore it, but an entity with the larger minor version number uses it for informational purposes 🫶
1.3. Namespace Identifiers 🎀
this document uses Uniform Resource Identifiers (URIs) [RFC3986] to identify resources, algorithms, and semantics 🌟
1.3.1. Defined Identifiers 💜
the XML namespace [XMLNS] URI for Version 1.0 of PSKC is:
urn:ietf:params:xml:ns:keyprov:pskcreferences to qualified elements in the PSKC schema defined here, and used in the examples, use the prefix pskc, defined as xmlns:pskc="urn:ietf:params:xml:ns:keyprov:pskc". it is "RECOMMENDED" to use this namespace in implementations 🍓
1.3.2. Referenced Identifiers 🦋
the PSKC syntax in this document relies on algorithm identifiers and elements defined in the XML Signature [XMLDSIG] namespace:
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"references to the XML Signature namespace use the prefix ds ✍️
PSKC also relies on algorithm identifiers and elements from the XML Encryption [XMLENC] namespace:
xmlns:xenc="http://www.w3.org/2001/04/xmlenc#"references to the XML Encryption namespace use the prefix xenc 🔐
when protecting keys in transport with passphrase-based keys, PSKC also relies on the derived key element from the XML Encryption Version 1.1 [XMLENC11] namespace:
xmlns:xenc11="http://www.w3.org/2009/xmlenc11#"references to the XML Encryption Version 1.1 namespace use the prefix xenc11 ✨
same deal for passphrase-based keys: PSKC also relies on algorithm identifiers and elements from the PKCS #5 [PKCS5] namespace:
xmlns:pkcs5=
"http://www.rsasecurity.com/rsalabs/pkcs/schemas/pkcs-5v2-0#"references to the PKCS #5 namespace use the prefix pkcs5 🧁
2. Terminology 📚
NOTE: in the subsequent sections of the document, we highlight mandatory XML elements and attributes. optional elements and attributes are not explicitly indicated, so if it doesn't say mandatory, it's optional. 🫶
3. Portable Key Container Entities Overview and Relationships ✨
okay so the portable key container is built on an XML schema definition, and it's got six main conceptual entities that work together like a whole squad 💖
- KeyContainer entity: the container that carries a bunch of KeyPackage entities. A valid container MUST carry at least one KeyPackage entity.
- KeyPackage entity: a package holding at most one key plus its related provisioning endpoint or current usage endpoint, like a physical or virtual device and a specific CryptoModule.
- DeviceInfo entity: all the info about the device and the criteria that uniquely identify it 🧚
- CryptoModuleInfo entity: info about the CryptoModule where the keys live or where they get provisioned to 🔐
- Key entity: the key that's being transported or provisioned 🗝️
- Data entity: a list of metadata about the key. The element name is the metadata's name, and its value is either encrypted (for example, the <Data> element <Secret>) or plaintext (for example, the <Data> element <Counter>) 💅
Figure 1 shows the high-level structure of the PSKC data elements. Bestie, look at how it all connects, it's literally so organized 😭
-----------------
| KeyContainer |
|---------------|
| EncryptionKey |
| Signature |
| ... |
-----------------
|
|
/|\ 1..n
---------------- ----------------
| KeyPackage | 0..1| DeviceInfo |
|--------------|--------|--------------|
| |-- | SerialNumber |
---------------- | | Manufacturer |
| | | .... |
| | ----------------
/|\ 0..1 |
---------------- | --------------------
| Key | | 0..1| CryptoModuleInfo |
|--------------| -----|------------------|
| Id | | Id |
| Algorithm | |.... |
| UserId | --------------------
| Policy |
| .... |
----------------
|
|
/|\ 0..n
--------------------------------------- - -
| | |
------------------ ---------------- -------- - -
| Data:Secret | | Data:Counter | | Data:other
|----------------| |--------------| |-- - -
| EncryptedValue | | PlainValue |
| ValueMAC | ----------------
------------------
Figure 1: PSKC Data Elements Relationship DiagramThe following sections describe in detail all the entities and related XML schema elements and attributes. Let's get into it 🦋
4. <KeyContainer> Element: The Basics
In its most basic form, a PSKC document uses the top-level element <KeyContainer> and a single <KeyPackage> element to carry key information. Simple and iconic 🎀
The example below shows a simple PSKC document. We'll use it to walk through the structure of the <KeyContainer> element and its child elements.
<?xml version="1.0" encoding="UTF-8"?>
<KeyContainer Version="1.0"
Id="exampleID1"
xmlns="urn:ietf:params:xml:ns:keyprov:pskc">
<KeyPackage>
<Key Id="12345678"
Algorithm="urn:ietf:params:xml:ns:keyprov:pskc:hotp">
<Issuer>Issuer-A</Issuer>
<Data>
<Secret>
<PlainValue>MTIzNA==
</PlainValue>
</Secret>
</Data>
</Key>
</KeyPackage>
</KeyContainer>
Figure 2: Basic PSKC Key Container ExampleNow the attributes of the <KeyContainer> element. Here's the tea ☕
Version: this one tells you which version of the PSKC schema you're looking at. This specification defines the initial version ("1.0") of the PSKC schema. This attribute MUST be included. Non-negotiable, bestie 💅Id: this carries a unique identifier for the container. It helps you pick out one specific key container when several are embedded in bigger XML documents 🧚
4.1. <Key>: Embedding Keying Material and Key-Related Information
The following attributes of the <Key> element MUST be included at a minimum. Main character requirements, obviously 👑
Id: this carries a unique identifier for the symmetric key in the context of key provisioning exchanges between two parties. So if PSKC gets used across multiple interactions between a sending and receiving party, with different containers referencing the same keys, theIdattribute of<Key>MUST use the same value. For example, after initial provisioning, if a system wants to update key metadata in the other system, the value of theIdattribute of the<Key>where the metadata is being updated MUST be the same as the originalIdattribute value that was provisioned. The identifier is defined as a string of alphanumeric characters 🔑Algorithm: this carries a unique identifier for the PSKC algorithm profile. The profile attaches specific semantics to the elements and attributes contained in the<Key>element. This document describes profiles for open standards algorithms in Section 10. Additional profiles are defined in the following informative document: [PSKC-ALGORITHM-PROFILES]. Extra credit, iykyk 🌈
The <Key> element has a bunch of optional child elements. Here's the starter pack:
<Issuer>: the name of the party that issued the key. For example, a bank "Foobar Bank, Inc." issuing hardware tokens to their retail banking users might set this element to 'Foobar Bank, Inc.'. Banking, but make it cute 🏦<FriendlyName>: a human-readable name for the secret key, so it's easier to reference. This element is for informational purposes only. It's a language-dependent string, so it SHOULD have an attributexml:lang="xx", wherexxis the language identifier specified in [RFC5646]. If there's noxml:langattribute present, implementations MUST assume the language is English, as defined by setting the attribute value to 'en' (e.g.,xml:lang="en"). Language check passed, ✨<AlgorithmParameters>: this carries parameters that influence the result of the algorithmic computation, like response truncation and format in OTP and CR algorithms. There's a more detailed discussion of this element in Section 4.3.4 🦋<Data>: this carries data about and related to the key. These child elements are defined for<Data>:<Secret>: the value of the key itself, in a binary representation. Check out Section 4.2 for more details on Key Value Encoding 🤫<Counter>: the event counter for event-based OTP algorithms 🔢<Time>: the time for time-based OTP algorithms. (If time intervals are used, this element carries the number of time intervals passed from a specific start point. Normally it's algorithm dependent.) ⏰<TimeInterval>: the time interval value for time-based OTP algorithms, in seconds (a typical value would be 30, indicating a time interval of 30 seconds) 💜<TimeDrift>: the device clock drift value for time-based OTP algorithms. It's an integer value (positive or negative drift) that indicates the number of time intervals that a validation server has established the device clock drifted after the last successful authentication. For example, say the last successful authentication established a device time value of 8 intervals from a specific start date, but the validation server determines the time value is 9 intervals. Then the server SHOULD record the drift as -1. Drift tracking is giving detective 🕵️♀️
All the elements listed above (and those defined in the future) follow a simple structure: they MUST support child elements to convey the data value in either plaintext or encrypted format. The three options are:
- Plaintext: the
<PlainValue>element carries a plaintext value that's typed, for example, to xs:integer. - Encrypted: the
<EncryptedValue>element carries an encrypted value. - ValueMAC: the
<ValueMAC>element is populated with a Message Authentication Code (MAC) generated from the encrypted value, in case the encryption algorithm doesn't support integrity checks.
The example in Figure 2 shows the <Data> element with two child elements, <Secret> and <Counter>. Both carry a plaintext value inside their <PlainValue> child element. Pretty clean, not gonna lie 💖
4.2. Key Value Encoding
Two parties receiving the same key value OCTET STRING, resulting from decoding the xs:base64Binary inside the <PlainValue> or <EncryptedValue> elements, must make use of the key in exactly the same way in order to interoperate. Same key, same vibes, no drama 🫶 To make sure that happens, it's necessary to define a correspondence between the OCTET STRING and the notation in the standard algorithm description that defines how the key is used. The next sections establish that correspondence for the AES algorithm [FIPS197] and the Triple Data Encryption Algorithm (TDEA or Triple DES) [SP800-67]. Unless otherwise specified for a specific algorithm, the OCTET STRING encoding MUST follow the AES Key Value Encoding.
4.2.1. AES Key Value Encoding
[FIPS197], Section 5.2, titled "Key Expansion", uses the input key as an array of bytes indexed starting at 0. The first octet of the OCTET STRING SHALL become the key byte in the AES, labeled index 0 in [FIPS197]. The succeeding octets of the OCTET STRING SHALL become key bytes in AES, in increasing index order. Index order, but make it aesthetic 🌸
Proper parsing and key load of the contents of the OCTET STRING for AES SHALL be determined by using the following value for the <PlainValue> element (binaryBase64-encoded) to generate and match the key expansion test vectors in [FIPS197], Appendix A, for AES:
Cipher Key: 2b 7e 15 16 28 ae d2 a6 ab f7 15 88 09 cf 4f 3c
...
<PlainValue>K34VFiiu0qar9xWICc9PPA==</PlainValue>
...4.2.2. Triple-DES Key Value Encoding ✨
okay so a Triple-DES key is basically a squad of three keys 👯♀️: Key1, Key2, and Key3. Each one is 64 bits (56 key bits plus 8 parity bits 💅). Together they're called a key bundle [SP800-67]. A bundle can run on two or three independent keys. In two-key Triple DES, the same value is used for Key1 and Key3 🫶.
Each key gets expanded into a key schedule using a procedure from [SP800-67], Appendix A. That procedure numbers the bits from 1 to 64, with bit 1 being the leftmost, or most significant bit (MSB) 🧠. The first octet of the OCTET STRING SHALL be bits 1 through 8 of Key1, with bit 1 being the MSB. The second octet SHALL be bits 9 through 16 of Key1, and so on, so the trailing octet of the OCTET STRING SHALL be bits 57 through 64 of Key3 (or Key2 for two-key Triple DES) 🎀.
Proper parsing and key load of the OCTET STRING contents for Triple DES SHALL be determined by using the following <PlainValue> element (binaryBase64-encoded) to generate and match the key expansion test vectors in [SP800-67], Appendix B, for the key bundle. Here's the vibe check:
Key1 = 0123456789ABCDEF
Key2 = 23456789ABCDEF01
Key3 = 456789ABCDEF0123
...
<PlainValue>ASNFZ4mrze8jRWeJq83vAUVniavN7wEj</PlainValue>
...4.3. Transmission of Supplementary Information 🌸
okay this is the fun part 🤭. A PSKC document can carry a bunch of extra info about device identification, cryptographic module identification, user identification, and parameters for use with OTP and CR algorithms. The example below (see Figure 3) is our reference for the sub-sections that follow 🦋.
<?xml version="1.0" encoding="UTF-8"?>
<KeyContainer Version="1.0"
Id="exampleID1"
xmlns="urn:ietf:params:xml:ns:keyprov:pskc">
<KeyPackage>
<DeviceInfo>
<Manufacturer>Manufacturer</Manufacturer>
<SerialNo>987654321</SerialNo>
<UserId>DC=example-bank,DC=net</UserId>
</DeviceInfo>
<CryptoModuleInfo>
<Id>CM_ID_001</Id>
</CryptoModuleInfo>
<Key Id="12345678"
Algorithm="urn:ietf:params:xml:ns:keyprov:pskc:hotp">
<Issuer>Issuer</Issuer>
<AlgorithmParameters>
<ResponseFormat Length="8" Encoding="DECIMAL"/>
</AlgorithmParameters>
<Data>
<Secret>
<PlainValue>MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=
</PlainValue>
</Secret>
<Counter>
<PlainValue>0</PlainValue>
</Counter>
</Data>
<UserId>UID=jsmith,DC=example-bank,DC=net</UserId>
</Key>
</KeyPackage>
</KeyContainer>Figure 3: PSKC Key Container Example with Supplementary Data 💖
4.3.1. <DeviceInfo> Element: Unique Device Identification 📱
The <DeviceInfo> element uniquely identifies the device that the <KeyPackage> is provisioned to. Devices come in all kinds of form factors, like hardware tokens, smart-cards, soft tokens in a mobile phone, or a PC, so this element lets different child element combinations get used 🧩. When combined, the values of the child elements MUST uniquely identify the device. For example, for hardware tokens, the combo of <SerialNo> and <Manufacturer> uniquely identifies a device, but <SerialNo> on its own is not enough, because two different token manufacturers might issue devices with the same serial number. It's giving the same energy as an Issuer Distinguished Name plus serial number on a certificate 🔐.
The <DeviceInfo> element has the following child elements:
<Manufacturer>: This element indicates the manufacturer of the device. Values for the<Manufacturer>element MUST be taken from either [OATHMAN] prefixes (i.e., the left column) or from the IANA Private Enterprise Number Registry [IANAPENREG], using the Organization value. When the value is taken from [OATHMAN], "oath." MUST be prepended to the value (e.g., "oath.<prefix value from [OATHMAN]>"). When the value is taken from [IANAPENREG], "iana." MUST be prepended to the value (e.g., "iana.<Organization value from [IANAPENREG]>").<SerialNo>: This element contains the serial number of the device.<Model>: This element describes the model of the device (e.g., one-button-HOTP-token-V1).<IssueNo>: This element contains the issue number in case there are devices with the same serial number, so that they can be distinguished by different issue numbers.<DeviceBinding>: This element allows a provisioning server to ensure that the key is going to be loaded into the device for which the key provisioning request was approved. The device is bound to the request using a device identifier, e.g., an International Mobile Equipment Identity (IMEI) for the phone, or an identifier for a class of identifiers, e.g., those for which the keys are protected by a Trusted Platform Module (TPM) 📲.<StartDate>and<ExpiryDate>: These two elements indicate the start and end date of a device (such as the one on a payment card, used when issue numbers are not printed on cards) 💳. The date MUST be expressed as a dateTime value in "canonical representation" [W3C.REC-xmlschema-2-20041028]. Implementations SHOULD NOT rely on time resolution finer than milliseconds, and MUST NOT generate time instants that specify leap seconds. Keys that reside on the device SHOULD only be used when the current date is after the<StartDate>and before the<ExpiryDate>. Note that usage enforcement of the keys with respect to the dates MAY only happen on the validation server, as some devices such as smart cards do not have an internal clock 🙈. Systems thus SHOULD NOT rely upon the device to enforce key usage date restrictions.
Heads up bestie: smart cards may not even have a clock, so the device can't always be trusted to enforce date limits. Check it on the validation server! ⚠️
Depending on the device type, certain child elements of the <DeviceInfo> element MUST be included in order to uniquely identify a device. This document does not enumerate the different device types and therefore does not list the elements that are mandatory for each type of device.
4.3.2. <CryptoModuleInfo> Element: CryptoModule Identification 🔑
The <CryptoModuleInfo> element identifies the cryptographic module that the symmetric keys are or have been provisioned to. This lets you spot the cases where a device MAY contain more than one crypto module (e.g., a PC hosting a TPM and a connected token) 👀.
The <CryptoModuleInfo> element has a single child element that MUST be included:
<Id>: This element carries a unique identifier for the CryptoModule and is implementation specific. As such, it helps to identify a specific CryptoModule to which the key is being or was provisioned 🪪.
4.3.3. <UserId> Element: User Identification 🙋♀️
The <UserId> element identifies the user of a distinguished name, as defined in [RFC4514], for example, UID=jsmith,DC=example,DC=net 🧾.
Although the syntax of the user identifier is defined, there are no semantics associated with this element. In other words, there are no checks enforcing that only a specific user can use this key. As such, this element is for informational purposes only 🫠.
This element may appear in two places: as a child element of the <Key> element, where it indicates the user the key is associated with, and as a child element of the <DeviceInfo> element, where it indicates the user the device is associated with 💜.
4.3.4. <AlgorithmParameters> Element: Supplementary Information for OTP and CR Algorithms ✨
Okay bestie, <AlgorithmParameters> is a child of the <Key> element 🎀 and this doc defines three child elements for it: <Suite>, <ChallengeFormat>, and <ResponseFormat> 💅
<Suite> 🦋 This one is optional, and it holds extra details about the algorithm that depend on which algorithm you're using. For example, in an HMAC-based (Hashed MAC) OTP algorithm, it could say how strong the hash is (SHA1, SHA256, etc.) 🔐 For what each value means for each algorithm profile, check Section 10 📖
<ChallengeFormat> 🌸 This one describes the challenge in a CR (challenge-response) setup, and it has these attributes:
'Encoding': this MUST be included 🫶 It sets how the device expects the challenge to be encoded, and it MUST be one of these values:DECIMAL: only numerical digitsHEXADECIMAL: hexadecimal responseALPHANUMERIC: all letters and numbers (case sensitive)BASE64: Base-64 encoded, as defined in Section 4 of [RFC4648]BINARY: binary data
'CheckDigit': this tells the device whether it needs to check the Luhn check digit tacked onto the end of a challenge (the one defined in [ISOIEC7812]) 🔢 It's only valid when'Encoding'isDECIMAL.TRUEmeans the device WILL check that digit, andFALSEmeans it will NOT.
Heads up: the rule above is the one that matters, so it'sTRUEorFALSEonly, no other vibes.
'Min': this sets the smallest challenge the device will accept in CR mode, and it MUST be included 📏 ForDECIMAL,HEXADECIMAL, orALPHANUMERIC, the value counts digits or characters. ForBASE64orBINARY, it counts bytes of the unencoded value.'Max': same deal, but for the biggest challenge the device will accept in CR mode, and it MUST be included 📐 Same counting rules as'Min'.
<ResponseFormat> 🍓 This one describes the result of a computation, so it sets the format of the OTP or the response to a challenge. When the key is a PIN, this element holds the PIN's format too (e.g., DECIMAL, length 4 for a 4-digit PIN) 🔑 It has these attributes:
'Encoding': this sets the encoding of the response the device makes, and it MUST be included and MUST be one of these values:DECIMAL,HEXADECIMAL,ALPHANUMERIC,BASE64, orBINARY💜'CheckDigit': this says whether the device needs to tack a Luhn check digit (from [ISOIEC7812]) onto the response 🧾 It's only valid when'Encoding'isDECIMAL.TRUEmeans the device WILL append it, andFALSEmeans it will NOT.'Length': this sets how long the response the device generates is, and it MUST be included 📏 ForDECIMAL,HEXADECIMAL, orALPHANUMERIC, it counts digits or characters. ForBASE64orBINARY, it counts bytes of the unencoded value.
4.4. Transmission of Key Derivation Values 🧚
Okay so the <KeyProfileId> element is a child of <Key> and it's a unique ID that the sender and receiver use to point at a set of key attribute values 🦋 Those values are NOT sent inside the container. Instead, the two parties agree on them out of band (aka outside the protocol), and this element is just the reference to that set 💖 It's giving secret handshake energy. Think about a smart card application personalization profile id tied to specific attribute values on the card that affect how a response gets computed 🪪
Here's a fun example. MasterCard's Chip Authentication Program [CAP] is the vibe. The sender and receiver agree that KeyProfileId='1' stands for a certain set of values (like the Internet Authentication Flag (IAF) set to one specific value) 🌈 When the <KeyContainer> is sent, those values are NOT sent as key attributes. The container just says <KeyProfileId> with the agreed profile (here, '1') 🫶 The receiver then matches up all the key attributes in that profile, which were agreed on out of band, with the imported keys ✨ This is super common between a manufacturing service run by company A and a validation service run by company B, because it avoids sending the same set of key attribute values over and over again 🙈
The <KeyReference> element holds a reference to an external key that's used with a key derivation scheme 🗝️ In that case, the parent <Key> element will NOT include the <Secret> subelement of <Data>, which is where the key value (the secret) normally goes. Only the reference to the external master key gets sent instead (e.g., a PKCS #11 key label) 👑
<?xml version="1.0" encoding="UTF-8"?>
<KeyContainer Version="1.0" Id="exampleID1"
xmlns="urn:ietf:params:xml:ns:keyprov:pskc">
<KeyPackage>
<DeviceInfo>
<Manufacturer>Manufacturer</Manufacturer>
<SerialNo>987654321</SerialNo>
</DeviceInfo>
<CryptoModuleInfo>
<Id>CM_ID_001</Id>
</CryptoModuleInfo>
<Key Id="12345678"
Algorithm="urn:ietf:params:xml:ns:keyprov:pskc:hotp">
<Issuer>Issuer</Issuer>
<AlgorithmParameters>
<ResponseFormat Length="8" Encoding="DECIMAL"/>
</AlgorithmParameters>
<KeyProfileId>keyProfile1</KeyProfileId>
<KeyReference>MasterKeyLabel
</KeyReference>
<Data>
<Counter>
<PlainValue>0</PlainValue>
</Counter>
</Data>
<Policy>
<KeyUsage>OTP</KeyUsage>
</Policy>
</Key>
</KeyPackage>
</KeyContainer>Figure 4: Example of a PSKC Document Transmitting an HOTP Key via Key
Derivation ValuesLast bit of the example, and it's a whole vibe 🍓 The key value gets derived from three things: the value of the <SerialNo> element, the values agreed on by the sender and receiver (identified by the <KeyProfile> 'keyProfile1'), and an externally agreed-upon key that's referenced by the label 'MasterKeyLabel' 🌸
5. Key Policy ✨
okay bestie, this section is all about the <Policy> element 🎀 It's how you attach a key usage and key PIN protection policy to a specific key and its related metadata. It's a child element of the <Key> element, so it lives right inside the key's little world 🦋
Quick but important vibe check first: if a <Policy> has child elements or values (inside elements or attributes) that the recipient doesn't understand, the recipient MUST assume that key usage is NOT permitted. 😭 Lowkey genius, because it means an unknown extension can never accidentally unlock a key usage nobody agreed to. Safety first, periodt 💅
Let's start with an example that expands on Figure 3 🌸
<?xml version="1.0" encoding="UTF-8"?>
<KeyContainer
Version="1.0" Id="exampleID1"
xmlns="urn:ietf:params:xml:ns:keyprov:pskc">
<KeyPackage>
<DeviceInfo>
<Manufacturer>Manufacturer</Manufacturer>
<SerialNo>987654321</SerialNo>
</DeviceInfo>
<CryptoModuleInfo>
<Id>CM_ID_001</Id>
</CryptoModuleInfo>
<Key Id="12345678"
Algorithm="urn:ietf:params:xml:ns:keyprov:pskc:hotp">
<Issuer>Issuer</Issuer>
<AlgorithmParameters>
<ResponseFormat Length="8" Encoding="DECIMAL"/>
</AlgorithmParameters>
<Data>
<Secret>
<PlainValue>MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=
</PlainValue>
</Secret>
<Counter>
<PlainValue>0</PlainValue>
</Counter>
</Data>
<Policy>
<PINPolicy MinLength="4" MaxLength="4"
PINKeyId="123456781" PINEncoding="DECIMAL"
PINUsageMode="Local"/>
<KeyUsage>OTP</KeyUsage>
</Policy>
</Key>
</KeyPackage>
<KeyPackage>
<DeviceInfo>
<Manufacturer>Manufacturer</Manufacturer>
<SerialNo>987654321</SerialNo>
</DeviceInfo>
<CryptoModuleInfo>
<Id>CM_ID_001</Id>
</CryptoModuleInfo>
<Key Id="123456781"
Algorithm="urn:ietf:params:xml:ns:keyprov:pskc:pin">
<Issuer>Issuer</Issuer>
<AlgorithmParameters>
<ResponseFormat Length="4" Encoding="DECIMAL"/>
</AlgorithmParameters>
<Data>
<Secret>
<PlainValue>MTIzNA==</PlainValue>
</Secret>
</Data>
</Key>
</KeyPackage>
</KeyContainer>Figure 5: Non-Encrypted HOTP Secret Key Protected by PIN
This document defines the following <Policy> child elements, so let's go through them together 👑
<StartDate> and <ExpiryDate>: These two elements denote the validity period of a key 📅 The key MUST only be used between the start and the end date (inclusive). The date MUST be expressed as a dateTime value in "canonical representation" [W3C.REC-xmlschema-2-20041028]. Implementations SHOULD NOT rely on time resolution finer than milliseconds, and they MUST NOT generate time instants that specify leap seconds. When this element is absent, the current time is assumed as the start time ⏰
<NumberOfTransactions>: The value in this element indicates the maximum number of times a key carried within the PSKC document can be used by an application after it has been received 🔢 When this element is omitted, there is NO restriction on how many times a key can be used.
<KeyUsage>: The <KeyUsage> element puts constraints on the intended usage of the key 🎯 The recipient of the PSKC document MUST enforce the key usage. Right now, this document registers the following tokens:
OTP: The key MUST only be used for OTP generation.CR: The key MUST only be used for Challenge/Response purposes.Encrypt: The key MUST only be used for data encryption purposes.Integrity: The key MUST only be used to generate a keyed message digest for data integrity or authentication purposes.Verify: The key MUST only be used to verify a keyed message digest for data integrity or authentication purposes. This is the opposite key usage ofIntegrity, so it's like the yin to its yang ☯️Unlock: The key MUST only be used for an inverse Challenge/Response in the case where a user has locked the device by entering a wrong PIN too many times (for devices with PIN-input capability) 🔓Decrypt: The key MUST only be used for data decryption purposes.KeyWrap: The key MUST only be used for key wrap purposes.Unwrap: The key MUST only be used for key unwrap purposes.Derive: The key MUST only be used with a key derivation function to derive a new key (see also Section 8.2.4 of [NIST800-57]).Generate: The key MUST only be used to generate a new key based on a random number and the previous value of the key (see also Section 8.1.5.2.1 of [NIST800-57]).
The element MAY also be repeated to express several key usages. When this element is absent, no key usage constraint is assumed, which means the key MAY be used for every usage 🌈
<PINPolicy>: The <PINPolicy> element lets you attach PIN usage policy to a key 🔐 It has the following attributes:
PINKeyId: This attribute carries the uniqueIdattribute value of the<Key>element held within this<KeyContainer>that contains the value of the PIN that protects the key.PINUsageMode: This mandatory attribute indicates the way the PIN is used while the key is in use. The following values are defined:Local: The PIN is checked locally on the device before the key is allowed to be used in executing the algorithm.Prepend: The PIN is prepended to the algorithm response, so it MUST be checked by the party validating the response.Append: The PIN is appended to the algorithm response, so it MUST be checked by the party validating the response.Algorithmic: The PIN is used as part of the algorithm computation.
MaxFailedAttempts: This attribute indicates the maximum number of times the PIN may be entered wrongly before it MUST NOT be possible to use the key anymore. Typical reasonable values are in the positive integer range of at least 2 and no more than 10 🙈MinLength: This attribute indicates the minimum length of a PIN that can be set to protect the associated key. It MUST NOT be possible to set a PIN shorter than this value. If thePINFormatattribute is set toDECIMAL,HEXADECIMAL, orALPHANUMERIC, this value indicates the number of digits/characters. If thePINFormatattribute is set toBASE64orBINARY, this value indicates the number of bytes of the unencoded value.MaxLength: This attribute indicates the maximum length of a PIN that can be set to protect this key. It MUST NOT be possible to set a PIN longer than this value. If thePINFormatattribute is set toDECIMAL,HEXADECIMAL, orALPHANUMERIC, this value indicates the number of digits/characters. If thePINFormatattribute is set toBASE64orBINARY, this value indicates the number of bytes of the unencoded value.PINEncoding: This attribute indicates the encoding of the PIN and MUST be one of the values:DECIMAL,HEXADECIMAL,ALPHANUMERIC,BASE64, orBINARY.
If the PinUsageMode attribute is set to Local, then the device MUST enforce the restrictions indicated in the MaxFailedAttempts, MinLength, MaxLength, and PINEncoding attributes. Otherwise, they MUST be enforced on the server side 🖥️
5.1. PIN Algorithm Definition
The PIN algorithm is defined as:
boolean = comparePIN(K,P)Where:
Kis the stored symmetric credential (PIN) in binary format.Pis the proposed PIN to be compared, in binary format.
The function comparePIN is a straight octet comparison of K and P. Such a comparison MUST yield a value of TRUE (credentials matched) when the octet length of K is the same as the octet length of P and all octets comprising K are the same as the octets comprising P. Bit-for-bit, no drama 🧚
6. Key Protection Methods 🔒
Okay so, with everything we've covered so far, key information had to be sent in cleartext 😬 Enter the <EncryptionKey> element, which is a child element of the <KeyContainer> element. With it, you can encrypt keys and their associated information 🫶 The level of encryption is applied to the value of individual elements, and the encryption algorithm applied MUST be the same for all encrypted elements.
Keys are protected using the following methods: pre-shared keys, passphrase-based keys, and asymmetric keys 🗝️ When encryption algorithms that use Initialization Vectors (IVs) are used, for example AES-128-CBC, a random IV value MUST be generated for each value to be encrypted, and it MUST be prepended to the resulting encrypted value as specified in [XMLENC]. Main character energy for security, no cap 💜
6.1. Encryption Based on Pre-Shared Keys ✨
okay so bestie, Figure 6 is the example that shows how the content of the <Secret> element gets encrypted with AES-128-CBC plus PKCS #5 Padding 🔐. The plaintext value of <Secret> is '3132333435363738393031323334353637383930'. The pre-shared secret is called "Pre-shared-key", which gets set in the <KeyName> element (a child of the <EncryptionKey> element) 🗝️. The encryption key value is '12345678901234567890123456789012'.
The IV for the MAC key is '11223344556677889900112233445566', and the IV for the HOTP key is '000102030405060708090a0b0c0d0e0f' 🧚.
Here's the lowkey plot twist: AES-128-CBC does not give you integrity checks 💀, so a keyed MAC gets slapped onto the encrypted value. That MAC uses a MAC key and a MAC algorithm declared in the <MACMethod> element. In our example the algorithm is "http://www.w3.org/2000/09/xmldsig#hmac-sha1", and the MAC key is randomly generated as '1122334455667788990011223344556677889900', then encrypted with the encryption key above 🔥. The result of the keyed-MAC computation goes into the <ValueMAC> child element of <Secret> 💜.
<?xml version="1.0" encoding="UTF-8"?>
<KeyContainer Version="1.0"
xmlns="urn:ietf:params:xml:ns:keyprov:pskc"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">
<EncryptionKey>
<ds:KeyName>Pre-shared-key</ds:KeyName>
</EncryptionKey>
<MACMethod Algorithm="http://www.w3.org/2000/09/xmldsig#hmac-sha1">
<MACKey>
<xenc:EncryptionMethod
Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc"/>
<xenc:CipherData>
<xenc:CipherValue>
ESIzRFVmd4iZABEiM0RVZgKn6WjLaTC1sbeBMSvIhRejN9vJa2BOlSaMrR7I5wSX
</xenc:CipherValue>
</xenc:CipherData>
</MACKey>
</MACMethod>
<KeyPackage>
<DeviceInfo>
<Manufacturer>Manufacturer</Manufacturer>
<SerialNo>987654321</SerialNo>
</DeviceInfo>
<CryptoModuleInfo>
<Id>CM_ID_001</Id>
</CryptoModuleInfo>
<Key Id="12345678"
Algorithm="urn:ietf:params:xml:ns:keyprov:pskc:hotp">
<Issuer>Issuer</Issuer>
<AlgorithmParameters>
<ResponseFormat Length="8" Encoding="DECIMAL"/>
</AlgorithmParameters>
<Data>
<Secret>
<EncryptedValue>
<xenc:EncryptionMethod
Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc"/>
<xenc:CipherData>
<xenc:CipherValue>
AAECAwQFBgcICQoLDA0OD+cIHItlB3Wra1DUpxVvOx2lef1VmNPCMl8jwZqIUqGv
</xenc:CipherValue>
</xenc:CipherData>
</EncryptedValue>
<ValueMAC>Su+NvtQfmvfJzF6bmQiJqoLRExc=
</ValueMAC>
</Secret>
<Counter>
<PlainValue>0</PlainValue>
</Counter>
</Data>
</Key>
</KeyPackage>
</KeyContainer>Figure 6: AES-128-CBC Encrypted Pre-Shared Secret Key with HMAC-SHA1
Now the rules 📋✨ When you're protecting the payload with pre-shared keys, implementations MUST set the name of the specific pre-shared key in the <KeyName> element inside the <EncryptionKey> element. And when the encryption method uses a CBC mode that needs an explicit initialization vector (IV), the IV MUST be passed by prepending it to the encrypted value 🫶.
For systems implementing PSKC, it is RECOMMENDED to support AES-128-CBC (URI http://www.w3.org/2001/04/xmlenc#aes128-cbc) and KW-AES128 (URI http://www.w3.org/2001/04/xmlenc#kw-aes128) 🌸. Heads up, KW-AES128 is picky: the key being protected must be a multiple of 8 bytes in length 🙄. So if you need to protect keys of a different length, using the key-wrap algorithm with padding, as described in [RFC5649], is RECOMMENDED 💅. Some of the encryption algorithms that can optionally be implemented are listed below:
Algorithm | Uniform Resource Locator (URL)
---------------+-------------------------------------------------------
AES192-CBC | http://www.w3.org/2001/04/xmlenc#aes192-cbc
AES256-CBC | http://www.w3.org/2001/04/xmlenc#aes256-cbc
TripleDES-CBC | http://www.w3.org/2001/04/xmlenc#tripledes-cbc
Camellia128 | http://www.w3.org/2001/04/xmldsig-more#camellia128
Camellia192 | http://www.w3.org/2001/04/xmldsig-more#camellia192
Camellia256 | http://www.w3.org/2001/04/xmldsig-more#camellia256
KW-AES128 | http://www.w3.org/2001/04/xmlenc#kw-aes128
KW-AES192 | http://www.w3.org/2001/04/xmlenc#kw-aes192
KW-AES256 | http://www.w3.org/2001/04/xmlenc#kw-aes256
KW-TripleDES | http://www.w3.org/2001/04/xmlenc#kw-tripledes
KW-Camellia128 | http://www.w3.org/2001/04/xmldsig-more#kw-camellia128
KW-Camellia192 | http://www.w3.org/2001/04/xmldsig-more#kw-camellia192
KW-Camellia256 | http://www.w3.org/2001/04/xmldsig-more#kw-camellia2566.1.1. MAC Method 🦋
Okay, MAC time 🔑. When algorithms without integrity checks are used, like AES-128-CBC, a keyed-MAC value MUST be placed in the <ValueMAC> element of the <Data> element. In this case the MAC algorithm type MUST be set in the <MACMethod> element of the <KeyContainer> element 🎀. The MAC key MUST be a randomly generated key by the sender, be pre-agreed upon between the receiver and the sender, or be set by the application protocol that carries the PSKC document. It is RECOMMENDED that the sender generate a random MAC key 💖. When the sender does generate a random MAC key, the MAC key material MUST be encrypted with the same encryption key specified in the <EncryptionKey> element of the key container 🔐. The encryption method and encrypted value MUST be set in the <EncryptionMethod> element and the <CipherData> element, respectively, of the <MACKey> element inside the <MACMethod> element. The <MACKeyReference> element of the <MACMethod> element MAY be used to indicate a pre-shared MAC key or a provisioning protocol derived MAC key 🧚. For systems implementing PSKC, it is RECOMMENDED to implement HMAC-SHA1 (URI 'http://www.w3.org/2000/09/xmldsig#hmac-sha1') 👑. Some of the MAC algorithms that can optionally be implemented are:
Algorithm | Uniform Resource Locator (URL)
---------------+-----------------------------------------------------
HMAC-SHA224 | http://www.w3.org/2001/04/xmldsig-more#hmac-sha224
HMAC-SHA256 | http://www.w3.org/2001/04/xmldsig-more#hmac-sha256
HMAC-SHA384 | http://www.w3.org/2001/04/xmldsig-more#hmac-sha384
HMAC-SHA512 | http://www.w3.org/2001/04/xmldsig-more#hmac-sha5126.2. Encryption Based on Passphrase-Based Keys ✨
okay so Figure 7 shows how to encrypt the content of the <Secret> element using passphrase-based key derivation (PBKDF2) to make the encryption key, as defined in [PKCS5] 🔐 when you're deriving a key from a passphrase, the <DerivedKey> element from XML Encryption Version 1.1 [XMLENC11] MUST be used to specify it 💖 that <DerivedKey> gets set as the child element of the <EncryptionKey> element in the key container 🎀
the <DerivedKey> element is basically where you name the key derivation function and its parameters 🧚 and the encryption algorithm in this example, AES-128-CBC (URI http://www.w3.org/2001/04/xmlenc#aes128-cbc), MUST be set in the Algorithm attribute of the <EncryptionMethod> element used inside the encrypted data elements 💅
when PBKDF2 is the thing you're using, the Algorithm attribute of the <xenc11:KeyDerivationMethod> element MUST be set to http://www.rsasecurity.com/rsalabs/pkcs/schemas/pkcs-5#pbkdf2 🌸 and that same <xenc11:KeyDerivationMethod> element MUST include the <PBKDF2-params> child element, which holds the PBKDF2 parameters like the salt and the iteration count 🫶
also, if your encryption method uses a CBC mode with an explicit initialization vector (IV) that isn't a derived one, the IV MUST be passed by prepending it to the encrypted value 😭
okay, let's look at the example data we're using 👑
- Password:
qwerty - Salt:
0x123eff3c4a72129c - Iteration Count:
1000 - MAC Key:
0xbdaab8d648e850d25a3289364f7d7eaaf53ce581 - OTP Secret:
12345678901234567890
the derived encryption key comes out to 0x651e63cd57008476af1ff6422cd02e41 ✨ and the initialization vector (IV) is 0xa13be8f92db69ec992d99fd1b5ca05f0 🦋 that same key also encrypts the randomly chosen MAC key. you can use a different IV if you want, like 0xd864d39cbc0cdc8e1ee483b9164b9fa0 in the example 🍓 and the encryption with algorithm AES-128-CBC follows the spec in [XMLENC] 💜
<?xml version="1.0" encoding="UTF-8"?>
<pskc:KeyContainer
xmlns:pskc="urn:ietf:params:xml:ns:keyprov:pskc"
xmlns:xenc11="http://www.w3.org/2009/xmlenc11#"
xmlns:pkcs5=
"http://www.rsasecurity.com/rsalabs/pkcs/schemas/pkcs-5v2-0#"
xmlns:xenc="http://www.w3.org/2001/04/xmlenc#" Version="1.0">
<pskc:EncryptionKey>
<xenc11:DerivedKey>
<xenc11:KeyDerivationMethod
Algorithm=
"http://www.rsasecurity.com/rsalabs/pkcs/schemas/pkcs-5v2-0#pbkdf2">
<pkcs5:PBKDF2-params>
<Salt>
<Specified>Ej7/PEpyEpw=</Specified>
</Salt>
<IterationCount>1000</IterationCount>
<KeyLength>16</KeyLength>
<PRF/>
</pkcs5:PBKDF2-params>
</xenc11:KeyDerivationMethod>
<xenc:ReferenceList>
<xenc:DataReference URI="#ED"/>
</xenc:ReferenceList>
<xenc11:MasterKeyName>My Password 1</xenc11:MasterKeyName>
</xenc11:DerivedKey>
</pskc:EncryptionKey>
<pskc:MACMethod
Algorithm="http://www.w3.org/2000/09/xmldsig#hmac-sha1">
<pskc:MACKey>
<xenc:EncryptionMethod
Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc"/>
<xenc:CipherData>
<xenc:CipherValue>
2GTTnLwM3I4e5IO5FkufoOEiOhNj91fhKRQBtBJYluUDsPOLTfUvoU2dStyOwYZx
</xenc:CipherValue>
</xenc:CipherData>
</pskc:MACKey>
</pskc:MACMethod>
<pskc:KeyPackage>
<pskc:DeviceInfo>
<pskc:Manufacturer>TokenVendorAcme</pskc:Manufacturer>
<pskc:SerialNo>987654321</pskc:SerialNo>
</pskc:DeviceInfo>
<pskc:CryptoModuleInfo>
<pskc:Id>CM_ID_001</pskc:Id>
</pskc:CryptoModuleInfo>
<pskc:Key Algorithm=
"urn:ietf:params:xml:ns:keyprov:pskc:hotp" Id="123456">
<pskc:Issuer>Example-Issuer</pskc:Issuer>
<pskc:AlgorithmParameters>
<pskc:ResponseFormat Length="8" Encoding="DECIMAL"/>
</pskc:AlgorithmParameters>
<pskc:Data>
<pskc:Secret>
<pskc:EncryptedValue Id="ED">
<xenc:EncryptionMethod
Algorithm=
"http://www.w3.org/2001/04/xmlenc#aes128-cbc"/>
<xenc:CipherData>
<xenc:CipherValue>
oTvo+S22nsmS2Z/RtcoF8Hfh+jzMe0RkiafpoDpnoZTjPYZu6V+A4aEn032yCr4f
</xenc:CipherValue>
</xenc:CipherData>
</pskc:EncryptedValue>
<pskc:ValueMAC>LP6xMvjtypbfT9PdkJhBZ+D6O4w=
</pskc:ValueMAC>
</pskc:Secret>
</pskc:Data>
</pskc:Key>
</pskc:KeyPackage>
</pskc:KeyContainer>Figure 7: Example of a PSKC Document Using Encryption Based on Passphrase-Based Keys
6.3. Encryption Based on Asymmetric Keys 🦋
when you're using asymmetric keys to encrypt the child elements of the <Data> element, info about the certificate you're using MUST be stated in the <X509Data> element, which is a child of the <EncryptionKey> element 💅 the encryption algorithm MUST be indicated in the Algorithm attribute of the <EncryptionMethod> element too ✨ in the Figure 8 example, the algorithm is http://www.w3.org/2001/04/xmlenc#rsa_1_5 🎀
<?xml version="1.0" encoding="UTF-8" ?>
<KeyContainer
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
xmlns="urn:ietf:params:xml:ns:keyprov:pskc"
xmlns:xenc="http://www.w3.org/2001/04/xmlenc#"
id="KC0001"
Version="1.0">
<EncryptionKey>
<ds:X509Data>
<ds:X509Certificate>MIIB5zCCAVCgAwIBAgIESZp/vDANBgkqhkiG9w0BAQUFADA4M
Q0wCwYDVQQKEwRJRVRGMRMwEQYDVQQLEwpLZXlQcm92IFdHMRIwEAYDVQQDEwlQU0tDIF
Rlc3QwHhcNMDkwMjE3MDkxMzMyWhcNMTEwMjE3MDkxMzMyWjA4MQ0wCwYDVQQKEwRJRVR
GMRMwEQYDVQQLEwpLZXlQcm92IFdHMRIwEAYDVQQDEwlQU0tDIFRlc3QwgZ8wDQYJKoZI
hvcNAQEBBQADgY0AMIGJAoGBALCWLDa2ItYJ6su80hd1gL4cggQYdyyKK17btt/aS6Q/e
DsKjsPyFIODsxeKVV/uA3wLT4jQJM5euKJXkDajzGGOy92+ypfzTX4zDJMkh61SZwlHNJ
xBKilAM5aW7C+BQ0RvCxvdYtzx2LTdB+X/KMEBA7uIYxLfXH2Mnub3WIh1AgMBAAEwDQY
JKoZIhvcNAQEFBQADgYEAe875m84sYUJ8qPeZ+NG7REgTvlHTmoCdoByU0LBBLotUKuqf
rnRuXJRMeZXaaEGmzY1kLonVjQGzjAkU4dJ+RPmiDlYuHLZS41Pg6VMwY+03lhk6I5A/w
4rnqdkmwZX/NgXg06alnc2pBsXWhL4O7nk0S2ZrLMsQZ6HcsXgdmHo=
</ds:X509Certificate>
</ds:X509Data>
</EncryptionKey>
<KeyPackage>
<DeviceInfo>
<Manufacturer>TokenVendorAcme</Manufacturer>
<SerialNo>987654321</SerialNo>
</DeviceInfo>
<Key
Id="MBK000000001"
Algorithm="urn:ietf:params:xml:ns:keyprov:pskc:hotp">
<Issuer>Example-Issuer</Issuer>
<AlgorithmParameters>
<ResponseFormat Length="6" Encoding="DECIMAL"/>
</AlgorithmParameters>
<Data>
<Secret>
<EncryptedValue>
<xenc:EncryptionMethod
Algorithm="http://www.w3.org/2001/04/xmlenc#rsa_1_5"/>
<xenc:CipherData>
<xenc:CipherValue>hJ+fvpoMPMO9BYpK2rdyQYGIxiATYHTHC7e/sPLKYo5/r1v+4
xTYG3gJolCWuVMydJ7Ta0GaiBPHcWa8ctCVYmHKfSz5fdeV5nqbZApe6dofTqhRwZK6
Yx4ufevi91cjN2vBpSxYafvN3c3+xIgk0EnTV4iVPRCR0rBwyfFrPc4=
</xenc:CipherValue>
</xenc:CipherData>
</EncryptedValue>
</Secret>
<Counter>
<PlainValue>0</PlainValue>
</Counter>
</Data>
</Key>
</KeyPackage>
</KeyContainer>Figure 8: Example of a PSKC Document Using Encryption Based on Asymmetric Keys
for systems implementing PSKC, it is RECOMMENDED to implement the RSA-1.5 algorithm, identified by the URI http://www.w3.org/2001/04/xmlenc#rsa-1_5 🌈
there are some other asymmetric encryption algorithms you can optionally implement too 🧚 here they are:
Algorithm | Uniform Resource Locator (URL)
------------------+-------------------------------------------------
RSA-OAEP-MGF1P | http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p6.4. Padding of Encrypted Values for Non-Padded Encryption Algorithms 🍓
padding the encrypted values (like the key secret value) is required when you use key protection algorithms that don't support embedded padding AND the value isn't a multiple of the cipher block length 😭 like, if you're sending an HOTP key (20 bytes long) protected with AES in CBC mode (8-byte block cipher), you NEED padding, because 20 isn't a multiple of the 8-byte block length 💀
so in these cases, for systems implementing PSKC, it is RECOMMENDED to pad the value before encryption using PKCS #5 padding, as described in [PKCS5] 🫶
7. Digital Signature ✨
PSKC lets you add a digital signature to the XML document, as a child element of the <KeyContainer> element 🦋 you can find the description of the XML digital signature in [XMLDSIG] 💜
<?xml version="1.0" encoding="UTF-8"?>
<KeyContainer
xmlns="urn:ietf:params:xml:ns:keyprov:pskc"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
xmlns:xenc="http://www.w3.org/2001/04/xmlenc#"
Version="1.0">
<KeyPackage>
<DeviceInfo>
<Manufacturer>TokenVendorAcme</Manufacturer>
<SerialNo>0755225266</SerialNo>
</DeviceInfo>
<Key Id="123"
Algorithm="urn:ietf:params:xml:ns:keyprov:pskc:hotp">
<Issuer>Example-Issuer</Issuer>
<AlgorithmParameters>
<ResponseFormat Length="6" Encoding="DECIMAL"/>
</AlgorithmParameters>
<Data>
<Secret>
<PlainValue>
MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=
</PlainValue>
</Secret>
<Counter>
<PlainValue>0</PlainValue>
</Counter>
</Data>
</Key>
</KeyPackage>
<Signature>
<ds:SignedInfo>
<ds:CanonicalizationMethod
Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
<ds:SignatureMethod
Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
<ds:Reference URI="#Device">
<ds:DigestMethod
Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<ds:DigestValue>
j6lwx3rvEPO0vKtMup4NbeVu8nk=
</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>
j6lwx3rvEPO0vKtMup4NbeVu8nk=
</ds:SignatureValue>
<ds:KeyInfo>
<ds:X509Data>
<ds:X509IssuerSerial>
<ds:X509IssuerName>
CN=Example.com,C=US
</ds:X509IssuerName>
<ds:X509SerialNumber>
12345678
</ds:X509SerialNumber>
</ds:X509IssuerSerial>
</ds:X509Data>
</ds:KeyInfo>
</Signature>
</KeyContainer>Figure 9: Digital Signature Example
8. Bulk Provisioning 🧚
okay so bulk provisioning is lowkey the cutest feature 🎀 You get it by repeating the <KeyPackage> element over and over inside one <KeyContainer>, so you can hand out keys to different devices or crypto modules in a single go. The <EncryptionKey> element applies to every <KeyPackage> in there, so it's one setup for all of them ✨
When you're giving several keys to the same device, you still repeat <KeyPackage>, but the <DeviceInfo> inside has to carry the same sub-elements that identify that one device. In the example below, the keys for the device with SerialNo='9999999' are the ones that do this 💜
Figure 10 shows the whole thing in action 👑
<?xml version="1.0" encoding="UTF-8"?>
<KeyContainer Version="1.0"
xmlns="urn:ietf:params:xml:ns:keyprov:pskc">
<KeyPackage>
<DeviceInfo>
<Manufacturer>TokenVendorAcme</Manufacturer>
<SerialNo>654321</SerialNo>
</DeviceInfo>
<Key Id="1"
Algorithm="urn:ietf:params:xml:ns:keyprov:pskc:hotp">
<Issuer>Issuer</Issuer>
<AlgorithmParameters>
<ResponseFormat Length="8" Encoding="DECIMAL"/>
</AlgorithmParameters>
<Data>
<Secret>
<PlainValue>
MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=
</PlainValue>
</Secret>
<Counter>
<PlainValue>0</PlainValue>
</Counter>
</Data>
<Policy>
<StartDate>2006-05-01T00:00:00Z</StartDate>
<ExpiryDate>2006-05-31T00:00:00Z</ExpiryDate>
</Policy>
</Key>
</KeyPackage>
<KeyPackage>
<DeviceInfo>
<Manufacturer>TokenVendorAcme</Manufacturer>
<SerialNo>123456</SerialNo>
</DeviceInfo>
<Key Id="2"
Algorithm="urn:ietf:params:xml:ns:keyprov:pskc:hotp">
<Issuer>Issuer</Issuer>
<AlgorithmParameters>
<ResponseFormat Length="8" Encoding="DECIMAL"/>
</AlgorithmParameters>
<Data>
<Secret>
<PlainValue>
MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=
</PlainValue>
</Secret>
<Counter>
<PlainValue>0</PlainValue>
</Counter>
</Data>
<Policy>
<StartDate>2006-05-01T00:00:00Z</StartDate>
<ExpiryDate>2006-05-31T00:00:00Z</ExpiryDate>
</Policy>
</Key>
</KeyPackage>
<KeyPackage>
<DeviceInfo>
<Manufacturer>TokenVendorAcme</Manufacturer>
<SerialNo>9999999</SerialNo>
</DeviceInfo>
<Key Id="3"
Algorithm="urn:ietf:params:xml:ns:keyprov:pskc:hotp">
<Issuer>Issuer</Issuer>
<AlgorithmParameters>
<ResponseFormat Length="8" Encoding="DECIMAL"/>
</AlgorithmParameters>
<Data>
<Secret>
<PlainValue>
MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=
</PlainValue>
</Secret>
<Counter>
<PlainValue>0</PlainValue>
</Counter>
</Data>
<Policy>
<StartDate>2006-03-01T00:00:00Z</StartDate>
<ExpiryDate>2006-03-31T00:00:00Z</ExpiryDate>
</Policy>
</Key>
</KeyPackage>
<KeyPackage>
<DeviceInfo>
<Manufacturer>TokenVendorAcme</Manufacturer>
<SerialNo>9999999</SerialNo>
</DeviceInfo>
<Key Id="4"
Algorithm="urn:ietf:params:xml:ns:keyprov:pskc:hotp">
<Issuer>Issuer</Issuer>
<AlgorithmParameters>
<ResponseFormat Length="8" Encoding="DECIMAL"/>
</AlgorithmParameters>
<Data>
<Secret>
<PlainValue>
MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=
</PlainValue>
</Secret>
<Counter>
<PlainValue>0</PlainValue>
</Counter>
</Data>
<Policy>
<StartDate>2006-04-01T00:00:00Z</StartDate>
<ExpiryDate>2006-04-30T00:00:00Z</ExpiryDate>
</Policy>
</Key>
</KeyPackage>
</KeyContainer>Figure 10: Bulk Provisioning Example
9. Extensibility 🌈
this section is basically the list of PSKC's favourite extension points, so you know where you're allowed to glow up 💅
- New PSKC Version: whenever a new version of this doc is needed, it gets its own version number ✨ That number lives in the
'Version'attribute (see Section 4). The numbering scheme MUST follow Section 1.2, and the rules for extensibility are in Section 12. - New XML Elements: the schema and its extension points let you add new XML elements 🦋 Depending on the element, you've got different routes. In some places you can use the
<Extensions>element, and elsewhere you use the"<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>"extension point. - New XML Attributes: new XML attributes are fair game wherever an extension point has been defined, like the
"<xs:anyAttribute namespace="##other"/>"one in Section 11 🎀 - New PSKC Algorithm Profiles: this document defines two PSKC algorithm profiles, which you'll find in Section 10. An informational document describes more profiles [PSKC-ALGORITHM-PROFILES] 📚 And you can register even more, as described in Section 12.4.
- Algorithm URIs: Section 6 explains how keys and related data get protected, and a bunch of algorithms can do that job. Brand new algorithms can just point to a new algorithm URI 🍓
- Policy: Section 5 defines the policies you can attach to a key and its keying-related data. The
<Policy>element is one of those, and it lets you limit what a key can be used for, like "OTP usage only" 🔐 More values can be registered as described in Section 12.
10. PSKC Algorithm Profile 💖
10.1. HOTP
- Common Name:
HOTP - Class:
OTP - URI:
urn:ietf:params:xml:ns:keyprov:pskc:hotp - Algorithm Definition: [HOTP]
- Identifier Definition: (this RFC)
- Registrant Contact:
IESG - Deprecated:
FALSE - Profiling:
okay so the profiling rules for HOTP are the main event 🔥 The <KeyPackage> element MUST be present, and the <ResponseFormat> element (a child of <AlgorithmParameters>) MUST be used to set the OTP length and the value format 💅
The <Counter> element (see Section 4.1) MUST be provided as metadata for the key 🧚
and then there are a few extra constraints 👑
- The value of the
<Secret>element MUST contain key material that's at least 16 octets (128 bits) long, if it's present 💜 - The
<ResponseFormat>element MUST have the'Format'attribute set to"DECIMAL", and the'Length'attribute MUST indicate a length value between 6 and 9 (inclusive) 🌸 - The
<PINPolicy>element MAY be present, but the'PINUsageMode'attribute cannot be set to"Algorithmic"🙈
there's an example in Figure 3 if you want to peek ✨
10.2. PIN
- Common Name:
PIN - Class:
Symmetric static credential comparison - URI:
urn:ietf:params:xml:ns:keyprov:pskc:pin - Algorithm Definition: (this RFC) Section 5.1
- Identifier Definition: (this RFC)
- Registrant Contact:
IESG - Deprecated:
FALSE - Profiling:
the <Usage> element MAY be present, but none of its attributes are required 🦋 The <ResponseFormat> element MAY be used to indicate the PIN value format 🎀
The <Secret> element (see Section 4.1) MUST be provided 🫶
see the example in Figure 5 💖
11. XML Schema 👑
this section is the official XML schema for PSKC, so here it is in all its glory 💅
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:pskc="urn:ietf:params:xml:ns:keyprov:pskc"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
xmlns:xenc="http://www.w3.org/2001/04/xmlenc#"
targetNamespace="urn:ietf:params:xml:ns:keyprov:pskc"
elementFormDefault="qualified"
attributeFormDefault="unqualified">
<xs:import namespace="http://www.w3.org/2000/09/xmldsig#"
schemaLocation=
"http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/
xmldsig-core-schema.xsd"/>
<xs:import namespace="http://www.w3.org/2001/04/xmlenc#"
schemaLocation=
"http://www.w3.org/TR/2002/REC-xmlenc-core-20021210/xenc-schema.xsd"/>
<xs:import namespace="http://www.w3.org/XML/1998/namespace"/>
<xs:complexType name="KeyContainerType">
<xs:sequence>
<xs:element name="EncryptionKey"
type="ds:KeyInfoType" minOccurs="0"/>
<xs:element name="MACMethod"
type="pskc:MACMethodType" minOccurs="0"/>
<xs:element name="KeyPackage"
type="pskc:KeyPackageType" maxOccurs="unbounded"/>
<xs:element name="Signature"
type="ds:SignatureType" minOccurs="0"/>
<xs:element name="Extensions"
type="pskc:ExtensionsType"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="Version"
type="pskc:VersionType" use="required"/>
<xs:attribute name="Id"
type="xs:ID" use="optional"/>
</xs:complexType>
<xs:simpleType name="VersionType" final="restriction">
<xs:restriction base="xs:string">
<xs:pattern value="\d{1,2}\.\d{1,3}"/>
</xs:restriction>okay so the schema keeps going and it's giving complete main character energy 💅✨ here's the rest of the KeyType through MACMethodType definitions, plus the root KeyContainer element 🎀
</xs:simpleType>
<xs:complexType name="KeyType">
<xs:sequence>
<xs:element name="Issuer"
type="xs:string" minOccurs="0"/>
<xs:element name="AlgorithmParameters"
type="pskc:AlgorithmParametersType"
minOccurs="0"/>
<xs:element name="KeyProfileId"
type="xs:string" minOccurs="0"/>
<xs:element name="KeyReference"
type="xs:string" minOccurs="0"/>
<xs:element name="FriendlyName"
type="xs:string" minOccurs="0"/>
<xs:element name="Data"
type="pskc:KeyDataType" minOccurs="0"/>
<xs:element name="UserId"
type="xs:string" minOccurs="0"/>
<xs:element name="Policy"
type="pskc:PolicyType" minOccurs="0"/>
<xs:element name="Extensions"
type="pskc:ExtensionsType" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="Id"
type="xs:string" use="required"/>
<xs:attribute name="Algorithm"
type="pskc:KeyAlgorithmType" use="optional"/>
</xs:complexType>
<xs:complexType name="PolicyType">
<xs:sequence>
<xs:element name="StartDate"
type="xs:dateTime" minOccurs="0"/>
<xs:element name="ExpiryDate"
type="xs:dateTime" minOccurs="0"/>
<xs:element name="PINPolicy"
type="pskc:PINPolicyType" minOccurs="0"/>
<xs:element name="KeyUsage"
type="pskc:KeyUsageType"
minOccurs="0" maxOccurs="unbounded"/>
<xs:element name="NumberOfTransactions"
type="xs:nonNegativeInteger" minOccurs="0"/>
<xs:any namespace="##other"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="KeyDataType">
<xs:sequence>
<xs:element name="Secret"
type="pskc:binaryDataType" minOccurs="0"/>
<xs:element name="Counter"
type="pskc:longDataType" minOccurs="0"/>
<xs:element name="Time"
type="pskc:intDataType" minOccurs="0"/>
<xs:element name="TimeInterval"
type="pskc:intDataType" minOccurs="0"/>
<xs:element name="TimeDrift"
type="pskc:intDataType" minOccurs="0"/>
<xs:any namespace="##other"
processContents="lax"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="binaryDataType">
<xs:sequence>
<xs:choice>
<xs:element name="PlainValue"
type="xs:base64Binary"/>
<xs:element name="EncryptedValue"
type="xenc:EncryptedDataType"/>
</xs:choice>
<xs:element name="ValueMAC"
type="xs:base64Binary" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="intDataType">
<xs:sequence>
<xs:choice>
<xs:element name="PlainValue" type="xs:int"/>
<xs:element name="EncryptedValue"
type="xenc:EncryptedDataType"/>
</xs:choice>
<xs:element name="ValueMAC"
type="xs:base64Binary" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="stringDataType">
<xs:sequence>
<xs:choice>
<xs:element name="PlainValue" type="xs:string"/>
<xs:element name="EncryptedValue"
type="xenc:EncryptedDataType"/>
</xs:choice>
<xs:element name="ValueMAC"
type="xs:base64Binary" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="longDataType">
<xs:sequence>
<xs:choice>
<xs:element name="PlainValue" type="xs:long"/>
<xs:element name="EncryptedValue"
type="xenc:EncryptedDataType"/>
</xs:choice>
<xs:element name="ValueMAC"
type="xs:base64Binary" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="PINPolicyType">
<xs:attribute name="PINKeyId"
type="xs:string" use="optional"/>
<xs:attribute name="PINUsageMode"
type="pskc:PINUsageModeType"/>
<xs:attribute name="MaxFailedAttempts"
type="xs:unsignedInt" use="optional"/>
<xs:attribute name="MinLength"
type="xs:unsignedInt" use="optional"/>
<xs:attribute name="MaxLength"
type="xs:unsignedInt" use="optional"/>
<xs:attribute name="PINEncoding"
type="pskc:ValueFormatType" use="optional"/>
<xs:anyAttribute namespace="##other"/>
</xs:complexType>
<xs:simpleType name="PINUsageModeType">
<xs:restriction base="xs:string">
<xs:enumeration value="Local"/>
<xs:enumeration value="Prepend"/>
<xs:enumeration value="Append"/>
<xs:enumeration value="Algorithmic"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="KeyUsageType">
<xs:restriction base="xs:string">
<xs:enumeration value="OTP"/>
<xs:enumeration value="CR"/>
<xs:enumeration value="Encrypt"/>
<xs:enumeration value="Integrity"/>
<xs:enumeration value="Verify"/>
<xs:enumeration value="Unlock"/>
<xs:enumeration value="Decrypt"/>
<xs:enumeration value="KeyWrap"/>
<xs:enumeration value="Unwrap"/>
<xs:enumeration value="Derive"/>
<xs:enumeration value="Generate"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="DeviceInfoType">
<xs:sequence>
<xs:element name="Manufacturer"
type="xs:string" minOccurs="0"/>
<xs:element name="SerialNo"
type="xs:string" minOccurs="0"/>
<xs:element name="Model"
type="xs:string" minOccurs="0"/>
<xs:element name="IssueNo"
type="xs:string" minOccurs="0"/>
<xs:element name="DeviceBinding"
type="xs:string" minOccurs="0"/>
<xs:element name="StartDate"
type="xs:dateTime" minOccurs="0"/>
<xs:element name="ExpiryDate"
type="xs:dateTime" minOccurs="0"/>
<xs:element name="UserId"
type="xs:string" minOccurs="0"/>
<xs:element name="Extensions"
type="pskc:ExtensionsType" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="CryptoModuleInfoType">
<xs:sequence>
<xs:element name="Id" type="xs:string"/>
<xs:element name="Extensions"
type="pskc:ExtensionsType" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="KeyPackageType">
<xs:sequence>
<xs:element name="DeviceInfo"
type="pskc:DeviceInfoType" minOccurs="0"/>
<xs:element name="CryptoModuleInfo"
type="pskc:CryptoModuleInfoType" minOccurs="0"/>
<xs:element name="Key"
type="pskc:KeyType" minOccurs="0"/>
<xs:element name="Extensions"
type="pskc:ExtensionsType" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="AlgorithmParametersType">
<xs:choice>
<xs:element name="Suite" type="xs:string" minOccurs="0"/>
<xs:element name="ChallengeFormat" minOccurs="0">
<xs:complexType>
<xs:attribute name="Encoding"
type="pskc:ValueFormatType"
use="required"/>
<xs:attribute name="Min"
type="xs:unsignedInt" use="required"/>
<xs:attribute name="Max"
type="xs:unsignedInt" use="required"/>
<xs:attribute name="CheckDigits"
type="xs:boolean" default="false"/>
</xs:complexType>
</xs:element>
<xs:element name="ResponseFormat" minOccurs="0">
<xs:complexType>
<xs:attribute name="Encoding"
type="pskc:ValueFormatType"
use="required"/>
<xs:attribute name="Length"
type="xs:unsignedInt" use="required"/>
<xs:attribute name="CheckDigits"
type="xs:boolean" default="false"/>
</xs:complexType>
</xs:element>
<xs:element name="Extensions"
type="pskc:ExtensionsType" minOccurs="0"
maxOccurs="unbounded"/>
</xs:choice>
</xs:complexType>
<xs:complexType name="ExtensionsType">
<xs:sequence>
<xs:any namespace="##other"
processContents="lax" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="definition"
type="xs:anyURI" use="optional"/>
</xs:complexType>
<xs:simpleType name="KeyAlgorithmType">
<xs:restriction base="xs:anyURI"/>
</xs:simpleType>
<xs:simpleType name="ValueFormatType">
<xs:restriction base="xs:string">
<xs:enumeration value="DECIMAL"/>
<xs:enumeration value="HEXADECIMAL"/>
<xs:enumeration value="ALPHANUMERIC"/>
<xs:enumeration value="BASE64"/>
<xs:enumeration value="BINARY"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="MACMethodType">
<xs:sequence>
<xs:choice>
<xs:element name="MACKey"
type="xenc:EncryptedDataType" minOccurs="0"/>
<xs:element name="MACKeyReference"
type="xs:string" minOccurs="0"/>
</xs:choice>
<xs:any namespace="##other"
processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="Algorithm" type="xs:anyURI" use="required"/>
</xs:complexType>
<xs:element name="KeyContainer"
type="pskc:KeyContainerType"/>
</xs:schema>12. IANA Considerations ✨
12.1. Content-Type Registration for 'application/pskc+xml' 🎀
okay bestie, this is where we register a brand new media type 💖 it follows the procedures of RFC 4288 [RFC4288] and the guidelines in RFC 3023 [RFC3023], so it's all very official ✨
- MIME media type name:
application - MIME subtype name:
pskc+xml - Required parameters: There is no required parameter.
- Optional parameters:
charset. Indicates the character encoding of enclosed XML. - Encoding considerations: Uses XML, which can employ 8-bit characters, depending on the character encoding used. See RFC 3023 [RFC3023], Section 3.2.
- Security considerations: Please refer to Section 13 of RFC 6030. 🙈
- Interoperability considerations: None
- Published specification: RFC 6030.
- Applications which use this media type: This media type is being used as a symmetric key container format for transport and provisioning of symmetric keys (One-Time Password (OTP) shared secrets or symmetric cryptographic keys) to different types of strong authentication devices. As such, it is used for key provisioning systems. 🔑
- Additional information:
- Magic Number: None
- File Extension:
.pskcxml - Macintosh file type code:
'TEXT'
- Personal and email address to contact for further information: Philip Hoyer, Philip.Hoyer@actividentity.com
- Intended usage: LIMITED USE
- Restrictions on usage: None
- Author: This specification is a work item of the IETF KEYPROV working group, with mailing list address
<keyprov@ietf.org>. - Change controller: The IESG
<iesg@ietf.org>
12.2. XML Schema Registration 📜
This section registers an XML schema as per the guidelines in [RFC3688]. Super tidy 💅
- URI:
urn:ietf:params:xml:schema:keyprov:pskc - Registrant Contact: IETF KEYPROV Working Group, Philip Hoyer (Philip.Hoyer@actividentity.com).
XML Schema: The XML schema to be registered is contained in Section 11. Its first line is
<?xml version="1.0" encoding="UTF-8"?>and its last line is
</xs:schema>12.3. URN Sub-Namespace Registration 🌸
This section registers a new XML namespace, "urn:ietf:params:xml:ns:keyprov:pskc", per the guidelines in [RFC3688]. Namespace glow-up incoming ✨
- URI:
urn:ietf:params:xml:ns:keyprov:pskc - Registrant Contact: IETF KEYPROV Working Group, Philip Hoyer (Philip.Hoyer@actividentity.com).
XML:
BEGIN
<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.0//EN"
"http://www.w3.org/TR/xhtml-basic/xhtml-basic10.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type"
content="text/html;charset=iso-8859-1"/>
<title>PSKC Namespace</title>
</head>
<body>
<h1>Namespace for PSKC</h1>
<h2>urn:ietf:params:xml:ns:keyprov:pskc</h2>
<p>See <a href="http://www.rfc-editor.org/rfc/rfc6030.txt">
RFC 6030</a>.</p>
</body>
</html>END
12.4. PSKC Algorithm Profile Registry 🦋
IANA has created a registry for PSKC algorithm profiles in accordance with the principles set out in RFC 5226 [RFC5226]. It's giving organised 🗂️
As part of this registry, IANA maintains the following information:
- Common Name: The name by which the PSKC algorithm profile is generally referred.
- Class: The type of PSKC algorithm profile registry entry being created, such as encryption, Message Authentication Code (MAC), One-Time Password (OTP), Digest.
- URI: The URI to be used to identify the profile.
- Identifier Definition: IANA will add a pointer to the specification containing information about the PSKC algorithm profile registration.
- Algorithm Definition: A reference to the stable document in which the algorithm being used with the PSKC is defined.
- Registrant Contact: Contact information about the party submitting the registration request.
- Deprecated: TRUE if this entry has been deprecated based on expert approval and SHOULD not be used in any new implementations. Otherwise, FALSE.
- PSKC Profiling: Information about PSKC XML elements and attributes being used (or not) with this specific profile of PSKC.
PSKC algorithm profile identifier registrations are to be subject to Specification Required as per RFC 5226 [RFC5226]. Updates can be provided based on expert approval only. Based on expert approval, it is possible to mark entries as "deprecated". A designated expert will be appointed by the IESG.
IANA has added two initial values to the registry based on the algorithm profiles described in Section 10. Two starter profiles, we love a fresh start 🌱
12.5. PSKC Version Registry 🔢
IANA has created a registry for PSKC version numbers. The registry has the following structure:
PSKC Version | Specification
+---------------------------+----------------
| 1.0 | RFC 6030Standards action is required to define new versions of PSKC. It is not envisioned to deprecate, delete, or modify existing PSKC versions. So right now it's just 1.0, and that's iconic 👑
12.6. Key Usage Registry 🔑
IANA has created a registry for key usage. A description of the <KeyUsage> element can be found in Section 5.
As part of this registry IANA will maintain the following information:
- Key Usage: The identifier of the Key Usage.
- Specification: IANA will add a pointer to the specification containing information about the semantics of a new Key Usage registration.
- Deprecated: TRUE if this entry has been deprecated based on expert approval and SHOULD not be used in any new implementations. Otherwise, FALSE.
IANA has added these initial values to the registry:
Key Usage | Specification | Deprecated
+---------------+------------------------------+-----------
| OTP | [Section 5 of this document] | FALSE
| CR | [Section 5 of this document] | FALSE
| Encrypt | [Section 5 of this document] | FALSE
| Integrity | [Section 5 of this document] | FALSE
| Verify | [Section 5 of this document] | FALSE
| Unlock | [Section 5 of this document] | FALSE
| Decrypt | [Section 5 of this document] | FALSE
| KeyWrap | [Section 5 of this document] | FALSE
| Unwrap | [Section 5 of this document] | FALSE
| Derive | [Section 5 of this document] | FALSE
| Generate | [Section 5 of this document] | FALSE
+---------------+------------------------------+-----------Key Usage Registry registrations are to be subject to Specification Required as per RFC 5226 [RFC5226]. Expert Review is required to define new Key Usage values. Updates can be provided based on expert approval only. Based on expert approval, it is possible to mark entries as "deprecated". A designated expert will be appointed by the IESG.
13. Security Considerations 🚨
okay this section is seriously important, bestie, so no skipping 😭 The portable symmetric key container (PSKC) carries sensitive information (e.g., cryptographic keys) and may be transported across the boundaries of one secure perimeter to another. For example, a container residing within the secure perimeter of a back-end provisioning server in a secure room may be transported across the Internet to an end-user device attached to a personal computer. This means that special care MUST be taken to ensure the confidentiality, integrity, and authenticity of the information contained within.
13.1. PSKC Confidentiality 🔒
By design, the container allows two main approaches to guaranteeing the confidentiality of the information it contains while transported.
First, the container key data payload may be encrypted.
In this case, no transport layer security is required. However, standard security best practices apply when selecting the strength of the cryptographic algorithm for key data payload encryption. A symmetric cryptographic cipher SHOULD be used -- the longer the cryptographic key, the stronger the protection. Please see Section 6.1 for recommendations of key data payload protection using symmetric cryptographic ciphers. In cases where the exchange of key encryption keys between the sender and the receiver is not possible, asymmetric encryption of the key data payload may be employed, see Section 6.3. Similar to symmetric key cryptography, the stronger the asymmetric key, the more secure the protection.
If the key data payload is encrypted with a method that uses one of the password-based encryption methods (PBE methods) detailed in Section 6.2, the key data payload may be subjected to password dictionary attacks to break the encryption password and recover the information. Standard security best practices for selection of strong encryption passwords apply.
Additionally, it is strongly RECOMMENDED that practical implementations use PBESalt and PBEIterationCount when PBE encryption is used. A different PBESalt value per PSKC SHOULD be used for best protection.
The second approach to protecting the confidentiality of the key data is based on using lower-layer security mechanisms (e.g., [TLS], [IPsec]). The secure connection established between the source secure perimeter (the provisioning server from the example above) and the target perimeter (the device attached to the end-user computer) utilizes encryption to protect the messages that travel across that connection. No key data payload encryption is required in this mode. Secure connections that encrypt and digest each message provide an extra measure of security.
Because of the fact that the plaintext PSKC is protected only by the transport layer security, practical implementation MUST ensure protection against man-in-the-middle attacks. Authenticating the secure channel endpoints is critically important for eliminating intruders that may compromise the confidentiality of the PSKC.
13.2. PSKC Integrity 🧩
The PSKC provides means to guarantee the integrity of the information it contains through the use of digital signatures. It is RECOMMENDED that for best security practices, the digital signature of the container encompasses the entire PSKC. This provides assurances for the integrity of all attributes. It also allows verification of the integrity of a given PSKC even after the container is delivered through the communication channel to the target perimeter and channel message integrity check is no longer possible.
13.3. PSKC Authenticity 🪪
The digital signature of the PSKC is the primary way of showing its authenticity. The recipient of the container SHOULD use the public key associated with the signature to assert the authenticity of the sender by tracing it back to a pre-loaded public key or certificate. Note that the digital signature of the PSKC can be checked even after the container has been delivered through the secure channel of communication.
Authenticity guarantee may be provided by [TLS] or [IPsec]. However, no authenticity verification is possible once the container is delivered at the recipient end. Since the TLS endpoints could differ from the key provisioning endpoints, this solution is weaker than the previous solution that relies on a digital signature of the PSKC.
14. Contributors 🫶
We would like Hannes Tschofenig for his text contributions to this document.
15. Acknowledgements ✨
Okay bestie, huge thank-you hugs to everyone who gave feedback on this doc 🫶: Apostol Vassilev, Shuh Chang, Jon Martinson, Siddhart Bajaj, Stu Vaeth, Kevin Lewis, Philip Hallam-Baker, Andrea Doherty, Magnus Nystrom, Tim Moses, Anders Rundgren, Sean Turner, and especially Robert Philpott 💜. Robert is literally the MVP 👑.
Sean Turner gets an extra shoutout for his review in January 2009 🌸. Anders Rundgren also deserves a spotlight 🔥. He kicked off the discussion about which encryption algorithms to pick (KW-AES-128 vs. AES-128-CBC) and gave input on the keyed message digest computation. Iconic behaviour, honestly 💅.
This work is built on earlier work from the members of OATH (Initiative for Open AuTHentication), see [OATH] 🦋. The goal was a format that anyone in the technical community can freely distribute, and that's giving generous energy ✨.
16. References
16.1. Normative References
Here are the normative references. These are the ones you really need to read, no skipping 🧚.
[FIPS197] National Institute of Standards, "FIPS Pub 197: Advanced
Encryption Standard (AES)", November 2001.
[HOTP] M'Raihi, D., Bellare, M., Hoornaert, F., Naccache, D., and
O. Ranen, "HOTP: An HMAC-Based One-Time Password
Algorithm", RFC 4226, December 2005.
[IANAPENREG]
IANA, "Private Enterprise Numbers", <http://www.iana.org>.
[ISOIEC7812]
ISO, "ISO/IEC 7812-1:2006 Identification cards --
Identification of issuers -- Part 1: Numbering system",
October 2006, <http://www.iso.org/iso/iso_catalogue/
catalogue_tc/catalogue_detail.htm?csnumber=39698>.
[OATHMAN] OATH, "List of OATH Manufacturer Prefixes (omp)",
April 2009,
<http://www.openauthentication.org/oath-id/prefixes/>.
[PKCS5] RSA Laboratories, "PKCS #5: Password-Based Cryptography
Standard", Version 2.0, March 1999,
<http://www.rsasecurity.com/rsalabs/pkcs/>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media
Types", RFC 3023, January 2001.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
January 2004.
[RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and
Registration Procedures", BCP 13, RFC 4288, December 2005.
[RFC4514] Zeilenga, K., "Lightweight Directory Access Protocol
(LDAP): String Representation of Distinguished Names",
RFC 4514, June 2006.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, October 2006.
[RFC5646] Phillips, A. and M. Davis, "Tags for Identifying
Languages", BCP 47, RFC 5646, September 2009.
[RFC5649] Housley, R. and M. Dworkin, "Advanced Encryption Standard
(AES) Key Wrap with Padding Algorithm", RFC 5649,
September 2009.
[SP800-67]
National Institute of Standards, "NIST Special Publication
800-67 Version 1.1: Recommendation for the Triple Data
Encryption Algorithm (TDEA) Block Cipher", NIST Special
Publication 800-67, May 2008.
[W3C.REC-xmlschema-2-20041028]
Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes
Second Edition", World Wide Web Consortium
Recommendation REC-xmlschema-2-20041028, October 2004,
<http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>.
[XMLDSIG] Solo, D., Reagle, J., and D. Eastlake, "XML-Signature
Syntax and Processing", World Wide Web Consortium
FirstEdition REC-xmldsig-core-20020212, February 2002,
<http://www.w3.org/TR/2002/REC-xmldsig-core-20020212>.
[XMLENC] Eastlake, D., "XML Encryption Syntax and Processing.",
W3C Recommendation, December 2002,
<http://www.w3.org/TR/xmlenc-core/>.
[XMLENC11]
Reagle, J. and D. Eastlake, "XML Encryption Syntax and
Processing Version 1.1", World Wide Web Consortium WD WD-
xmlenc-core1-20090730, July 2009,
<http://www.w3.org/TR/2009/WD-xmlenc-core1-20090730>.16.2. Informative References
These ones are just helpful background reading, bestie 📚🎀.
[CAP] MasterCard International, "Chip Authentication Program
Functional Architecture", September 2004.
[IPsec] Kent, S. and K. Seo, "Security Architecture for the
Internet Protocol", RFC 4301, December 2005.
[NIST800-57]
Barker, E., Barker, W., Burr, W., Polk, W., and M. Smid,
"NIST Special Publication 800-57, Recommendation for Key
Management Part 1: General (Revised)", NIST Special
Publication 800-57, March 2007.
[OATH] "Initiative for Open AuTHentication",
<http://www.openauthentication.org>.
[PSKC-ALGORITHM-PROFILES]
Hoyer, P., Pei, M., Machani, S., and A. Doherty,
"Additional Portable Symmetric Key Container (PSKC)
Algorithm Profiles", Work in Progress, May 2010.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008.
[TLS] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, August 2008.
[XMLNS] Hollander, D., Bray, T., and A. Layman, "Namespaces in
XML", World Wide Web Consortium FirstEdition REC-xml-
names-19990114, January 1999,
<http://www.w3.org/TR/1999/REC-xml-names-19990114>.Appendix A. Use Cases 🌈
This appendix is a big list of real-life use cases that inspired the whole spec 💖. The requirements from these use cases were used to derive the main requirement that drove the design, and those requirements are covered in the next section. It also helps you see where this spec actually fits in the real world 🍓.
A.1. Online Use Cases
Here we look at use cases for provisioning keys over an online provisioning protocol 🌐.
A.1.1. Transport of Keys from Server to Cryptographic Module
For example, a mobile device user wants a symmetric key to use with a cryptographic module on their phone 📱. The cryptographic module from vendor A starts the provisioning process against a provisioning system from vendor B, using a standards-based provisioning protocol. The provisioning entity delivers one or more keys in a standard format that the mobile device can process ✨.
Another version: instead of the user's phone, the key gets provisioned into the user's soft token application on a laptop, through a network-based online protocol 💻. Same deal as before. The provisioning system delivers a key in a standard format that the soft token on the PC can process 🦋.
And one more: the end user or the key issuer wants to update or configure an existing key in the cryptographic module, so they request a replacement key container 🔁. The container may or may not include a new key. It may also include new or updated key attributes, such as a new counter value in HOTP key case, a modified response format or length, a new friendly name, etc. Main character energy 👑.
A.1.2. Transport of Keys from Cryptographic Module to Cryptographic Module
Say a user wants to move a key from one cryptographic module to another 🔑. There could be two cryptographic modules, one on a computer and one on a mobile phone, and the user wants to move a key from the computer to the phone 💅. The user can export the key and related data in a standard format, and then the other cryptographic module can import it 🫶.
A.1.3. Transport of Keys from Cryptographic Module to Server
Now picture this: a user wants to activate and use a new key and its related data against a validation system that doesn't know about this key yet 🙈. The key might be built into the cryptographic module, like a Secure Digital (SD) card or a USB drive, which the user bought at the local electronics store 🛍️. Along with the module, the user might get the key on a CD or a floppy, in a standard format 💿. The user can then upload it over a secure online channel, or import the key and related data into the new validation system, and start using the key 🎉.
A.1.4. Server-to-Server Bulk Import/Export of Keys
Sometimes a key management system needs to import or export keys in bulk, from one entity to another 📦.
For example, instead of importing keys from a manufacturer using a file, a validation server can download the keys using an online protocol ⬇️. The keys can be downloaded in a standard format that a validation system can process 💜.
In a variation of this, an Over-The-Air (OTA) key provisioning gateway, which provisions keys to mobile phones, can get key material from a key issuer through an online protocol 📡. The keys are delivered in a standard format that the key provisioning gateway can process, and then get sent on to the end user's mobile phone 📲.
A.2. Offline Use Cases
This section covers use cases for moving keys from one system to another offline, using some kind of export and import model 💾.
A.2.1. Server-to-Server Bulk Import/Export of Keys
For example, cryptographic modules such as OTP authentication tokens may have their symmetric keys initialized in bulk during manufacturing. That means copies of the keys and algorithm data need to be loaded into the authentication system through a file on portable media 💿. The manufacturer provides the keys and related data as a file with records in a standard format, typically on a CD 🌸. Note that the token manufacturer and the vendor for the validation system may be the same or different 🤷♀️. Some crypto modules allow local PIN management (the device has a PIN pad), so random initial PINs set at manufacturing should be transmitted together with the respective keys they protect 🔐.
Another example: an enterprise wants to port keys and related data from an existing validation system A into a different validation system B 🚚. The existing system gives the enterprise a way to export keys and related data (for example, for OTP authentication tokens) in a standard format 📤. Since the OTP tokens are in that standard format, the enterprise can import the token records into the new validation system B and keep using the existing tokens 🥳. Note that the vendors for the two validation systems may be the same or different 🦋.
Appendix B. Requirements ✨
okay so this section is the wishlist 🎀 that the whole format was built around, and a bunch of these came straight out of the use cases we just went through 💅. Each requirement gets a little label (R1, R2, and so on), and the BCP 14 key words tell you how strict it is. 🫶
R1: The format MUST support the transport of multiple types of symmetric keys and related attributes for algorithms including HOTP, other OTP, Challenge/Response, etc. 🔥
R2: The format MUST handle the symmetric key itself as well of attributes that are typically associated with symmetric keys. Some of these attributes may be:
- Unique Key Identifier 🪪
- Issuer information 🏢
- Algorithm ID 🧮
- Algorithm mode 🎛️
- Issuer Name 🏷️
- Key friendly name 💖
- Event counter value (moving factor for OTP algorithms) 🔢
- Time value ⏰
R3: The format SHOULD support both offline and online scenarios. That is, it should be serializable to a file as well as it should be possible to use this format in online provisioning protocols. 📁🌐
R4: The format SHOULD allow bulk representation of symmetric keys. 📦
R5: The format SHOULD allow bulk representation of PINs related to specific keys. 🔐
R6: The format SHOULD be portable to various platforms. Furthermore, it SHOULD be computationally efficient to process. 🧚
R7: The format MUST provide an appropriate level of security in terms of data encryption and data integrity. 🛡️
R8: For online scenarios, the format SHOULD NOT rely on transport layer security (e.g., Secure Socket Layer/Transport Layer Security (SSL/TLS)) for core security requirements. 🙈
R9: The format SHOULD be extensible. It SHOULD enable extension points allowing vendors to specify additional attributes in the future. 🌸
R10: The format SHOULD allow for distribution of key derivation data without the actual symmetric key itself. This is to support symmetric key management schemes that rely on key derivation algorithms based on a pre-placed master key. The key derivation data typically consists of a reference to the key, rather than the key value itself. 🦋
R11: The format SHOULD allow for additional life cycle management operations such as counter resynchronization. Such processes require confidentiality between client and server, thus could use a common secure container format, without the transfer of key material. 🍓
R12: The format MUST support the use of pre-shared symmetric keys to ensure confidentiality of sensitive data elements. 👑
R13: The format MUST support a password-based encryption (PBE) [PKCS5] scheme to ensure security of sensitive data elements. This is a widely used method for various provisioning scenarios. 💜
R14: The format SHOULD support asymmetric encryption algorithms such as RSA to ensure end-to-end security of sensitive data elements. This is to support scenarios where a pre-set shared key encryption key is difficult to use. 🌈
Authors' Addresses 💌
Philip Hoyer ActivIdentity, Inc. 117 Waterloo Road London, SE1 8UL UK
Phone: +44 (0) 20 7960 0220 EMail: phoyer@actividentity.com
Mingliang Pei VeriSign, Inc. 487 E. Middlefield Road Mountain View, CA 94043 USA
Phone: +1 650 426 5173 EMail: mpei@verisign.com
Salah Machani Diversinet, Inc. 2225 Sheppard Avenue East Suite 1801 Toronto, Ontario M2J 5C2 Canada
Phone: +1 416 756 2324 Ext. 321 EMail: smachani@diversinet.com
bestie that's the whole RFC 🎉 the authors are the squad who wrote it, and you can reach them at the emails above if you're ever curious 🫶✨
📦 where this page comes from
- ietf: rfc6030 2010-10
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms