| TOC |
|
This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress.”
The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.
This Internet-Draft will expire on April 27, 2010.
Copyright (c) 2009 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents in effect on the date of publication of this document (http://trustee.ietf.org/license-info). Please review these documents carefully, as they describe your rights and restrictions with respect to this document.
This document specifies a symmetric key format for transport and provisioning of symmetric keys to different types of crypto modules. For example, One Time Password (OTP) shared secrets or symmetric cryptographic keys to strong authentication devices. A standard key transport format enables enterprises to deploy best-of-breed solutions combining components from different vendors into the same infrastructure.
1.
Introduction
1.1.
Key Words
1.2.
Versions
1.3.
Namespace Identifiers
1.3.1.
Defined Identifiers
1.3.2.
Referenced Identifiers
2.
Terminology
3.
Portable Key Container Entities Overview and Relationships
4.
<KeyContainer> Element: The Basics
4.1.
<Key>: Embedding Keying Material and Key Related Information
4.2.
Transmission of supplementary Information
4.2.1.
<DeviceInfo> Element: Unique Device Identification
4.2.2.
<CryptoModuleInfo> Element: CryptoModule Identification
4.2.3.
<UserId> Element: User Identification
4.2.4.
<AlgorithmParameters> Element: Supplementary Information for OTP and CR Algorithms
4.3.
Transmission of Key Derivation Values
5.
Key policy - transmission of key usage policies and key PIN protection policy
6.
Key protection methods
6.1.
Encryption based on Pre-Shared Keys
6.1.1.
MAC Method
6.2.
Encryption based on Passphrase-based Keys
6.3.
Encryption based on Asymmetric Keys
6.4.
Padding of encrypted values for non-padded encryption algorithms
7.
Digital Signature
8.
Bulk Provisioning
9.
Extensibility
10.
PSKC Algorithm Profile
10.1.
HOTP
10.2.
KEYPROV-PIN
11.
XML Schema
12.
IANA Considerations
12.1.
Content-type registration for 'application/pskc+xml'
12.2.
XML Schema Registration
12.3.
URN Sub-Namespace Registration
12.4.
PSKC Algorithm Profile Registry
12.5.
PSKC Version Registry
12.6.
Key Usage Registry
13.
Security Considerations
13.1.
Payload confidentiality
13.2.
Payload integrity
13.3.
Payload authenticity
14.
Contributors
15.
Acknowledgements
16.
References
16.1.
Normative References
16.2.
Informative References
Appendix A.
Use Cases
A.1.
Online Use Cases
A.1.1.
Transport of keys from Server to Cryptographic Module
A.1.2.
Transport of keys from Cryptographic Module to Cryptographic Module
A.1.3.
Transport of keys from Cryptographic Module to Server
A.1.4.
Server to server Bulk import/export of keys
A.2.
Offline Use Cases
A.2.1.
Server to server Bulk import/export of keys
Appendix B.
Requirements
§
Authors' Addresses
| TOC |
With increasing use of symmetric key based systems, such as encryption of data at rest or systems used for strong authentication such as those based on one-time-password (OTP) and challenge response (CR) mechanisms, there is a need for vendor interoperability and a standard format for importing and exporting (provisioning) symmetric keys. Traditionally, for example, vendors of authentication servers and service providers have used proprietary formats for importing and exporting these keys into their systems, thus making it hard to use tokens from vendor "Foo" with a server from vendor "Bar".
This document defines a standardized XML-based key container, called Portable Symmetric Key Container (PSKC), for transporting symmetric keys and key related meta data. The document also specifies the information elements that may be required when the symmetric key is utilized for specific purposes, such as the initial counter in the MAC-Based One Time Password (HOTP) [HOTP] (MRaihi, D., Bellare, M., Hoornaert, F., Naccache, D., and O. Ranen, “HOTP: An HMAC-Based One Time Password Algorithm,” December 2005.) algorithm. It also requests the creation of an IANA registry for algorithm profiles where algorithms, their related meta-data and PSKC transmission profile can be recorded for centralised standardised reference.
| TOC |
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] (, “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.).
| TOC |
There is a provision made in the syntax for an explicit version number. Only version "1.0" is currently specified.
| TOC |
This document uses Uniform Resource Identifiers [RFC2396] (Berners-Lee, T., Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifiers (URI): Generic Syntax,” August 1998.) to identify resources, algorithms, and semantics.
| TOC |
The XML namespace [XMLNS] (, “Namespaces in XML,” January 1999.) URI for Version 1.0 of PSKC is:
xmlns:pskc="urn:ietf:params:xml:ns:keyprov:pskc"
References to qualified elements in the PSKC schema defined herein use the prefix "pskc".
| TOC |
The PSKC syntax presented in this document relies on algorithm identifiers and elements defined in the XML Signature [XMLDSIG] (Eastlake, D., “XML-Signature Syntax and Processing,” February 2002.) namespace:
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
References to the XML Signature namespace are represented by the prefix "ds".
PSKC also relies on algorithm identifiers and elements defined in the XML Encryption [XMLENC] (Eastlake, D., “XML Encryption Syntax and Processing.,” December 2002.) namespace:
xmlns:xenc="http://www.w3.org/2001/04/xmlenc#"
References to the XML Encryption namespace are represented by the prefix "xenc".
When protecting keys in transport with passphrase-based keys, PSKC also relies on the derived key element defined in the XML Encryption Version 1.1 [XMLENC11] (Eastlake, D., “XML Encryption Syntax and Processing Version 1.1.,” July 2009.) namespace:
xmlns:xenc11="http://www.w3.org/2009/xmlenc11#""
References to the XML Encryption Version 1.1 namespace are represented by the prefix "xenc11".
When protecting keys in transport with passphrase-based keys, PSKC also relies on algorithm identifiers and elements defined in the PKCS#5 [PKCS5] (RSA Laboratories, “PKCS #5: Password-Based Cryptography Standard,” March 1999.) namespace:
xmlns:pkcs5= "http://www.rsasecurity.com/rsalabs/pkcs/schemas/pkcs-5v2-0#"
References to the PKCS#5 namespace are represented by the prefix "pkcs5".
| TOC |
NOTE: In subsequent sections of the document we highlight **mandatory** XML elements and attributes. Optional elements and attributes are not explicitly indicated, i.e., if it does not say mandatory it is optional.
| TOC |
The portable key container is based on an XML schema definition and contains the following main conceptual entities:
Figure 1 shows the high-level structure of the PSKC data elements.
-----------------
| 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 |
| TOC |
In its most basic form, a PSKC document uses the top-level element <KeyContainer> and a single <KeyPackage> element to carry key information.
The following example shows such a simple PSKC document. We will use it to describe
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 Example |
The attributes of the <KeyContainer> element have the following semantics:
- 'Version:'
- The 'Version' attribute is used to identify the version of the PSKC schema version. This specification defines the initial version ("1.0") of the PSKC schema. This attribute MUST be included.
- 'Id:'
- The 'Id' attribute carries a unique identifier for the container. As such, it helps to identify a specific key container in cases when multiple containers are embedded in larger xml documents.
| TOC |
The following attributes of the <Key> element MUST be included at a minimum:
- 'Id':
- This attribute carries a globally unique identifier for the symmetric key. The identifier is defined as a string of alphanumeric characters.
- 'Algorithm':
- This attribute contains a unique identifier for the PSKC algorithm profile. This profile associates specific semantics to the elements and attributes contained in the <Key> element. This document describes profiles for open standards algorithms in Section 10 (PSKC Algorithm Profile). Additional profiles are defined in the following information draft [PSKC‑ALGORITHM‑PROFILES] (Hoyer, P., Pei, M., Machani, S., and A. Doherty, “Additional Portable Symmetric Key Container (PSKC) Algorithm Profiles,” December 2008.).
The <Key> element has a number of optional child elements. An initial set is described below:
- <Issuer>:
- This element represents the name of the party that issued the key. For example, a bank "Foobar Bank Inc." issuing hardware tokens to their retail banking users may set this element to "Foobar Bank Inc.".
- <FriendlyName>:
- A human readable name for the secret key for easier reference. This element serves informational purposes only.
- <AlgorithmParameters>:
- This element carries parameters that influence the result of the algorithmic computation, for example response truncation and format in OTP and CR algorithms. A more detailed discussion of the element can be found in Section 4.2.4 (<AlgorithmParameters> Element: Supplementary Information for OTP and CR Algorithms).
- <Data>:
- This element carries data about and related to the key. The following child elements are defined for the <Data> element:
All the elements listed above (and those defined in the future) obey a simple structure in that they MUST support child elements to convey the data value in either plaintext or encrypted format:
- <Secret>:
- This element carries the value of the key itself in a binary representation.
- <Counter>:
- This element contains the event counter for event based OTP algorithms.
- <Time>:
- This element contains the time for time based OTP algorithms. (If time interval is used, this element carries the number of time intervals passed from a specific start point, normally algorithm dependent).
- <TimeInterval>:
- This element carries the time interval value for time based OTP algorithms.
- <TimeDrift>:
- This element contains the device clock drift value for time-based OTP algorithms. The value indicates the number of seconds that the device clock may drift each day.
- Plaintext:
- The <PlainValue> element carries plaintext value that is typed, for example to xs:integer.
- Encrypted:
- The <EncryptedValue> element carries encrypted value.
- ValueMAC:
- The <ValueMAC> element is populated with a MAC generated from the encrypted value in case the encryption algorithm does not support integrity checks. The example shown at Figure 2 (Basic PSKC Key Container Example) illustrates the usage of the <Data> element with two child elements, namely <Secret> and <Counter>. Both elements carry plaintext value within the <PlainValue> child element.
| TOC |
A PSKC document can contain a number of additional information regarding device
identification, cryptomodule identification, user identification and parameters for usage with
OTP and CR algorithms. The following example, see Figure 3 (PSKC Key Container Example with Supplementary Data), is used as a reference for the subsequent sub-sections.
<?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>
<UserId>UID=jsmith,DC=example-bank,DC=net</UserId>
<AlgorithmParameters>
<ResponseFormat Length="8" Encoding="DECIMAL"/>
</AlgorithmParameters>
<Data>
<Secret>
<PlainValue>MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=
</PlainValue>
</Secret>
<Counter>
<PlainValue>0</PlainValue>
</Counter>
</Data>
</Key>
</KeyPackage>
</KeyContainer>
| Figure 3: PSKC Key Container Example with Supplementary Data |
| TOC |
The <DeviceInfo> element uniquely identifies the device the <KeyPackage> is provisioned to. Since devices can come in different form factors, such as hardware tokens, smart-cards, soft tokens in a mobile phone or as a PC, this element allows different child element combinations to be used. When combined, the values of the child elements MUST uniquely identify the device. For example, for hardware tokens the combination of <SerialNo> and <Manufacturer> elements uniquely identifies a device but the <SerialNo> element alone is insufficient since two different token manufacturers might issue devices with the same serial number (similar to the Issuer Distinguished Name and serial number of a certificate).
The <DeviceInfo> element has the following child elements:
- <Manufacturer>:
- This element indicates the manufacturer of the device.
- <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 devices with the same serial number that are 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 IMEI for the phone, or an identifier for a class of identifiers, e.g., those for which the keys are protected by a 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 in UTC form with no timezone component. Implementations SHOULD NOT rely on time resolution finer than milliseconds and MUST NOT generate time instants that specify leap seconds.
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.
| TOC |
The <CryptoModuleInfo> element identifies the cryptographic module to which the symmetric keys are or have been provisioned to. This allows the identification of the specific 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 proivisioned.
| TOC |
The <UserId> element identifies the user using a distinguished name, as defined in [RFC4514] (Zeilenga, K., “Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names,” June 2006.). 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, i.e., 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, namely as a child element of the <Key> element where it indicates the user with whom the key is associated with and as a child element of the <DeviceInfo> element where it indicates the user the device is associated with.
| TOC |
The <AlgorithmParameters> element is a child element of the <Key> element and this document defines two child elements: <ChallengeFormat> and <ResponseFormat>
- <ChallengeFormat>:
The <ChallengeFormat> element defines the characteristics of the challenge in a CR usage scenario whereby the following attributes are defined:
- 'Encoding':
- This attribute, which MUST be included, defines the encoding of the challenge accepted by the device and MUST be one of the following values:
- DECIMAL
- Only numerical digits
- HEXADECIMAL
- Hexadecimal response
- ALPHANUMERIC
- All letters and numbers (case sensitive)
- BASE64
- Base 64 encoded
- BINARY
- Binary data
- 'CheckDigit':
- This attribute indicates whether a device needs to check the appended Luhn check digit, as defined in [LUHN] (Luhn, H., “Luhn algorithm,” August 1960.), contained in a challenge. This is only valid if the 'Encoding' attribute is 'DECIMAL'. A value of TRUE indicates that the device will check the appended Luhn check digit in a provided challenge. A value of FALSE indicates that the device will not check the appended Luhn check digit in the challenge.
- 'Min':
- This attribute defines the minimum size of the challenge accepted by the device for CR mode and MUST be included. If the 'Encoding' attribute is 'DECIMAL', 'HEXADECIMAL' or 'ALPHANUMERIC' this value indicates the minimum number of digits/characters. If the 'Encoding' attribute is 'BASE64' or 'BINARY', this value indicates the minimum number of bytes of the unencoded value.
- 'Max':
- This attribute defines the maximum size of the challenge accepted by the device for CR mode and MUST be included. If the 'Encoding' attribute is 'DECIMAL', 'HEXADECIMAL' or 'ALPHANUMERIC' this value indicates the maximum number of digits/characters. If the 'Encoding' attribute is 'BASE64' or 'BINARY', this value indicates the maximum number of bytes of the unencoded value.
- <ResponseFormat>:
The <ResponseFormat> element defines the characteristics of the result of a computation and defines the format of the OTP or the response to a challenge. For cases where the key is a PIN value, this element contains the format of the PIN itself (e.g., DECIMAL, length 4 for a 4 digit PIN). The following attributes are defined:
- 'Encoding':
- This attribute defines the encoding of the response generated by the device, it MUST be included and MUST be one of the following values: DECIMAL, HEXADECIMAL, ALPHANUMERIC, BASE64, or BINARY.
- 'CheckDigit':
- This attribute indicates whether the device needs to append a Luhn check digit, as defined in [LUHN] (Luhn, H., “Luhn algorithm,” August 1960.), to the response. This is only valid if the 'Encoding' attribute is 'DECIMAL'. If the value is TRUE then the device will append a Luhn check digit to the response. If the value is FALSE, then the device will not append a Luhn check digit to the response.
- 'Length':
- This attribute defines the length of the response generated by the device and MUST be included. If the 'Encoding' attribute is 'DECIMAL', 'HEXADECIMAL' or 'ALPHANUMERIC' this value indicates the number of digits/characters. If the 'Encoding' attribute is 'BASE64' or 'BINARY', this value indicates the number of bytes of the unencoded value.
| TOC |
<KeyProfileId> element, which is a child element of the <Key> element, carries a unique identifier used between the sending and receiving parties to establish a set of key attribute values that are not transmitted within the container but agreed between the two parties out of band. This element will then represent the unique reference to a set of key attribute values. (For example, a smart card application personalisation profile id related to attributes present on a smart card application that have influence when computing a response.).
For example, in the case of MasterCard's Chip Authentication Program [CAP] (MasterCard International, “Chip Authentication Program Functional Architecture,” September 2004.), sending and receiving party would agree that KeyProfileId='1' represents a certain set of values (e.g., Internet Authentication Flag IAF set to a specific value). During transmission of the KeyContainer, these values would not be transmitted as key attributes but only referred to via the <KeyProfileId> element set to the specific agreed profile (in this case '1'). The receiving party can then associate all relevant key attributes contained in the out of band agreed profile with the imported keys. Often this methodology is used between a manufacturing service, run by company A and the validation service run by company B, to avoid repeated transmission of the same set of key attribute values.
The <KeyReference> element contains a reference to an external key to be used with a key derivation scheme and no specific key value (secret) is transported but only the reference to the external master key is used (e.g., the 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 a HOTP key via key derivation values |
| TOC |
This section illustrates the functionality of the <Policy> element within PSKC that allows policy to be attached to a key and its related meta data. This element is a child element of the <Key> element.
If the <Policy> element contains child elements or values within elements/attributes that are not understood by the recipient of the PSKC document then the recipient MUST assume that key usage is not permitted. This statement ensures that the lack of understanding of certain extensions does not lead to unintended key usage.
We will start our description with an example that expands the example shown in Figure 3 (PSKC Key Container Example with Supplementary Data).
<?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:
- <StartDate> and <ExpiryDate>:
- These two elements denote the validity period of a key. It MUST be ensured that the key is only used between the start and the end date (inclusive). The value MUST be expressed in UTC form, with no time zone component. Implementations SHOULD NOT rely on time resolution finer than milliseconds and 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 having received it.. When this element is omitted then there is no restriction regarding the number of 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. Currently, the following tokens are registered by this document:
The element MAY also be repeated to allow several key usages to be expressed. When this element is absent then no key usage constraint is assumed, i.e., the key MAY be utilized for every usage.
- 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 vice versa of Integrity)
- 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] (Barker, E., Barker, W., Burr, W., Polk, W., and M. Smid, “NIST Special Publication 800-57, Recommendation for Key Management – Part 1: General (Revised),” March 2007.)).
- 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] (Barker, E., Barker, W., Burr, W., Polk, W., and M. Smid, “NIST Special Publication 800-57, Recommendation for Key Management – Part 1: General (Revised),” March 2007.)).
- <PINPolicy>:
- The <PINPolicy> element allows policy about the PIN usage to be associated with the key. The following attributes are specified:
If the 'PinUsageMode' attribute is set to "Local" then the device MUST enforce the restriction indicated in the 'MaxFailedAttempts', 'MinLength', 'MaxLength' and 'PINEncoding' attribute, otherwise it MUST be enforced on the server side.
- 'PINKeyId':
- This attribute contains the unique key id of the key held within this container that contains the value of the PIN that protects the key.
- 'PINUsageMode':
- This mandatory attribute indicates the way the PIN is used during the usage of the key. The following values are defined:
- Local:
- This value indicates that the PIN is checked locally on the device before allowing the key to be used in executing the algorithm.
- Prepend:
- This value indicates that the PIN is prepended to the algorithm response hence it MUST be checked by the party validating the response.
- Append:
- This value indicates that the PIN is appended to the algorithm response hence it MUST be checked by the party validating the response.
- Algorithmic:
- This value indicates that 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.
- '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 the 'PINFormat' attribute is 'DECIMAL', 'HEXADECIMAL' or 'ALPHANUMERIC' this value indicates the number of digits/characters. If the 'PINFormat' attribute is 'BASE64' or 'BINARY', 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 the 'PINFormat' attribute is 'DECIMAL', 'HEXADECIMAL' or 'ALPHANUMERIC' this value indicates the number of digits/characters. If the 'PINFormat' attribute is 'BASE64' or 'BINARY', 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, or BINARY.
| TOC |
With the functionality described in the previous sections, information related to keys had to be transmitted in clear text. With the help of the <EncryptionKey> element, which is a child element of the <KeyContainer> element, it is possible to encrypt keys and associated information. The level of encryption is applied to the value of individual elements and the applied encryption algorithm 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 are used that make use of Initialisation Vectors (IV), for example AES128-CBC, then 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] (Eastlake, D., “XML Encryption Syntax and Processing.,” December 2002.).
| TOC |
Figure 6 (AES-128-CBC Encrypted Pre-Shared Secret Key with HMAC-SHA1) shows an example that illustrates the encryption of the content of the <Secret> element using AES128-CBC and PKCS5 Padding. The plaintext value of <Secret> is '3132333435363738393031323334353637383930'. The name of the pre-shared secret is "Example-Key1", as set in the <KeyName> element (which is a child element of the <EncryptionKey> element). The value of the encryption key used is '12345678901234567890123456789012'.
The IV for the MAC key is '11223344556677889900112233445566' and the IV for the HOTP key is '000102030405060708090a0b0c0d0e0f'.
As AES128-CBC does not provide integrity checks a keyed MAC is applied to the encrypted value using a MAC key and a MAC algorithm as declared in the <MACMethod> element (in our example "http://www.w3.org/2000/09/xmldsig#hmac-sha1" is used as the algorithm and the value of the MAC key is randomly generated, in our case '1122334455667788990011223344556677889900', and encrypted with the above encryption key). The result of the keyed MAC computation is placed in 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>aSRlEG1agUo0CS2dt/OvIAqQ6Co=
</ValueMAC>
</Secret>
<Counter>
<PlainValue>0</PlainValue>
</Counter>
</Data>
</Key>
</KeyPackage>
</KeyContainer>
| Figure 6: AES-128-CBC Encrypted Pre-Shared Secret Key with HMAC-SHA1 |
When 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. When the encryption method uses a CBC mode that requires 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 (with the URI of http://www.w3.org/2001/04/xmlenc#aes128-cbc) and KW-AES128 (with the URI of http://www.w3.org/2001/04/xmlenc#kw-aes128). Please note that KW-AES128 requires that the key to be protected must be a multiple of 8 bytes in length. Hence, if keys of a different length have to be protected then the usage of the key wrap algorithm with padding, as described in [AESKWPAD] (Housley, R. and M. Dworkin, “Advanced Encryption Standard (AES) Key Wrap with Padding Algorithm,” March 2009.) is RECOMMENDED. Some of the encryption algorithms that can optionally be implemented are:
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-camellia256
| TOC |
When algorithms without integrity checks are used, such as 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, a pre-shared one between the receiver and the sender, or one set by an application protocol that uses KeyContainer. It is recommended that a sender generates a random MAC key. When the sender generates such a random MAC key, the MAC key material MUST be encrypted with the same encryption key specified in <EncryptionKey> element of the key container. The encryption method and encrypted value MUST be set respectively in the <EncryptionMethod> element and the <CipherData> element of the <MACKey> element in 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 the HMAC-SHA1 (with the URI of '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-sha512
| TOC |
Figure 7 (Example of a PSKC Document using Encryption based on Passphrase-based Keys) shows an example that illustrates the encryption of the content of the <Secret> element using passphrase based key derivation (PBKDF2) to derive the encryption key as defined in [PKCS5] (RSA Laboratories, “PKCS #5: Password-Based Cryptography Standard,” March 1999.). When using passphrase based key derivation, the <DerivedKey> element defined in XML Encryption v1.1 [XMLENC11] (Eastlake, D., “XML Encryption Syntax and Processing Version 1.1.,” July 2009.) MUST be used to specify the passphrased-based key. A <DerivedKey> element is set as the child element of <EncryptionKey> element of the key container.
The <DerivedKey> element is used to specify the key derivation function and related parameters. 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 <EncryptionMethod> element used inside the encrypted data elements.
When PBKDF2 is used, the attribute "Algorithm" of the element <xenc11:KeyDerivationMethod> MUST be set to the URI 'http://www.rsasecurity.com/rsalabs/pkcs/schemas/pkcs-5#pbkdf2'. The element <xenc11:KeyDerivationMethod> MUST include the <PBKDF2-params> child element to indicate the PBKDF2 parameters, such as salt and iteration count.
When the encryption method uses a CBC mode that uses an explicit initialization vector (IV) other than a derived one, the IV MUST be passed by prepending it to the encrypted value.
In the example below, the following data is used.
- Password:
- qwerty
- Salt:
- 0x123eff3c4a72129c
- Iteration Count:
- 1000
- MAC Key:
- 0xbdaab8d648e850d25a3289364f7d7eaaf53ce581
- OTP Secret:
- 12345678901234567890
The derived encryption key is "0x651e63cd57008476af1ff6422cd02e41". The initialization vector (IV) is "0xa13be8f92db69ec992d99fd1b5ca05f0". This key is also used to encrypt the randomly chosen MAC key. A different IV can be used, say, "0xd864d39cbc0cdc8e1ee483b9164b9fa0" in the example. The encryption with algorithm "AES-128-CBC" follows the specification defined in [XMLENC] (Eastlake, D., “XML Encryption Syntax and Processing.,” December 2002.).
<?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>
2GTTnLwM3I4e5IO5FkufoNhk05y8DNyOHuSDuRZLn6DhIjoTY/dX4SkUAbQ
SWJblA7Dzi031L6FNnUrcjsGGcQ==
</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 |
| TOC |
When using asymmetric keys to encrypt child elements of the <Data> element information about the certificate being used MUST be stated in the <X509Data> element, which is a child element of the <EncryptionKey> element. The encryption algorithm MUST be indicated in the 'Algorithm' attribute of the <EncryptionMethod> element. In the example shown in Figure 8 (Example of a PSKC Document using Encryption based on Asymmetric Keys) the algorithm is set to "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'.
Some of the asymmetric encryption algorithms that can optionally be implemented are:
Algorithm | Uniform Resource Locator (URL) ------------------+------------------------------------------------- RSA-OAEP-MGF1P | http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p
| TOC |
Padding of encrypted values (for example the key secret value) is required when key protection algorithms are used that do not support embedded padding and the value to be encrypted is not a multiple of the encryption algorithm cypher block length.
For example, when transmitting a HOTP key (20 bytes long) protected with the AES algorithm in CBC mode (8 byte block cypher), since 20 bytes are not a multiple of the 8 byte block length, padding is required.
In these cases, for systems implementing PSKC it is RECOMMENDED to pad the value before encryption using PKCS5 padding as described in [PKCS5] (RSA Laboratories, “PKCS #5: Password-Based Cryptography Standard,” March 1999.).
| TOC |
PSKC allows a digital signature to be added to the XML document, as a child element of the <KeyContainer> element. The description of the XML digital signature can be found in [XMLDSIG] (Eastlake, D., “XML-Signature Syntax and Processing,” February 2002.).
<?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 |
| TOC |
The functionality of bulk provisioning can be accomplished by repeating the <KeyPackage> element multiple times within the <KeyContainer> element indicating that multiple keys are provided to different devices or cryptomodules. The <EncryptionKey> element then applies to all <KeyPackage> elements. When provisioning multiple keys to the same device the <KeyPackage> element is repeated but the enclosed <DeviceInfo> element will contain the same sub elements that uniquely identify the single device.
Figure 10 (Bulk Provisioning Example) shows an example utilizing these capabilities.
<?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>
<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 |
| TOC |
This section lists a few common extension points provided by PSKC:
- New PSKC Version:
- Whenever it is necessary to define a new version of this document then a new version number has to be allocated to refer to the new specification version. The version number is carried inside the 'Algorithm' attribute, as described in Section 4 (<KeyContainer> Element: The Basics), and rules for extensibililty are defined in Section 12 (IANA Considerations).
- New XML Elements:
- The usage of the XML schema and the available extension points allows new XML elements to be added. Depending of type of XML elements different ways for extensibility are offered. In some places the <Extensions> element can be used and elsewhere the "<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>" XML extension point is utilized.
- New XML Attributes:
- The XML schema allows new XML attributes to be added where XML extension points have been defined (see "<xs:anyAttribute namespace="##other"/>" in Section 11 (XML Schema)).
- New PSKC Algorithm Profiles:
- This document defines two PSKC algorithm profiles, see Section 10 (PSKC Algorithm Profile). The following informational draft describes additional profiles [PSKC‑ALGORITHM‑PROFILES] (Hoyer, P., Pei, M., Machani, S., and A. Doherty, “Additional Portable Symmetric Key Container (PSKC) Algorithm Profiles,” December 2008.). Further PSKC algorithm profiles can be registered as described in Section 12.4 (PSKC Algorithm Profile Registry).
- Algorithm URIs:
- Section 6 (Key protection methods) defines how keys and related data can be protected. A number of algorithms can be used. The use of new algorithms can be used by pointing to a new algorithm URI.
- Policy:
- Section 5 (Key policy - transmission of key usage policies and key PIN protection policy) defines policies that can be attached to a key and keying related data. The <Policy> element is one such item that allows to restrict the use of the key to certain functions, such as "OTP usage only". Further values may be registered as described in Section 12 (IANA Considerations).
| TOC |
| TOC |
- Common Name:
- HOTP
- Class:
- OTP
- URN:
- urn:ietf:params:xml:ns:keyprov:pskc#hotp
- Algorithm Definition:
- http://www.ietf.org/rfc/rfc4226.txt
- Identifier Definition:
- (this RFC)
- Registrant Contact:
- IESG
- Profiling:
The <KeyPackage> element MUST be present and the <ResponseFormat> element, which is a child element of the <AlgorithmParameters> element, MUST be used to indicate the OTP length and the value format.
The <Counter> element (see Section 4.1 (<Key>: Embedding Keying Material and Key Related Information)) MUST be provided as meta data for the key.
The following additional constraints apply:
- The value of the <Secret> element MUST contain key material with a length of at least 16 octets (128 bits), if it is 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.
- The <PINPolicy> element MAY be present but the 'PINUsageMode' attribute cannot be set to "Algorithmic".
An example can be found in Figure 3 (PSKC Key Container Example with Supplementary Data).
| TOC |
- Common Name:
- KEYPROV-PIN
- Class:
- Symmetric static credential comparison
- URN:
- urn:ietf:params:xml:ns:keyprov:pskc#pin
- Algorithm Definition:
- (this document)
- Identifier Definition
- (this document)
- Registrant Contact:
- IESG
- Profiling:
The <Usage> element MAY be present but no attribute of the <Usage> element is required. The <ResponseFormat> element MAY be used to indicate the PIN value format.
The <Secret> element (see Section 4.1 (<Key>: Embedding Keying Material and Key Related Information)) MUST be provided.
See the example in Figure 5 (Non-Encrypted HOTP Secret Key protected by PIN)
| TOC |
This section defines the XML schema for PSKC.
<?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>
</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="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>
| TOC |
| TOC |
This specification requests the registration of a new MIME type according to the procedures of RFC 4288 [RFC4288] (Freed, N. and J. Klensin, “Media Type Specifications and Registration Procedures,” December 2005.) and guidelines in RFC 3023 [RFC3023] (Murata, M., St. Laurent, S., and D. Kohn, “XML Media Types,” January 2001.).
- MIME media type name:
- application
- MIME subtype name:
- pskc+xml
- Mandatory parameters:
- none
- 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] (Murata, M., St. Laurent, S., and D. Kohn, “XML Media Types,” January 2001.), Section 3.2.
- Security considerations:
- This content type is designed to carry PSKC protocol payloads.
- Interoperability considerations:
- None
- Published specification:
- RFCXXXX [NOTE TO IANA/RFC-EDITOR: Please replace XXXX with the RFC number of this specification.]
- Applications which use this media type:
- This MIME 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 for further information:
- Philip Hoyer, Philip.Hoyer@actividentity.com
- Intended usage:
- LIMITED USE
- 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>
| TOC |
This section registers an XML schema as per the guidelines in [RFC3688] (Mealling, M., “The IETF XML Registry,” January 2004.).
- URI:
- urn:ietf:params:xml:ns: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 (XML Schema). Its first line is
and its last line is<?xml version="1.0" encoding="UTF-8"?></xs:schema>
| TOC |
This section registers a new XML namespace, "urn:ietf:params:xml:ns:keyprov:pskc", per the guidelines in [RFC3688] (Mealling, M., “The IETF XML Registry,” January 2004.).
- 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="[URL of published RFC]">RFCXXXX [NOTE TO IANA/RFC-EDITOR: Please replace XXXX with the RFC number of this specification.]</a>.</p> </body> </html> END
| TOC |
This specification requests the creation of a new IANA registry for PSKC algorithm profiles in accordance with the principles set out in RFC 5226 (Narten, T. and H. Alvestrand, “Guidelines for Writing an IANA Considerations Section in RFCs,” May 2008.) [RFC5226].
As part of this registry IANA will maintain 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.
- URN:
- The URN to be used to identify the profile.
- Identifier Definition:
- IANA will be asked to 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.
- PSKC Profiling:
- Information about PSKC XML elements and attributes being used (or not used) with this specific profile of PSKC.
PSKC algorithm profile identifier registrations are to be subject to Expert Review as per RFC 5226 (Narten, T. and H. Alvestrand, “Guidelines for Writing an IANA Considerations Section in RFCs,” May 2008.) [RFC5226].
IANA is asked to add an initial value to the registry based on the PSKC HOTP algorithm profile described in Section 10 (PSKC Algorithm Profile).
| TOC |
IANA is requested to create a registry for PSKC version numbers. The registry has the following structure:
PSKC Version | Specification +---------------------------+---------------- | 1.0 | [This document]
Standards action is required to define new versions of PSKC. It is not envisioned to deprecate, delete, or modify existing PSKC versions.
| TOC |
IANA is requested to create a registry for key usage. A description of the 'KeyUsage' element can be found in Section 5 (Key policy - transmission of key usage policies and key PIN protection policy). The registry has the following structure:
Key Usage Token | Specification +---------------------------+------------------------------- | OTP | [Section 5 of this document] | CR | [Section 5 of this document] | Encrypt | [Section 5 of this document] | Integrity | [Section 5 of this document] | Verify | [Section 5 of this document] | Unlock | [Section 5 of this document] | Decrypt | [Section 5 of this document] | KeyWrap | [Section 5 of this document] | Unwrap | [Section 5 of this document] | Derive | [Section 5 of this document] | Generate | [Section 5 of this document] +---------------------------+-------------------------------
Expert Review is required to define new key usage tokens. Each registration request has to provide a description of the semantic. Using the same procedure it is possible to deprecate, delete, or modify existing key usage tokens.
| TOC |
The portable key container 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.
| TOC |
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 payload encryption. Symmetric cryptographic cipher should be used - the longer the cryptographic key, the stronger the protection. Please see Section 6.1 (Encryption based on Pre-Shared Keys) for recommendations of 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 secret key payload may be employed, see Section 6.3 (Encryption based on Asymmetric Keys) . Similarly to symmetric key cryptography, the stronger the asymmetric key, the more secure the protection is.
If the payload is encrypted with a method that uses one of the password-based encryption methods provided above, the 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.
Practical implementations should use PBESalt and PBEIterationCount when PBE encryption is used. Different PBESalt value per key container should be used for best protection.
The second approach to protecting the confidentiality of the payload is based on using transport layer security. The secure channel 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 transport the messages that travel across. No payload encryption is required in this mode. Secure channels that encrypt and digest each message provide an extra measure of security, especially when the signature of the payload does not encompass the entire payload.
Because of the fact that the plain text payload is protected only by the transport layer security, practical implementation must ensure protection against man-in-the-middle attacks. Validating the secure channel end-points is critically important for eliminating intruders that may compromise the confidentiality of the payload.
| TOC |
The portable symmetric key container provides a mean to guarantee the integrity of the information it contains through digital signatures. For best security practices, the digital signature of the container should encompass the entire payload. This provides assurances for the integrity of all attributes. It also allows verification of the integrity of a given payload even after the container is delivered through the communication channel to the target perimeter and channel message integrity check is no longer possible.
| TOC |
The digital signature of the payload is the primary way of showing its authenticity. The recipient of the container may use the public key associated with the signature to assert the authenticity of the sender by tracing it back to a preloaded public key or certificate. Note that the digital signature of the payload can be checked even after the container has been delivered through the secure channel of communication.
A weaker payload authenticity guarantee may be provided by the transport layer if it is configured to digest each message it transports. However, no authenticity verification is possible once the container is delivered at the recipient end. This approach may be useful in cases where the digital signature of the container does not encompass the entire payload.
| TOC |
We would like Hannes Tschofenig for his text contributions to this document.
| TOC |
The authors of this draft would like to thank the following people for their feedback: 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.
We would like to thank Sean Turner for his draft review in January 2009. We would also like to thank Anders Rundgren for triggering the discussion regarding to the selection of encryption algorithms (KW-AES-128 vs. AES-128-CBC) and his input on the keyed message digest computation.
This work is based on earlier work by the members of OATH (Initiative for Open AuTHentication), see [OATH] (, “Initiative for Open AuTHentication,” .), to specify a format that can be freely distributed to the technical community.
| TOC |
| TOC |
| [PKCS5] | RSA Laboratories, “PKCS #5: Password-Based Cryptography Standard,” Version 2.0, URL: http://www.rsasecurity.com/rsalabs/pkcs/, March 1999. |
| [RFC2119] | “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. |
| [XMLDSIG] | Eastlake, D., “XML-Signature Syntax and Processing,” URL: http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/, W3C Recommendation, February 2002. |
| [XMLENC] | Eastlake, D., “XML Encryption Syntax and Processing.,” URL: http://www.w3.org/TR/xmlenc-core/, W3C Recommendation, December 2002. |
| [XMLENC11] | Eastlake, D., “XML Encryption Syntax and Processing Version 1.1.,” URL: http://www.w3.org/TR/2009/WD-xmlenc-core1-20090730, W3C Recommendation, July 2009. |
| TOC |
| [AESKWPAD] | Housley, R. and M. Dworkin, “Advanced Encryption Standard (AES) Key Wrap with Padding Algorithm,” March 2009. |
| [CAP] | MasterCard International, “Chip Authentication Program Functional Architecture,” September 2004. |
| [DSKPP] | Doherty, A., Pei, M., Machani, S., and M. Nystrom, “Dynamic Symmetric Key Provisioning Protocol,” Internet Draft Informational, URL: http://www.ietf.org/internet-drafts/draft-ietf-keyprov-dskpp-07.txt, February 2009. |
| [HOTP] | MRaihi, D., Bellare, M., Hoornaert, F., Naccache, D., and O. Ranen, “HOTP: An HMAC-Based One Time Password Algorithm,” RFC 4226, December 2005. |
| [LUHN] | Luhn, H., “Luhn algorithm,” US Patent 2950048, August 1960 (HTML). |
| [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,” URL: http://www.openauthentication.org. |
| [PSKC-ALGORITHM-PROFILES] | Hoyer, P., Pei, M., Machani, S., and A. Doherty, “Additional Portable Symmetric Key Container (PSKC) Algorithm Profiles,” Internet Draft Informational, URL: http://tools.ietf.org/html/draft-hoyer-keyprov-pskc-algorithm-profiles-00, December 2008. |
| [RFC2396] | Berners-Lee, T., Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifiers (URI): Generic Syntax,” BCP 26, RFC 2396, August 1998. |
| [RFC5226] | Narten, T. and H. Alvestrand, “Guidelines for Writing an IANA Considerations Section in RFCs,” BCP 26, RFC 5226, May 2008. |
| [XMLNS] | “Namespaces in XML,” W3C Recommendation , URL: http://www.w3.org/TR/1999/REC-xml-names-19990114, January 1999. |
| TOC |
This section describes a comprehensive list of use cases that inspired the development of this specification. These requirements were used to derive the primary requirement that drove the design. These requirements are covered in the next section.
These use cases also help in understanding the applicability of this specification to real world situations.
| TOC |
This section describes the use cases related to provisioning the keys using an online provisioning protocol such as [DSKPP] (Doherty, A., Pei, M., Machani, S., and M. Nystrom, “Dynamic Symmetric Key Provisioning Protocol,” February 2009.).
| TOC |
For example, a mobile device user wants to obtain a symmetric key for use with a Cryptographic Module on the device. The Cryptographic Module from vendor A initiates the provisioning process against a provisioning system from vendor B using a standards-based provisioning protocol such as [DSKPP] (Doherty, A., Pei, M., Machani, S., and M. Nystrom, “Dynamic Symmetric Key Provisioning Protocol,” February 2009.). The provisioning entity delivers one or more keys in a standard format that can be processed by the mobile device.
For example, in a variation of the above, instead of the user's mobile phone, a key is provisioned in the user's soft token application on a laptop using a network-based online protocol. As before, the provisioning system delivers a key in a standard format that can be processed by the soft token on the PC.
For example, the end-user or the key issuer wants to update or configure an existing key in the Cryptographic Module and requests a replacement key container. The container may or may not include a new key and may 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.
| TOC |
For example, a user wants to transport a key from one Cryptographic Module to another. There may be two cryptographic modules, one on a computer one on a mobile phone, and the user wants to transport a key from the computer to the mobile phone. The user can export the key and related data in a standard format for input into the other Cryptographic Module.
| TOC |
For example, a user wants to activate and use a new key and related data against a validation system that is not aware of this key. This key may be embedded in the Cryptographic Module (e.g. SD card, USB drive) that the user has purchased at the local electronics retailer. Along with the Cryptographic Module, the user may get the key on a CD or a floppy in a standard format. The user can now upload via a secure online channel or import this key and related data into the new validation system and start using the key.
| TOC |
From time to time, a key management system may be required 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 may download the keys using an online protocol. The keys can be downloaded in a standard format that can be processed by a validation system.
For example, in a variation of the above, an Over-The-Air (OTA) key provisioning gateway that provisions keys to mobile phones may obtain key material from a key issuer using an online protocol. The keys are delivered in a standard format that can be processed by the key provisioning gateway and subsequently sent to the end-user's mobile phone.
| TOC |
This section describes the use cases relating to offline transport of keys from one system to another, using some form of export and import model.
| TOC |
For example, Cryptographic Modules such as OTP authentication tokens, may have their symmetric keys initialized during the manufacturing process in bulk, requiring copies of the keys and algorithm data to be loaded into the authentication system through a file on portable media. The manufacturer provides the keys and related data in the form of a file containing records in 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 will allow local PIN management (the device will have a PIN pad) hence random initial PINs set at manufacturing should be transmitted together with the respective keys they protect.
For example, an enterprise wants to port keys and related data from an existing validation system A into a different validation system B. The existing validation system provides the enterprise with a functionality that enables export of keys and related data (e.g. for OTP authentication tokens) in a standard format. Since the OTP tokens are in the standard format, the enterprise can import the token records into the new validation system B and start using the existing tokens. Note that the vendors for the two validation systems may be the same or different.
| TOC |
This section outlines the most relevant requirements that are the basis of this work. Several of the requirements were derived from use cases described above.
- R1:
- The format MUST support 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 such as [DSKPP] (Doherty, A., Pei, M., Machani, S., and M. Nystrom, “Dynamic Symmetric Key Provisioning Protocol,” February 2009.)
- 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 appropriate level of security in terms of data encryption and data integrity.
- R8:
- For online scenarios the format SHOULD NOT rely on transport level security (e.g., 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 lifecycle 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] (RSA Laboratories, “PKCS #5: Password-Based Cryptography Standard,” March 1999.) 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.
| TOC |
| Philip Hoyer | |
| ActivIdentity, Inc. | |
| 117 Waterloo Road | |
| London, SE1 8UL | |
| UK | |
| Phone: | +44 (0) 20 7744 6455 |
| Email: | Philip.Hoyer@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 |