|
Please find attached the draft of the PSKC submitted to IETF today. It contains some additional update based
on late comments from Rob Philpott and Andrea Doherty. Changes
made from version 4 are:
[Update] Extension points: Changed to model proposed by Rob Philpott
declaring a new type: <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> Which has been added as “<xs:element name="Extensions" type="pskc:ExtensionsType" minOccurs="0" maxOccurs="unbounded"/>” To:
Please NOTE that KeyData still has the
existing “<xs:any namespace="##other" minOccurs="0" maxOccurs="unbounded"/>” Because of the special nature of the
KeyData element and subelements PINUsageMode too maintains the existing
“<xs:any namespace="##other" minOccurs="0" maxOccurs="unbounded"/>” Being an extensible enumeration Added a ‘<xs:anyAttribute
namespace="##other"/>’ to:
<xs:attribute name="OTP" type="xs:boolean"
default="false"/>
<xs:attribute name="CR" type="xs:boolean" default="false"/>
<xs:attribute name="Integrity" type="xs:boolean"
default="false"/>
<xs:attribute name="Encrypt" type="xs:boolean"
default="false"/>
<xs:attribute name="Unlock" type="xs:boolean"
default="false"/>
So I thought it would be wise to be able to extend this Outstanding
issues that need to be discussed:
“ 3. Shouldn’t the “KeyId” attribute in the
KeyType type also be of type xs:ID? It is currently defined as xs:string?
If this was intentional, I am quite confused as to the reason for using
xs:string. a. Assuming KeyId should be of type xs:ID (and renamed to
simply “Id”), then the PINKeyId attribute in the PINPolicyType type
(pending #1 above) and the MasterKeyId attribute in KeyPropertiesType and
KeyType types would need to be of type xs:IDREF. These attributes are
described to be unique references to keys. [PH] No it can’t be
of type xs:ID becaue KeyId is actually what you refer further down as the
unique serial number of the keys. [RSP] I suspected that might be the case. However,
based on my experience with a number of other XML-based protocols, I strongly
recommend separating the mechanism of identifying a blob of XML in an instance
document (for which xs:ID and xs:IDREF are very useful) from the serial numbers
that tie the blob to information managed by external systems. That is, it
is generally not a good idea to overload an attribute to serve double-duty. IMO
that’s just a cleaner content model. The ID/IDREF attributes
provide formal semantics for defining/referring to the XML blobs. A “serial
number” string does not. Also, it seems to me that the serial number of a
key is no different from a serial number of a device in that it’s info
about the key itself, not the XML blob representing the key. Yet you didn’t
use the ID attribute of the device as the serial number of the device. Thus the
current approach is internally inconsistent. So, I still recommend: ·
In <KeyType>, change <xs:attribute name="KeyId"
type="xs:string" use="required"/> to <xs:attribute
name="ID" type="xs:ID" use="required"/> ·
Since <PINKeyId> refers to a specific
<Key> in the instance document, in <PINPolicyType>, change <xs:attribute name="PINKeyId"
type="xs:string" use="optional"/> to <xs:attribute
name="PINKey" type="xs:IDREF" use="optional"/> Finally, in <KeyType> add <xs:element name=”SerialNo” type=”xs:string
minOccurs=”0”> I think it should be an optional element
(since we would now have the xs:ID that can be used to refer to it), although I
could be convinced it should be mandatory. The description would be: ·
<SerialNo> (OPTIONAL), a unique
and global identifier of the symmetric key. The identifier is defined as
a string of alphanumeric characters. “
Rob Philpot
BTW, we’d also like to
raise a concern about defining <Time> as an xs:int (via intDataType).
IMO, <Time> should be defined as an xs:dateTime, which we’ve
recently agreed would uniformly express time as UTC in Z form. Using an
int for time is very problematic for computational reasons. The spec
leaves the interpretation of this value undefined. It just seems dangerous to
leave this so ambiguously defined. If expressed as a UTC time value using
xs:dateTime, then it’s pretty easy to do the right thing and timezones,
etc don’t get in the way. Protocols really shouldn’t leave
such things to chance since it definitely inhibits interoperability. <Time> also seems to
have an overloaded use if the <TimeInterval> value is also provided.
In this case the <Time> value is not a time value, but is instead an
interval count. IMO, this is confusing and the overloading should be
avoided by adding an optional <IntervalCount> element. If
<TimeInterval> is not specified, is <Time> a local time? What
is the epoch? Etc. etc… It seems pretty ambiguous. Now, we don’t
need it for our use cases, although we might in the future. I do think it
would be helpful to clean this up. “ –
Rob Philpot Philip From: Here is Philip Hoyer's response
to Rob's comments (see below), which we initially handled offline, and
then we decided it would be better to further the discussion on the mailing
list. -- Andrea [PH] good point I was
thinking that xs:Id for KeyPropertiesId could be a good choice The KeyId
on the other hand is not really used to be referred to. Do you think it would
be better to use xs:ID for this aswell? And in case we use it now is it
backwards compatible to what we have?
[PH] valid comment and I
will think we should add this [PH] agreed [PH] so basically you are saying that any
high level entity (Key, Device, KeyContainer etc) should have an ID that is
xs:ID? The thought of DeviceId was to aggregate under a specific type the elements
that comprise the compound key to look up the device
[PH] agreed I think we
should add an xs:any [PH] this has been
extensively discussed at IETF and there are pros and cons for all approaches.
The pro’s of the name value approach is that it will be re-usable for the
ASN.1 spec and that we will have a semantic registry defined by IANA.
[PH] this has been
extensively discussed. And we opted for the name value pair approach. This mean
that all elements in Data can be parsed in the same manner and individually be
encrypted or not. There will be a centralized semantic registry by IANA, etc
[PH] why do you say that,
the name could be also be a namespace for an wholly encrypted or base64 encoded
XML sub node. I see your point though in terms of parsing here. Could you give
me an example of what you had in mind since we have considered quite a few use
cases and not come across the requirement for grouped extensions.
[PH] using xs:string for
plainvalue was discussed during the last IETF meeting (I personally am in favor
of it) but Sean Turner and the rest of the people did not see much value in it.
If we use string we will need to deice for specific data elements what the
encoding rules are. For example do we say for 8 byte unsigned int to encode
just string e.g. ‘60’ or leading 0 examples ‘00000060’.
I would appreciate your thoughts on this. Also how would we encode binary data
in string form base64 encoded?
[PH] agreed and see
answer above
[PH] if you are referring
to the fact that ‘<xs:attribute name="PINKeyId"
type="xs:string" use="required"/>’ is set to
required I agree with you. We should set this to ‘optional’. I do
not agree with your 90% use case analysis since the main use cases I have come
across where to transmit the initial random pin for PINPads tokens within the
same PSKC document from manufacturing to the validation server.
[PH] I agree we need to
make PINPolicy extensible and not put stuff into the Data elements of the
PINKey. Are there any other elements that you know of we should include now and
not just as an xs:any extension?
<Key
KeyId="07552252661"
KeyAlgorithm="http://www.ietf.org/keyprov/pskc#pin">
<Usage>
<ResponseFormat Length="4" Format="DECIMAL"/>
</Usage>
<Data Name="SECRET">
<PlainValue>MTIzNA==</PlainValue>
</Data> </Key> [PH] I see your point. If we make PINKeyId optional as in the
comment above you can have a common PINPolicy as part of the shared
KeyProperties. I believe that would serve your purpose.
[PH] agreed, will change
|
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY rfc2119 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
]>
<rfc category="std" ipr="full3978" docName="draft-ietf-keyprov-portable-symmetric-key-container-05.txt">
<?rfc toc="yes" ?>
<?rfc symrefs="yes" ?>
<?rfc sortrefs="yes"?>
<?rfc iprnotified="no" ?>
<?rfc strict="yes" ?>
<front>
<title>Portable Symmetric Key Container</title>
<author initials="P." surname="Hoyer" fullname="Philip Hoyer">
<organization abbrev="ActivIdentity">
ActivIdentity, Inc.
</organization>
<address>
<postal>
<street>117 Waterloo Road</street>
<city>London</city>
<region>SE1</region>
<code>8UL</code>
<country>UK</country>
</postal>
<phone>+44 (0) 20 7744 6455</phone>
<email>Philip.Hoyer at actividentity.com</email>
</address>
</author>
<author initials="M." surname="Pei" fullname="Mingliang Pei">
<organization abbrev="VeriSign">
VeriSign, Inc.
</organization>
<address>
<postal>
<street>487 E. Middlefield Road</street>
<city>Mountain View</city>
<region>CA</region>
<code>94043</code>
<country>USA</country>
</postal>
<phone>+1 650 426 5173</phone>
<email>mpei at verisign.com</email>
</address>
</author>
<author initials="S." surname="Machani" fullname="Salah Machani">
<organization abbrev="Diversinet">
Diversinet, Inc.
</organization>
<address>
<postal>
<street>2225 Sheppard Avenue East</street>
<street>Suite 1801</street>
<city>Toronto</city>
<region>Ontario</region>
<code>M2J 5C2</code>
<country>Canada</country>
</postal>
<phone>+1 416 756 2324 Ext. 321</phone>
<email>smachani at diversinet.com</email>
</address>
</author>
<date day="14" month="July" year="2008"/>
<workgroup>keyprov</workgroup>
<abstract>
<t>This document specifies a symmetric key format for transport
and provisioning of symmetric keys (for example One Time Password (OTP) shared secrets or
symmetric cryptographic keys) to different types of crypto modules such as a strong authentication device.
The standard key transport format enables enterprises to deploy best-of-breed solutions combining
components from different vendors into the same infrastructure. </t>
<t>This work is a joint effort by the members of OATH (Initiative for Open AuTHentication)
to specify a format that can be freely distributed to the technical community. The authors
believe that a common and shared specification will facilitate adoption of two-factor
authentication on the Internet by enabling interoperability between commercial and
open-source implementations.</t>
</abstract>
</front>
<middle>
<section title="Introduction">
<t>With increasing use of symmetric key based authentication systems such as systems based one time password (OTP) and challenge
response mechanisms, there is a need for vendor interoperability and a standard format for importing, exporting or
provisioning symmetric keys from one system to another. Traditionally authentication server vendors
and service providers have used proprietary formats for importing, exporting and provisioning these keys
into their systems making it hard to use tokens from vendor A with a server from vendor B.</t>
<t>This Internet draft describes a standard format for serializing symmetric keys such as OTP shared secrets for system import, export or network/protocol transport.
The goal is that the format will facilitate dynamic provisioning and transfer of symmetric keys such as OTP shared secrets or
encryption keys of different types. In the case of OTP shared secrets, the format will facilitate
dynamic provisioning using an online provisioning protocol to different flavors of embedded tokens or allow
customers to import new or existing tokens in batch or single instances into a compliant system.</t>
<t>This draft also specifies the key attributes required for computation such as the initial event
counter used in the HOTP algorithm <xref target="HOTP"/>. It is also applicable for other
time-based or proprietary algorithms. </t>
<t>To provide an analogy, in public key environments the PKCS#12 format <xref target="PKCS12"/> is commonly used for
importing and exporting private keys and certificates between systems. In the environments outlined
in this document where OTP keys may be transported directly down to smartcards or devices
with limited computing capabilities, a format with small (size in bytes) and explicit shared secret
configuration attribute information is desirable, avoiding complexity of PKCS#12. For example,
one would have to use opaque data within PKCS#12 to carry shared secret attributes used for OTP
calculations, whereas a more explicit attribute schema definition is better for interoperability
and efficiency.</t>
</section>
<section title="Terminology">
<section title="Key Words">
<t>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 <xref target="RFC2119"/>.</t>
</section>
<section title="Definitions">
<t>This section defines terms used in this document. The same terms
may be defined differently in other documents.
<list style="hanging">
<t hangText="Authentication Token:">A physical device that an authorized user of
computer services is given to aid in authentication. The term may also refer to
software tokens.</t>
<t hangText="Bulk Provisioning:">Transferring multiple keys linked to multiple devices in a single execution step within one single PSKC KeyContainer</t>
<t hangText="Cryptographic Module:">A component of an application, which enables
symmetric key cryptographic functionality</t>
<t hangText="Cryptographic Key:">A parameter used in conjunction with a cryptographic
algorithm that determines its operation in such a way that an entity with knowledge
of the key can reproduce or reverse the operation, while an entity without knowledge
of the key cannot (see <xref target="NIST-SP800-57"/>)</t>
<t hangText="Cryptographic Token:">See Authentication Token</t>
<t hangText="Device:">A physical piece of hardware, or a software framework, that
hosts symmetric keys</t>
<t hangText="DeviceInfo:">A set of elements whose values combined uniquely identify a device e.g. Manufacture 'Manufacturer and Serialnumber '12345678'</t>
<t hangText="Dynamic Provisioning:">Usage of a protocol, such as DSKPP, to make a key container available to a recipient</t>
<t hangText="Encryption Key:">A key used to encrypt key</t>
<t hangText="Key:">See Cryptographic Key</t>
<t hangText="Hardware Token:">See Authentication Token</t>
<t hangText="Key Algorithm:">A well-defined computational procedure that takes
variable inputs including a cryptographic key and produces an output.</t>
<t hangText="Key Container:">An object that encapsulates symmetric keys and their
attributes for set of devices</t>
<t hangText="Key ID (KeyID):">A unique identifier for the symmetric key</t>
<t hangText="Key Issuer:">An organization that issues symmetric keys to end-users</t>
<t hangText="Key Type:">The type of symmetric key cryptographic methods for which
the key will be used (e.g., OATH HOTP or RSA SecurID authentication, AES encryption,
etc.)</t>
<t hangText="Secret Key:">The symmetric key data</t>
<t hangText="Software Token:">A type of authentication token that is stored on
a general-purpose electronic device such as a desktop computer, laptop, PDA,
or mobile phone </t>
<t hangText="Token:">See Authentication Token</t>
<t hangText="User:">The person or client to whom devices are issued</t>
<t hangText="User ID:">A unique identifier for the user or client</t>
</list></t>
</section>
</section>
<section title="Use Cases">
<t>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.</t>
<t>These use cases also help in understanding the applicability of this specification to real world situations.</t>
<section title="Online Use Cases">
<t>This section describes the use cases related to provisioning the keys
using an online provisioning protocol such as <xref target="DSKPP"/></t>
<section title="Transport of keys from Server to Cryptomodule">
<t>For example, a mobile device user wants to obtain a symmetric key for use with a cryptomodule on the device. The cryptomodule client from vendor A initiates the provisioning process against a provisioning system from vendor B using a standards-based provisioning protocol such as <xref target="DSKPP"/>. The provisioning entity delivers one or more keys in a standard format that can be processed by the mobile device.</t>
<t>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.</t>
<t>For example, the end-user or the key issuer wants to update or configure an existing
key in the cryptomodule 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.</t>
</section>
<section title="Transport of keys from Cryptomodule to Cryptomodule">
<t>For example, a user wants to transport a key from one cryptomodule 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 cryptomodule.</t>
</section>
<section title="Transport of keys from Cryptomodule to Server">
<t>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 cryptomodule (e.g. SD card, USB drive) that the user has purchased at the local electronics retailer. Along with the cryptomodule, 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.</t>
</section>
<section title="Server to server Bulk import/export of keys">
<t>From time to time, a key management system may be required to import or export keys in bulk from one entity to another. </t>
<t>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.</t>
<t>For example, in a variation of the above, an 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.</t>
</section>
</section>
<section title="Offline Use Cases">
<t>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. </t>
<section title="Server to server Bulk import/export of keys">
<t>For example, cryptomodules 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.</t>
<t>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. </t>
</section>
</section>
</section>
<section title="Requirements">
<t>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.
<list style="format R%d:">
<t>The format MUST support transport of multiple types of symmetric keys and related attributes for algorithms
including HOTP, other OTP, challenge-response, etc.</t>
<t>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
<list style="symbols">
<t>Unique Key Identifier</t>
<t>Issuer information</t>
<t>Algorithm ID</t>
<t>Algorithm mode</t>
<t>Issuer Name</t>
<t>Key friendly name</t>
<t>Event counter value (moving factor for OTP algorithms)</t>
<t>Time value</t>
</list>
</t>
<t>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 <xref target="DSKPP"/></t>
<t>The format SHOULD allow bulk representation of symmetric keys</t>
<t>The format SHOULD allow bulk representation of PINs related to specific keys</t>
<t>The format SHOULD be portable to various platforms. Furthermore, it SHOULD be
computationally efficient to process.</t>
<t>The format MUST provide appropriate level of security in terms of data encryption
and data integrity. </t>
<t>For online scenarios the format SHOULD NOT rely on transport level security
(e.g., SSL/TLS) for core security requirements.</t>
<t>The format SHOULD be extensible. It SHOULD enable extension points allowing
vendors to specify additional attributes in the future.</t>
<t>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.</t>
<t>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.</t>
<t>The format MUST support the use of pre-shared symmetric keys to ensure confidentiality of
sensitive data elements. </t>
<t>The format MUST support a password-based encryption (PBE) <xref target="PKCS5"/> scheme to ensure
security of sensitive data elements. This is a widely used method for various provisioning scenarios.</t>
<t>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 encryption key is difficult to use. </t>
</list>
</t>
</section>
<section title="Portable Key container definition">
<t>The portable key container is based on an XML schema definition and contains the following main entities:
<list style="numbers">
<t>KeyContainer entity as defined in <xref target="KeyContainerEntity"/>
</t>
<t>KeyProperties entity as defined in <xref target="KeyPropertiesEntity"/>
</t>
<t>Device entity as defined in <xref target="DeviceEntity"/>
</t>
<t>Key entity as defined in <xref target="KeyEntity"/>
</t>
</list>
</t>
<t>Additionally other XML schema types have been defined and are detailed in the relevant subsections of this document</t>
<t>A KeyContainer MAY contain one or more Device entities.
A Device MAY contain one or more Key entities</t>
<t>
The figure below indicates a possible relationship diagram of a container.
</t>
<figure>
<artwork>
--------------------------------------------
| KeyContainer |
| |
| -------------------- |
| | Keyproperties 1 | |
| | | |
| -------------------- |
| ------------------ ----------------- |
| | Device 1 | | Device n | |
| | | | | |
| | ------------ | | ------------ | |
| | | Key 1 | | | | Key n | | |
| | ------------ | | ------------ | |
| | | | | |
| | | | | |
| | ------------ | | ------------ | |
| | | Key m | | | | Key p | | |
| | ------------ | | ------------ | |
| ------------------ ----------------- |
| |
--------------------------------------------
</artwork>
</figure>
<t>The following sections describe in detail all the entities and related XML schema elements and attributes:</t>
<section anchor="KeyContainerEntity" title="KeyContainer">
<t>The KeyContainer represents the key
container entity. A Container MAY contain more than one Device entity; each Device
entity MAY contain more than one Key entity.</t>
<t>The KeyContainer is defined as follows:</t>
<figure>
<preamble/>
<artwork><![CDATA[
<xs:complexType name="KeyContainerType">
<xs:sequence>
<xs:element name="EncryptionKey"
type="ds:KeyInfoType" minOccurs="0"/>
<xs:element name="MACAlgorithm"
type="pskc:KeyAlgorithmType" minOccurs="0"/>
<xs:element name="KeyProperties"
type="pskc:KeyPropertiesType" minOccurs="0"
maxOccurs="unbounded"/>
<xs:element name="Device"
type="pskc:DeviceType" minOccurs="1"
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>
]]></artwork>
<postamble/>
</figure>
<t>The attributes of the KeyContainer have the following meanings:
<list style="symbols">
<t>Version (MANDATORY), the version number for the portable key container format
(the XML schema defined in this document).</t>
<t>ID (OPTIONAL), the unique ID for this container in case an XML document contains more than one container and wants to refer to them uniquely.</t>
</list>
</t>
<t>The elements of the KeyContainer have the following meanings:
<list style="symbols">
<t><EncryptionKey> (OPTIONAL), Identifies the encryption key, algorithm and possible parameters used to protect the Secret Key data in the container. Please see <xref target="EncryptionKeyDescription"/> for detailed description of how to protect key data in transit and the usage of this element.
</t>
<t><MACAlgorithm> (OPTIONAL), Identifies the algorithm used to generate a keyed digest of the Secret Key data values when protection algorithms are used that do not have integrity checks. The digest guarantees the integrity and the authenticity of the key data. for profile and usage please see <xref target="SymmetricKeyProtectionDescription"/>
</t>
<t><KeyProperties> (OPTIONAL), key property entities containing key related properties that are common for keys within this container. Please see <xref target="KeyPropertiesEntity"/> for detailed description of this element.The KeyContainer MAY contain multiple KeyProperties elements each containing a set of properties related to one or more keys transported within the container.
</t>
<t><Device> (MANDATORY), the host Device for one or more Keys as defined in <xref target="DeviceEntity"/> The KeyContainer MAY contain multiple Device data elements, allowing for bulk provisioning of multiple devices each containing multiple keys.</t>
<t><Signature> (OPTIONAL), the signature value of the Container.
When the signature is applied to the entire container, it MUST use XML Signature
methods as defined in <xref target="XMLDSIG"/>. It MAY be omitted when application
layer provisioning or transport layer provisioning protocols provide the integrity and
authenticity of the payload between the sender and the recipient of the container.
When required, this specification recommends using a symmetric key based signature
with the same key used in the encryption of the secret key data. The signature is enveloped.</t>
<t><Extensions> (OPTIONAL), is the extension point for this entity. All extensions are grouped under this element and will be of type pskc:ExtensionType, which contains an optional attribute 'defintion' that can have a URI pointing at the defintion of the extension. In this way groups of extension can be bundled under a subelement. For example:
<figure>
<preamble/>
<artwork><![CDATA[
<Extensions>
<MyExtension1
definition="http://ACME/MyExtension1.html";>blah</Myextension1>
<YourExtension99>blahblah</YourExtension99>
</Extensions>]]></artwork>
<postamble/>
</figure>
</t>
</list>
</t>
</section>
<section anchor="KeyPropertiesEntity" title="KeyProperties">
<t>The KeyProperties represents common properties shared by more than one key held in the container. If a value is set in the properties the Key element can refer to it via ID attribute. Values that are present in the Key element itself MUST take precedence over values set in KeyProperties. The KeyProperties is defined as follows:</t>
<figure>
<preamble/>
<artwork><![CDATA[
<xs:complexType name="KeyPropertiesType">
<xs:sequence>
<xs:element name="Issuer" type="xs:string"
minOccurs="0"/>
<xs:element name="Usage" type="pskc:UsageType"
minOccurs="0"/>
<xs:element name="KeyProfileId" type="xs:string"
minOccurs="0"/>
<xs:element name="MasterKeyId" type="xs:string"
minOccurs="0"/>
<xs:element name="Data" type="pskc:KeyDataType"
minOccurs="0" maxOccurs="1"/>
<xs:element name="PINPolicy"
type="pskc:PINPolicyType" minOccurs="0"/>
<xs:element name="StartDate" type="xs:dateTime"
minOccurs="0"/>
<xs:element name="ExpiryDate"
type="xs:dateTime" minOccurs="0"/>
<xs:element name="Extensions"
type="pskc:ExtensionsType" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="ID" type="xs:ID"
use="required"/>
<xs:attribute name="KeyAlgorithm"
type="pskc:KeyAlgorithmType" use="optional"/>
</xs:complexType>
]]></artwork>
<postamble/>
</figure>
<t>The attributes of the KeyProperties entity have the following meanings:
<list style="symbols">
<t>ID (MANDATORY), a unique and global identifier of set of KeyProperties. The identifier is defined as a string of alphanumeric characters.</t>
<t>KeyAlgorithm (OPTIONAL), the unique URI of the type of algorithm
to use with a secret key for the profiles described in <xref target="KeyAlgorithmAttribute"/>
</t>
</list>
</t>
<t>Since KeyProperties are a method to group element values that are common to multiple keys transported, please refer to <xref target="KeyEntity"/> for detailed description of all elements.
</t>
</section>
<section anchor="DeviceEntity" title="Device">
<t>The Device represents an extensible Device entity in the Container.
A Device MAY be bound to a user and MAY contain more than one key. A key SHOULD be bound to only one Device.</t>
<t>The Device is defined as follows:</t>
<figure>
<preamble/>
<artwork><![CDATA[
<xs:complexType name="DeviceType">
<xs:sequence>
<xs:element name="DeviceInfo" type="pskc:DeviceInfoType"
minOccurs="0"/>
<xs:element name="Key" type="pskc:KeyType"
maxOccurs="unbounded"/>
<xs:element name="User" type="xs:string" minOccurs="0"/>
<xs:element name="Extensions"
type="pskc:ExtensionsType" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
]]></artwork>
<postamble/>
</figure>
<t>The elements of the Device have the following meanings:
<list style="symbols">
<t><DeviceInfo> (OPTIONAL), a set of elements containing information about the device, whose values uniquely identify the device, defined in <xref target="DeviceInfoElement"/>
</t>
<t><Key> (MANDATORY), represents the key entity as defined in <xref target="KeyEntity"/>
</t>
<t><User> (OPTIONAL), identifies the owner or the user of the Device, a string representation of a Distinguished Name as defined in <xref target="RFC4514"/>. For example UID=jsmith,DC=example,DC=net. In systems where unique user Ids are used the string representation 'UID=[uniqueId]' SHOULD be used.</t>
<t><Extensions> (OPTIONAL), is the extension point for this entity. All extensions are grouped under this element and will be of type pskc:ExtensionType, which contains an optional attribute 'defintion' that can have a URI pointing at the defintion of the extension. In this way groups of extension can be bundled under a subelement. For example:
<figure>
<preamble/>
<artwork><![CDATA[
<Extensions>
<MyExtension1
definition="http://ACME/MyExtension1.html";>blah</Myextension1>
<YourExtension99>blahblah</YourExtension99>
</Extensions>]]></artwork>
<postamble/>
</figure>
</t>
</list>
</t>
<section anchor="DeviceInfoElement" title="DeviceInfo">
<t>The DeviceInfo represents an extensible set of elements that form the identifying criteria to uniquely identify the device that contains the associated
keys. Since devices can come in different form factors such as hardware tokens, smart-cards, soft tokens
in a mobile phone or PC etc this element allows different criteria to be used. Combined though the criteria MUST uniquely identify the device. For example for hardware tokens the combination of SerialNo and Manufacturer will uniquely identify a device but not SerialNo alone since two different token manufacturers might issue devices with the same serial number (similar to the IssuerDN and serial number of a certificate). Symmetric Keys used in the payment industry are usually stored on Integrated Circuit Smart Cards. These cards are uniquely identified via the Primary Account Number (PAN, the long number printed on the front of the card) and an expiry date of the card. DeviceInfo is an extensible type that allows all these different ways to uniquely identify a specific key containing device.</t>
<t>The DeviceInfo is defined as follows:</t>
<figure>
<preamble/>
<artwork><![CDATA[
<xs:complexType name="DeviceInfoType">
<xs:sequence>
<xs:element name="Manufacturer" type="xs:string"/>
<xs:element name="SerialNo" type="xs:string"/>
<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="Extensions"
type="pskc:ExtensionsType" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
]]></artwork>
<postamble/>
</figure>
<t>The elements of DeviceInfo have the following meanings:
<list style="symbols">
<t><Manufacturer> (MANDATORY), the manufacturer of the device.</t>
<t><SerialNo> (MANDATORY), the serial number of the device or the PAN (primary account number)
in case of payment smart cards.</t>
<t><Model> (OPTIONAL), the model of the device (e.g. one-button-HOTP-token-V1)</t>
<t><IssueNo> (OPTIONAL), the issue number in case of smart cards with the same PAN, equivalent to a
PSN (PAN Sequence Number).</t>
<t><DeviceBinding> (OPTIONAL), the identifier that can be used to bind keys to the device or class of device. When loading keys into a device, this identifier can be checked against information obtained from the device to ensure that the correct device or class of device is being used.</t>
<t><StartDate> (OPTIONAL), the start date of a device (such as the one on a payment card, used when issue numbers are not printed on cards). 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.</t>
<t><ExpiryDate> (OPTIONAL), the expiry date of a device (such as the one on a payment card, used when issue numbers are not printed on cards). 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.
</t>
<t><Extensions> (OPTIONAL), is the extension point for this entity. All extensions are grouped under this element and will be of type pskc:ExtensionType, which contains an optional attribute 'defintion' that can have a URI pointing at the defintion of the extension. In this way groups of extension can be bundled under a subelement. For example:
<figure>
<preamble/>
<artwork><![CDATA[
<Extensions>
<MyExtension1
definition="http://ACME/MyExtension1.html";>blah</Myextension1>
<YourExtension99>blahblah</YourExtension99>
</Extensions>]]></artwork>
<postamble/>
</figure>
</t>
</list>
</t>
</section>
</section>
<section anchor="KeyEntity" title="Key">
<t>The Key represents the key entity in the KeyContainer. The Key is defined as follows:</t>
<figure>
<preamble/>
<artwork><![CDATA[
<xs:complexType name="KeyType">
<xs:sequence>
<xs:element name="Issuer" type="xs:string"
minOccurs="0"/>
<xs:element name="Usage" type="pskc:UsageType"
minOccurs="0"/>
<xs:element name="KeyProfileId" type="xs:string"
minOccurs="0"/>
<xs:element name="MasterKeyId" type="xs:string"
minOccurs="0"/>
<xs:element name="FriendlyName" type="xs:string"
minOccurs="0"/>
<xs:element name="Data" type="pskc:KeyDataType"
minOccurs="0" maxOccurs="1"/>
<xs:element name="PINPolicy"
type="pskc:PINPolicyType" 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:attribute name="KeyId" type="xs:string"
use="required"/>
<xs:attribute name="KeyAlgorithm"
type="pskc:KeyAlgorithmType" use="optional"/>
<xs:attribute name="KeyProperties" type="xs:IDREF"
use="optional"/>
</xs:complexType>
]]></artwork>
<postamble/>
</figure>
<t>The attributes of the Key entity have the following meanings:
<list style="symbols">
<t>KeyId (MANDATORY), a unique and global identifier of the symmetric key. The identifier
is defined as a string of alphanumeric characters. This identifier SHOULD be valid globally and outside of the instance document of the container.</t>
<t>KeyAlgorithm (OPTIONAL), the unique URI of the type of algorithm to use with the secret key, for profiles are described in <xref target="KeyAlgorithmAttribute"/>
</t>
<t>KeyProperties (OPTIONAL), the references to the unique id of the KeyProperties whose value the instance of this key inherits. If this value is set implementation MUST lookup the Keyproperties element referred to by this unique Id and this instance of key will inherit all values from the KeyProperties. Values held in the key instance MUST take precedence over values inherited from KeyProperties."/>
</t>
</list>
</t>
<t>The elements of the Key entity have the following meanings:
<list style="symbols">
<t><Issuer> (OPTIONAL), The key issuer name, this is normally the name of the organization that issues the key to the end user of the key. For example MyBank issuing hardware tokens to their retail banking users 'MyBank' would be the issuer. The Issuer is defined as a String.</t>
<t><Usage> (OPTIONAL), defines the intended usage of the key and related metadata as defined in <xref target="UsageElement"/>
</t>
<t><KeyProfileId> (OPTIONAL), A unique identifier used between the sending and receiving party of the container to establish a set of constant values related to a key that are not transmitted via the container. 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. An example could be an EMV MasterCard CAP <xref target="CAP"/> application on a card personalised with data for a specific batch of cards such as:
<list style="hanging">
<t hangText="">IAF Internet authentication flag </t>
<t hangText="">CVN Cryptogram version number, for example (MCHIP2, MCHIP4, VISA 13, VISA14)</t>
<t hangText="">AIP (Application Interchange Profile), 2 bytes</t>
<t hangText="">TVR Terminal Verification Result, 5 bytes</t>
<t hangText="">CVR The card verification result</t>
<t hangText="">AmountOther</t>
<t hangText="">TransactionDate</t>
<t hangText="">TerminalCountryCode</t>
<t hangText="">TransactionCurrencyCode</t>
<t hangText="">AmountAuthorised</t>
<t hangText="">IIPB</t>
</list>
These values are not contained within attributes in the container but
are shared between the manufacturing and the validation service through this unique KeyProfileId. The KeyProfileId is defined as a String.</t>
<t><MasterKeyId> (OPTIONAL), The unique reference to an external master key when key derivation schemes are used and no specific key is transported but only the reference to the master key used to derive a specific key and some derivation data (e.g. the PKCS#11 key label in an HSM).</t>
<t><FriendlyName> (OPTIONAL), The user friendly name that is assigned to the secret key for easy reference. The FriendlyName is defined as a String.</t>
<t><Data> (OPTIONAL), the element carrying the data related to the key as defined in <xref target="KeyDataElement"/>
</t>
<t><PINPolicy> (OPTIONAL), the policy of the PIN relating to the usage of this key as defined in <xref target="PINPolicyElement"/>
</t>
<t><StartDate> (OPTIONAL), the start date of the key, it MUST not be possible to use this key before this date. 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.</t>
<t><ExpiryDate> (OPTIONAL), the expiry date of the key, it MUST not be possible to use this key after this date. 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.</t>
<t><UserId> (OPTIONAL), identifies the user account (e.g. username or user id) to which the key is assigned. The value MAY be a string representation of a Distinguished Name as defined in <xref target="RFC4514"/>. For example â??UID=jsmith,DC=example,DC=netâ??. In systems where unique user Ids are used the string representation 'UID=[uniqueId]' SHOULD be used.</t>
<t><Extensions> (OPTIONAL), is the extension point for this entity. All extensions are grouped under this element and will be of type pskc:ExtensionType, which contains an optional attribute 'defintion' that can have a URI pointing at the defintion of the extension. In this way groups of extension can be bundled under a subelement. For example:
<figure>
<preamble/>
<artwork><![CDATA[
<Extensions>
<MyExtension1
definition="http://ACME/MyExtension1.html";>blah</Myextension1>
<YourExtension99>blahblah</YourExtension99>
</Extensions>]]></artwork>
<postamble/>
</figure>
</t>
</list>
</t>
<section anchor="KeyDataElement" title="KeyData">
<t>Defines an extensible set of data elements relating to a key including the key value itself (secret). After considerable discussions in forums and at IETF the authors needed a mean to convey data related to a key in an extensible form. The requirements were that the data elements could be encrypted but not via XML encryption which was deemed to complex because of canonicalization. Hence earlier drafts made use of a list of name value pairs. This was not considered to be very XML like and also lacked inbuilt support for typing. Hence the current apporach is to have within KeyData a set of elements that have both typing and can be encrypted.
</t>
<t>All elements within Data hence obey a simple structure in that they MUST have:</t>
<t> a choice between:
<list style="hanging">
<t hangText="">A <PlainValue> element that is typed to the specific type (e.g. xs:integer) </t>
<t hangText="">An <EncryptedValue> element that is of type xenc:EncryptedDataType where the value of the specific element is placed in case it is encrypted</t>
</list>
</t>
<t> an optional <ValueMac> element that is populated with a MAC in case the encryption algorithm does not support integrity checks</t>
<t>For example the pskc:intDataType is defined as follows:</t>
<figure>
<preamble/>
<artwork><![CDATA[
<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>]]></artwork>
<postamble/>
</figure>
<t>The following typed base types have been defined within the current schema of the PSKC spec with the naming convention <type>DataType (e.g. intDataType) to be able to cater transmission of key data elements:
<list style="hanging">
<t hangText="">pskc:intDataType - to carry data elements of type integer, PlainValue sub element is of type xs:integer. When encrypted the binary value MUST be 4 bytes unsigned integer
in big endian (i.e. network byte order) form</t>
<t hangText="">pskc:longDataType - to carry data elements of type long, PlainValue sub element is of type xs:long. When encrypted the binary value MUST be 8 bytes unsigned integer
in big endian (i.e. network byte order) form</t>
<t hangText="">pskc:binaryDataType - to carry data elements of type binary, PlainValue sub element is of type xs:Base64Binary</t>
<t hangText="">pskc:stringDataType - to carry data elements of type string, PlainValue sub element is of type xs:string. When encrypted the binary value MUST UTF-8 encoded string in binary form</t>
</list>
</t>
<t>Therefore the KeyData element is defined as follows and contains sub ements to convey the values required by algorithms considered during the definition of this specification:</t>
<figure>
<preamble/>
<artwork><![CDATA[
<xs:complexType name="KeyDataType">
<xs:sequence>
<xs:element name="Secret" type="pskc:binaryDataType"
minOccurs="0" maxOccurs="1"/>
<xs:element name="Counter" type="pskc:longDataType"
minOccurs="0" maxOccurs="1"/>
<xs:element name="Time" type="pskc:intDataType"
minOccurs="0" maxOccurs="1"/>
<xs:element name="TimeInterval" type="pskc:intDataType"
minOccurs="0" maxOccurs="1"/>
<xs:element name="TimeDrift" type="pskc:intDataType"
minOccurs="0" maxOccurs="1"/>
<xs:any namespace="##other" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
]]></artwork>
<postamble/>
</figure>
<t>The elements of the Data element have the following meanings:
<list style="symbols">
<t><Secret> (OPTIONAL), the value of the key itself in binary.</t>
<t><Counter> (OPTIONAL), the event counter for event based OTP algorithms.</t>
<t><Time> (OPTIONAL), 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)</t>
<t><TimeInterval> (OPTIONAL), the time interval value for time based OTP algorithms.</t>
<t><TimeDrift> (OPTIONAL), the device clock drift value for time based OTP algorithms. The value indicates number of seconds that the device clock may drift each day. </t>
<t><xs:any ..> the extension point for carrying future elements. Please note that all elements added MUST carry PlainValue and EncryptedValue sub eleemnts as described above.</t>
</list>
</t>
</section>
<section anchor="UsageElement" title="Usage">
<t>The Usage element defines the