Portable Symmetric Key Container (PSKC)
Extracted elements (31)
PSKC was designed as an XML-based standard key container to replace proprietary vendor formats for importing/exporting symmetric keys (OTP shared secrets, encryption keys) to authentication servers and hardware tokens, enabling best-of-breed deployments mixing components from different vendors.
The deny-by-default behavior for unrecognized <Policy> child elements (Section 5) was chosen to ensure that future policy extensions cannot be silently ignored, preventing an implementation that does not understand a new restriction from inadvertently permitting key usage that the sender intended to prohibit.
Unless an algorithm specification explicitly defines a different encoding, all key OCTET STRING encodings in PSKC MUST follow the AES Key Value Encoding (first octet = MSB index 0). Implementers must verify test vectors from FIPS 197 Appendix A match when decoding the canonical base64 PlainValue.
A valid <KeyContainer> MUST carry at least one <KeyPackage> entity.
Date values in <StartDate> and <ExpiryDate> elements (in both <DeviceInfo> and <Policy>) MUST be expressed as xs:dateTime in canonical representation; implementations SHOULD NOT rely on time resolution finer than milliseconds and MUST NOT generate time instants specifying leap seconds.
For the HOTP algorithm profile, the <Secret> element value MUST contain key material with a length of at least 16 octets (128 bits) if present. The <ResponseFormat> 'Format' attribute MUST be 'DECIMAL' and the 'Length' attribute MUST be between 6 and 9 inclusive.
If the <Policy> element contains child elements or attribute values not understood by the recipient, the recipient MUST assume that key usage is not permitted. This deny-by-default ensures unknown policy extensions do not silently permit unintended usage.
The <Key> element 'Id' attribute value MUST remain the same across multiple PSKC interactions referencing the same key (e.g., initial provisioning followed by metadata update), to enable stable key identification between parties.
The recipient of a PSKC document MUST enforce the <KeyUsage> element constraints; e.g., a key with usage 'OTP' MUST only be used for OTP generation.
The 'Version' attribute MUST be included in the <KeyContainer> element. Version major and minor numbers MUST be treated as separate integers; leading zeros MUST be ignored by recipients and MUST NOT be sent.
When algorithms without integrity checks (such as AES-128-CBC) are used, a keyed-MAC value MUST be placed in the <ValueMAC> element, and the MAC algorithm type MUST be set in the <MACMethod> element. The MAC key MUST be randomly generated or pre-agreed, and if randomly generated, MUST be encrypted with the same encryption key.
When encryption algorithms using CBC mode are employed, a random IV MUST be generated for each encrypted value and MUST be prepended to the resulting encrypted value as specified in XML Encryption.
When using passphrase-based key derivation (PBKDF2), the <DerivedKey> element from XML Encryption 1.1 MUST be used as a child of <EncryptionKey>; the 'Algorithm' attribute of <KeyDerivationMethod> MUST be set to the PBKDF2 URI, and the <PBKDF2-params> child element MUST be included.
The <AlgorithmParameters> element contains <Suite> (algorithm-specific characteristics, e.g., hash strength), <ChallengeFormat> (encoding, min/max size, CheckDigit for CR algorithms), and <ResponseFormat> (encoding, length, CheckDigit for OTP/CR output). Both <ChallengeFormat> and <ResponseFormat> require mandatory 'Encoding', and 'Min'/'Max' or 'Length' attributes.
The <Data> element carries key-related metadata with child elements <Secret> (key value as base64Binary), <Counter> (event counter for HOTP), <Time> (time intervals for TOTP), <TimeInterval> (interval in seconds), and <TimeDrift> (device clock drift). Each supports plaintext via <PlainValue> or encrypted form via <EncryptedValue>, with optional <ValueMAC> for integrity.
The <DeviceInfo> element uniquely identifies the target device using combinations of <Manufacturer>, <SerialNo>, <Model>, <IssueNo>, <DeviceBinding>, <StartDate>, <ExpiryDate>, and <UserId> child elements. Manufacturer values MUST be prefixed with 'oath.' (from OATH registry) or 'iana.' (from IANA PEN registry).
The <EncryptionKey> element, a child of <KeyContainer>, specifies the key protection method for all enclosed <KeyPackage> elements: pre-shared keys (via <ds:KeyName>), passphrase-derived keys (via <xenc11:DerivedKey> with PBKDF2), or asymmetric keys (via <ds:X509Data>). The same encryption algorithm MUST be applied to all encrypted elements.
The <Key> element carries keying material and metadata, with mandatory 'Id' (unique alphanumeric key identifier stable across provisioning interactions) and optional 'Algorithm' (PSKC algorithm profile URI) attributes, plus optional child elements including <Issuer>, <FriendlyName>, <AlgorithmParameters>, <Data>, <UserId>, and <Policy>.
The <KeyContainer> element is the top-level PSKC document element, carrying one or more <KeyPackage> elements along with optional <EncryptionKey>, <MACMethod>, <Signature>, and <Extensions> child elements. It requires a mandatory 'Version' attribute and an optional 'Id' attribute for unique container identification.
The <KeyPackage> element bundles at most one <Key> element together with its associated <DeviceInfo> and <CryptoModuleInfo> elements, representing the provisioning or usage endpoint for a single symmetric key.
The <MACMethod> element specifies the MAC algorithm URI and carries an encrypted <MACKey> (or <MACKeyReference> for pre-shared MAC keys). It is required when encryption algorithms lacking integrity checks (e.g., AES-CBC) are used, and applies container-wide to all encrypted values.
The <Policy> element attaches key usage constraints to a <Key>, including <StartDate>/<ExpiryDate> for validity period, <NumberOfTransactions> for maximum use count, <KeyUsage> (OTP, CR, Encrypt, Integrity, Verify, Unlock, Decrypt, KeyWrap, Unwrap, Derive, Generate), and <PINPolicy> for PIN enforcement parameters.
The PSKC XML namespace for version 1.0 is 'urn:ietf:params:xml:ns:keyprov:pskc', and implementations SHOULD use the prefix 'pskc'. PSKC also relies on XML Signature (ds:), XML Encryption (xenc:), XML Encryption 1.1 (xenc11:), and PKCS#5 (pkcs5:) namespaces.
This document creates the 'Key Usage Registry' (Section 12.6) with initial values: OTP, CR, Encrypt, Integrity, Verify, Unlock, Decrypt, KeyWrap, Unwrap, Derive, Generate. New key usage values require IETF Review.
This document creates the 'PSKC Algorithm Profile Registry' (Section 12.4) to record algorithm profiles with their metadata and PSKC transmission profiles. Initial entries are the HOTP profile (urn:ietf:params:xml:ns:keyprov:pskc:hotp) and the PIN profile (urn:ietf:params:xml:ns:keyprov:pskc:pin). New profiles require IETF Review.
This document registers the 'application/pskc+xml' MIME media type (Section 12.1) for PSKC documents, and registers the XML schema and URN sub-namespace 'urn:ietf:params:xml:ns:keyprov:pskc' (Sections 12.2, 12.3). A 'PSKC Version Registry' is also created (Section 12.5) with initial entry '1.0'.
PSKC authenticity is established via an XML digital signature (<Signature> child element of <KeyContainer>) using XML Signature [XMLDSIG]. This enables receivers to verify the origin of a PSKC document and that it has not been tampered with in transit.
PSKC confidentiality requires that symmetric keys be protected in transport. PSKC supports three protection methods: pre-shared key encryption (recommended: AES-128-CBC and KW-AES128), passphrase-derived key encryption (PBKDF2), and asymmetric key encryption (recommended: RSA-1.5). Keys SHOULD NOT be transmitted in plaintext in production deployments.
PSKC integrity is provided by the <ValueMAC> mechanism when encryption algorithms without built-in integrity (e.g., AES-CBC) are used, and by XML digital signatures over the entire <KeyContainer>. Both mechanisms may be combined; the MAC protects individual encrypted values while the signature covers the whole document.
Key values in <PlainValue> and <EncryptedValue> are encoded as xs:base64Binary (OCTET STRING). For AES keys, the first octet of the OCTET STRING maps to AES key byte index 0 (MSB-first per FIPS 197 Section 5.2). This encoding is the default for all algorithms unless the algorithm specification states otherwise.
Triple-DES key bundles are encoded as a concatenated OCTET STRING of Key1 || Key2 || Key3 (each 64 bits, 8 bytes, MSB first), with two-key Triple-DES using Key2 in place of Key3. The encoding must match SP 800-67 Appendix B test vectors.