RFC 6030
Portable Symmetric Key Container (PSKC)
5. Key Policy
This section illustrates the functionality of the <Policy> element within PSKC, which allows a key usage and key PIN protection policy to be attached to a specific key and its related metadata. 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. <?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 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. 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, 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:
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 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]).
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 allow several key usages to be
expressed. When this element is absent, no key usage constraint
is assumed, i.e., the key MAY be utilized for every usage.
<PINPolicy>: The <PINPolicy> element allows policy about the PIN
usage to be associated with the key. The following attributes are
specified:
'PINKeyId': This attribute carries the unique 'Id' attribute vale
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 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 (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 the
'PINFormat' attribute is set to 'DECIMAL', 'HEXADECIMAL', or
'ALPHANUMERIC', this value indicates the number of digits/
characters. If the 'PINFormat' attribute is set to '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 set to 'DECIMAL', 'HEXADECIMAL', or
'ALPHANUMERIC', this value indicates the number of digits/
characters. If the 'PINFormat' attribute is set to '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.
If the 'PinUsageMode' attribute is set to 'Local', then the device
MUST enforce the restriction indicated in the 'MaxFailedAttempts',
'MinLength', 'MaxLength', and 'PINEncoding' attributes; otherwise,
it MUST be enforced on the server side.
5.1. PIN Algorithm Definition
The PIN algorithm is defined as:
boolean = comparePIN(K,P)
Where:
'K' is the stored symmetric credential (PIN) in binary format.
'P' is 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.
6. Key Protection Methods
With the functionality described in the previous sections,
information related to keys had to be transmitted in cleartext. 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 Initialization Vectors (IVs), 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].
6.1. Encryption Based on Pre-Shared Keys
Figure 6 shows an example that illustrates the encryption of the content of the <Secret> element using AES-128-CBC and PKCS #5 Padding. The plaintext value of <Secret> is '3132333435363738393031323334353637383930'. The name of the pre- shared secret is "Pre-shared-key", 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 AES-128-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>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 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 [RFC5649] 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-camellia2566.1.1. MAC Method
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, 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 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 in the <EncryptionMethod> element and the <CipherData> element, respectively, 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
6.2. Encryption Based on Passphrase-Based Keys
Figure 7 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]. When using passphrase-based key derivation, the <DerivedKey> element defined in XML Encryption Version 1.1 [XMLENC11] 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 'Algorithm' attribute of the <xenc11: KeyDerivationMethod> element MUST be set to the URI 'http://www.rsasecurity.com/rsalabs/pkcs/schemas/pkcs-5#pbkdf2'. The <xenc11:KeyDerivationMethod> element 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].
<?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 Keys6.3. Encryption Based on Asymmetric Keys
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, 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-mgf1p6.4. Padding of Encrypted Values for Non-Padded Encryption Algorithms
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 cipher block length. For example, when transmitting an HOTP key (20 bytes long) protected with the AES algorithm in CBC mode (8-byte block cipher), padding is required since its length is not a multiple of the 8-byte block length. 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 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]. <?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
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 cryptographic modules. 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 (for example, the keys for the device identified by SerialNo='9999999' in the example below). Figure 10 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> </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 Example9. Extensibility
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, a new version number has to be allocated to refer to the new specification. The version number is carried inside the 'Version' attribute, as described in Section 4, the numbering scheme MUST follow Section 1.2, and rules for extensibility are defined in Section 12.
New XML Elements: The usage of the XML schema and the available
extension points allows new XML elements to be added. Depending
on the type of XML element, 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).
New PSKC Algorithm Profiles: This document defines two PSKC
algorithm profiles, see Section 10. The following informational
document describes additional profiles [PSKC-ALGORITHM-PROFILES].
Further PSKC algorithm profiles can be registered as described in
Section 12.4.
Algorithm URIs: Section 6 defines how keys and related data can be
protected. A number of algorithms can be used. New algorithms
can be used by pointing to a new algorithm URI.
Policy: Section 5 defines policies that can be attached to a key and
keying-related data. The <Policy> element is one such item that
allows implementers 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.
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:
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) MUST be provided as
metadata 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 (inclusive).
+ The <PINPolicy> element MAY be present, but the
'PINUsageMode' attribute cannot be set to "Algorithmic".
An example can be found in Figure 3.
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 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) MUST be provided.
See the example in Figure 5
(page 38 continued on part 3)
