Re: [KEYPROV] [pskc] Latest draft of PSKC

Please find attached the latest work in progress draft and related schema,

Changes made from version 4 are:

Added optional Id element to the container in case another document includes more than one container and wants to reference it uniquely, this is of type xs:Id
Made PINKeyId of PINPolicy optional (in version 4 it wrongly became mandatory)
Changed KeyPropertiesType:KeyPropertiesId from type xs:String to xs:ID
Changed KeyType:KeyPropertiesId from type xs:string to be of type xs:IDREF as it refers to the ID of the element of (3) see directly above
Added optional PINPolicyId attribute of type xs:ID to PINPolicyType
Added the KeyContainer:KeyProperties element that was missing from version -04 (oversight).This is where the common properties for a key are actually held within a container
Changed PINPolicyType: WrongPINtry into WrongPINTry so that it is proper camel-case

Extension points:

Added a ‘<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>’ to

KeyContainerType
KeyPropertiesType
KeyType
PINPolicy
DeviceIDType
DeviceType
UsageType

Added a ‘<xs:anyAttribute namespace="##other"/>’ to:

UsageType (since it contains the attributes of ‘

<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:

Should we make KeyType:KeyId of type xs:ID instead of xs:string
Should we make KeyType:KeyProfileId and KeyProperties:KeyProfileId of type xs:ID instead of xs:string
For all the uses of xs:ID should we add facets of minlength, maxlength and whitespace? Or do we just have standard
Should we go for xs:string for unencrypted data elements – Rob Philpott and others seem strongly for it but Sean Turner was against it at the last IETF in Philadelphia
Where else do we need ‘<anyAttribute namespace="##other" processContents="lax"/>’ as extension points
For the added ‘<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>’ do we need a description within the spec or do we just leave them in the parts of the schema fragments throughout the spec as obvious extension points?
Address other issues raised by Rob Philpott: Here below with my comments and numbered Rob Philpott Comment plus number (RPC1, RPC2, … etc)

RPC1. The use of the DeviceIdType is inconsistent with other “ID”’s (that are used for referential information). The elements in the DeviceIDType seem more appropriate for the DeviceType or KeyType elements. At a minimum, I would not call this a “DeviceIdType” (perhaps “DeviceInfoType”?) but really, I would just put its elements directly in the DeviceType complexType). I would also give <Device> elements an optional referential ID via xs:ID.

[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. Also since there are already implementations out there changing this would make it incompatible.

RPC2. We are really unhappy with the proposed extensibility mechanism. This goes against general XML schema best practice. Defining extension points via xs:any/xs:anyAttribute is vastly superior (IMO):

[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.

RPC3. The use of “Reserved data attribute names” as described in section 7 is really difficult to work with. First, <Data> elements should ONLY be used for “real” extensions… i.e. things that aren’t already known at the time the spec is written. If we already know that the items defined in section 7 are needed, they should just be defined in the schema with their own element/attribute definitions. They should not be “reserved” uses of the <DATA> element. We just don’t understand the desire to do it this way. Having explicitly defined elements also allows for more flexible datayping.

[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

RPC4. This mechanism only lets us create very simple name-value pair extensions. If we have some small groups of related extensions, we’d really like to be able to define them externally in a private schema via their own complexType definitions. With the current method, it’s going to be very messy to add groups of extensions or extensions that have more complex data values.

[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.

RPC5 In general, it is undesirable to create abbreviations such as “InAlgo” (in PINUsageMode) to be used as XML keywords. To stay consistent with “Local” and “Prepend”, I would strongly suggest something like “Embed” or “Algorithmic”.
[PH[ we had Embed before and people got confused by the meaning. So maybe Algorithmic is a better choice, that is why I tried to express the use of the PIN in the algorithm as InAlgo. I do not feel very strong about it. Maybe we can have a vote

Philip

From: andrea.doherty at rsa.com [mailto:andrea.doherty at rsa.com]
Sent: Friday, May 30, 2008 4:36 PM
To: keyprov at ietf.org
Cc: Philip Hoyer
Subject: FW: [KEYPROV] [pskc] Latest draft of PSKC

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

1. Use of xs:ID attributes:

a. The xs:ID datatype is only used in the DerivedKeyType complexType. xs:ID is the preferred mechanism for referring to other XML elements in an instance document. So why are custom attributes defined to be able to referto elements of the types KeyPropertiesType (the “KeyPropertiesId” attribute) and KeyType (“KeyId”)? Why don’t these use xs:ID attributes?

[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?

b. Why doesn’t a KeyContainer have an (optional) ID that could be used to reference it in an instance document?

[PH] valid comment and I will think we should add this

c. Same question for PINPolicy?

[PH] agreed

d. The use of the DeviceIdType is inconsistent with other “ID”’s (that are used for referential information). The elements in the DeviceIDType seem more appropriate for the DeviceType or KeyType elements. At a minimum, I would not call this a “DeviceIdType” (perhaps “DeviceInfoType”?) but really, I would just put its elements directly in the DeviceType complexType). I would also give <Device> elements an optional referential ID via xs:ID.

e. Section 5.2.1 says that the DeviceIdType is an extensible type, but there are no extension points in it.

[PH] agreed I think we should add an xs:any

2. We are really unhappy with the proposed extensibility mechanism. This goes against general XML schema best practice. Defining extension points via xs:any/xs:anyAttribute is vastly superior (IMO):

a. The use of “Reserved data attribute names” as described in section 7 is really difficult to work with. First, <Data> elements should ONLY be used for “real” extensions… i.e. things that aren’t already known at the time the spec is written. If we already know that the items defined in section 7 are needed, they should just be defined in the schema with their own element/attribute definitions. They should not be “reserved” uses of the <DATA> element. We just don’t understand the desire to do it this way. Having explicitly defined elements also allows for more flexible datayping.

b. This mechanism only lets us create very simple name-value pair extensions. If we have some small groups of related extensions, we’d really like to be able to define them externally in a private schema via their own complexType definitions. With the current method, it’s going to be very messy to add groups of extensions or extensions that have more complex data values.

c. It is also a pain for implementers to deal with the limitation of the data typing available for unencrypted <Data> elements. For example, for a SecurID token with a display interval of 60 seconds, I cannot simply use an xml schema-defined datatype of xs:integer with a value of “60”. I have to Base64-encode the big-endian 2-byte binary value for 60 seconds (and then decode it on the receiving end). Why is this necessary? I could define such an item with a single XML element, but here I need 3 or 4.

[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?

d. This approach does not produce “readable” XML since the data values are always Base64-encoded. That is just crazy when the data is not sensitive in nature. Please do not underestimate the value of being able to look at data in an instance document and know what it is without having to run it through a Base64 decoder! This is a major drawback.

[PH] agreed and see answer above

3. RE: PINPolicy:

a. If I specify a PINPolicy, I am forced to specify a PINKeyID, which forces me to create another Key element (even if I don’t have any additional PIN policy info that I need to pass along in that Key element). For 90% of the use cases, this referential style of description is overkill and makes the instance document much more complex than it needs to be.

[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.

b. The PINPolicy element only contains “policy” attributes for “WrongPINtry” and “PINUsageMode” and the element is not directly extensible. Any extensions we need have to go in Data elements inside a separate Key element that the PINPolicy then references. IMO, PIN policy info should be in the PINPolicy element, not in a separate “Key” element! The only thing that should go in the Key element is a PIN value that is being expressly communicated with the instance document. That is, a PIN value IS a key; PIN policy information IS NOT a key.

[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?

c.       It seems to us that there are additional universally-known PIN policy attributes that should be included in the schema. Things such as the PIN’s maximum and minimum length and it’s data type (integer, alphanumeric). Unless these are part of the spec, we currently are forced to create custom Data elements for them (and put them in a referenced Key element). BTW – Just to be clear, I am talking about the POLICY information associated with whatever PIN a user uses with their token. I’m not talking about the attributes of a specific PIN value that can be expressed in a Key element. As an example, to express a min and max PIN length policy, we have to create custom Data elements in a separate Key element (and also Base64 encode the values). I’m sorry, but this is getting ridiculous.

           <Key KeyId="07552252661"

             KeyAlgorithm="http://www.ietf.org/keyprov/pskc#pin">

              <Data Name="PIN_MIN_LENGTH">

                  <PlainValue>NA==</PlainValue>

              </Data>

              <Data Name="PIN_MAX_LENGTH">

                  <PlainValue>OA==</PlainValue>

              </Data>

           </Key>

[PH] no the format and length would be in the UsageElement of the PINKey. I had hoped Example (Section 12.2 of the spec) would make that clear here is the XML fragment:

<Key KeyId="07552252661"

KeyAlgorithm="http://www.ietf.org/keyprov/pskc#pin">

<Usage>

</Usage>

<PlainValue>MTIzNA==</PlainValue>

</Data>

        </Key>

Notes:

a.       If I had an xs:any extension point, I could express this in 2 lines of XML in the PinPolicy element.

b.      This example doesn’t include the PIN format, which would require me to either:

                                                                     i.            Use another custom Data element

                                                                   ii.            Include a ResponseFormat element that then requires inclusion of a “Length” attribute. But what would the Length attribute really mean in this case?

d.      Why isn’t a PINPolicy reusable across multiple tokens (it has no ID that can be used in a reference from a token definition). If I want to define a PINPolicy that applies to multiple tokens, the PINPolicy element needs its own ID.

[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.

e. The “WrongPINtry” element name (in PINPolicyType) is not consistent with the other camel-case names (“try” should be “Try”).

[PH] agreed, will change

f. In general, it is undesirable to create abbreviations such as “InAlgo” (in PINUsageMode) to be used as XML keywords. To stay consistent with “Local” and “Prepend”, I would strongly suggest something like “Embed” or “Algorithmic”.
[PH[ we had Embed before and people got confused by the meaning. So maybe Algorithmic is a better choice, that is why I tried to express the use of the PIN in the algorithm as InAlgo. I do not feel very strong about it. Maybe we can have a vote

4. The use of “ResponseFormat” for describing a PIN is very confusing. The spec defines ResponseFormat as follows “The ResponseFormat element defines the characteristics of the result of a computation. This defines the format of the OTP or of the response to a challenge.” A PIN is not the result of a “computation”, nor is it a response to a challenge. It seems quite odd to use this Key construct for a PIN. I think that either another usage type should be defined or the ResponseFormat definition should be changed to also reflect its use for describing a PIN.
[PH] Yes I think we need to change the description. I am getting a lot of push back to include PIN requirements in the spec so I tried to convince people that tit was a good idea without having to introduce to many new schema types. Here you say it is odd to use the Key element for the PIN value but above you agree that a PIN IS a Key. So I would keep it in the Key element buy change description.

<?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>109 Borough High Street</street> <city>London</city> <region>SE1</region> <code>1NL</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="18" month="June" 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 a symmetric keys such as an OTP shared secret or an encryption key 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="Device ID (DeviceId):">A unique identifier for the device, representing the identifying criteria to uniquely identify a device</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 Crypto Module"> <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 Crypto Module to Crypto Module"> <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 Crypto Module 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, crypto 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.</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>Device entity as defined in <xref target="DeviceEntity"/> </t> <t>KeyProperties entity as defined in <xref target="KeyPropertiesEntity"/> </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 section 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="Device" type="pskc:DeviceType" maxOccurs="unbounded"/> <xs:element name="KeyProperties" type="pskc:KeyPropertiesType" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="Signature" type="ds:SignatureType" minOccurs="0"/> <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:attribute name="Version" type="pskc:VersionType" use="required"/> <xs:attribute name="KeyContainerID" 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><KeyContainerID (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 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><Device>, 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><KeyProperties (OPTIONAL)>, one or more 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. </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> </list> </t> </section> <section anchor="DeviceEntity" title="Device"> <t>The Device represents the Device entity in the Container. A Device MAY be bound to a user and MAY contain more than one keys. 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="DeviceId" type="pskc:DeviceIdType" minOccurs="0"/> <xs:element name="Key" type="pskc:KeyType" maxOccurs="unbounded"/> <xs:element name="UserId" type="xs:string" minOccurs="0"/> <xs:any namespace="##other" processContents="lax" 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><DeviceId>, a unique identifier for the device, defined in <xref target="DeviceIdElement"/> </t> <t><Key>, represents the key entity as defined in <xref target="KeyEntity"/> </t> <t><UserId>, optionally 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]' MUST be used.</t> </list> </t> <section anchor="DeviceIdElement" title="DeviceId"> <t>The DeviceId represents 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. DeviceId is an extensible type that allows all these different ways to uniquely identify a specific key containing device.</t> <t>The DeviceId is defined as follows:</t> <figure> <preamble/> <artwork><![CDATA[ <xs:complexType name="DeviceIdType"> <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="ExpiryDate" type="xs:dateTime" minOccurs="0"/> <xs:element name="StartDate" type="xs:dateTime" minOccurs="0"/> <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> ]]></artwork> <postamble/> </figure> <t>The elements of DeviceId have the following meanings: <list style="symbols"> <t><Manufacturer>, the manufacturer of the device.</t> <t><SerialNo>, the serial number of the device or the PAN (primary account number) in case of payment smart cards.</t> <t><Model>, the model of the device (e.g one-button-HOTP-token-V1)</t> <t><IssueNo>, the issue number in case of smart cards with the same PAN, equivalent to a PSN (PAN Sequence Number).</t> <t><ExpiryDate>, the expiry date of a device (such as the one on a payment card,used when issue numbers are not printed on cards).</t> <t><StartDate>, the start date of a device (such as the one on a payment card,used when issue numbers are not printed on cards).</t> </list> </t> </section> </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 KeyPropertiesId attribute. Values that are present in the Key element itself MUST take precendence 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:DataType" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="PINPolicy" type="pskc:PINPolicyType" minOccurs="0"/> <xs:element name="ExpiryDate" type="xs:dateTime" minOccurs="0"/> <xs:element name="StartDate" type="xs:dateTime" minOccurs="0"/> <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:attribute name="KeyPropertiesId" 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>KeyPropertiesId (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 the secret key, for profiles are described in <xref target="KeyAlgorithmAttribute"/> </t> </list> </t> <t>Since KeyProperties are a method to commonalise the elements in Key please refer to section <xref target="KeyEntity"/> for detailed description of all elements. </t> </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:DataType" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="PINPolicy" type="pskc:PINPolicyType" minOccurs="0"/> <xs:element name="ExpiryDate" type="xs:dateTime" minOccurs="0"/> <xs:element name="StartDate" type="xs:dateTime" minOccurs="0"/> <xs:any namespace="##other" processContents="lax" 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="KeyPropertiesId" 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.</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><KeyPropertiesId (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 it 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 (MANDATORY)>, 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 a 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.</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="DataAttribute"/> </t> <t><PINPolicy (OPTIONAL)>, the policy of the PIN relating to the usage of this key as defined in <xref target="PINPolicyElement"/> </t> <t><ExpiryDate (OPTIONAL)>, the expiry date of the key, it MUST not be possible to use this key after this date</t> <t><StartDate (OPTIONAL)>, the start date of the key, it MUST not be possible to use this key before this date</t> </list> </t> <section anchor="DataAttribute" title="Data (OPTIONAL)"> <t>Defines the data attributes of the symmetric key. Each is a name value pair which has either a plain value (in case of no encryption) or a encrypted value as defined in EncryptedDataType in XML Encryption. </t> <t>This is also where the key value is transported, <xref target="DataAttributeNames"/> defines a list of reserved attribute names. </t> <t>Data element is defined as follows:</t> <figure> <preamble/> <artwork><![CDATA[ <xs:complexType name="DataType"> <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:attribute name="Name" type="xs:string" use="required"/> </xs:complexType> ]]></artwork> <postamble/> </figure> <t>The attributes of the Data element have the following meanings: <list style="symbols"> <t>Name, defines the name of the name-value pair, <xref target="DataAttributeNames"/> defines a list of reserved attribute names</t> </list> </t> <t>The elements of the Data element have the following meanings: <list style="symbols"> <t>The <PlainValue> conveys an unencrypted value of the name-value pair in base 64 encoding.</t> <t>The <EncryptedValue> element in the DataType conveys an encrypted value of the name-value pair inside an EncryptedDataType as defined in XML Encryption.</t> <t>The <ValueMAC (OPTIONAL)> element in the DataType conveys a keyed MAC value of the unencrypted data for the cases where the algorithm to protect key data in transit, as described in section <xref target="SymmetricKeyProtectionDescription"/> ,does not support integrity checks.</t> </list> </t> </section> <section anchor="UsageElement" title="Usage (MANDATORY)"> <t>The Usage element defines the usage attribute(s) of the key entity. Usage is defined as follows:</t> <figure> <preamble/> <artwork><![CDATA[ <xs:complexType name="UsageType"> <xs:sequence> <xs:element name="ChallengeFormat" minOccurs="0"> <xs:complexType> <xs:attribute name="Format" 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"> <xs:complexType> <xs:attribute name="Format" 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:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <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"/> <xs:anyAttribute namespace="##other"/> </xs:complexType> ]]></artwork> <postamble/> </figure> <t>The attributes of the Usage element define the intended usage of the key and are a combination of one or more of the following (set to true): <list style="symbols"> <t>OTP, the key will be used for OTP generation</t> <t>CR, the key will be used for Challenge/Response purposes</t> <t>Encrypt, the key will be used for data encryption purposes</t> <t>Integrity, the key will be used to generate a keyed message digest for data integrity or authentication purposes.</t> <t>Unlock, the key will be used for an inverse challenge response in the case a user has locked the device by entering a wrong PIN too many times (for devices with PIN-input capability)</t> </list> </t> <section title="OTP and CR specific Usage elements (OPTIONAL)"> <t>When the intended usage of a key usage is OTP and/or CR, the following additional elements MUST be provided within the Usage element to support the OTP and/or the response computation as required by the underlying algorithm. These elements also allow to customize or configure the result of the computation (e.g. format, length).</t> <section title="ChallengeFormat element (MANDATORY)"> <t>The ChallengeFormat element defines the characteristics of the challenge in a CR usage scenario. The Challenge element is defined by the following attributes: <list style="symbols"> <t>Format (MANDATORY) <list style="hanging"> <t hangText="">Defines the format of the challenge accepted by the device and MUST be one of the values defined in <xref target="ValueFormat"/> </t> </list> </t> <t>CheckDigit (OPTIONAL) <list style="hanging"> <t hangText="">Defines if the device needs to check the appended Luhn check digit contained in a provided challenge. This is only valid if the Format attribute is 'DECIMAL'. Value MUST be: <list style="hanging"> <t hangText="">TRUE device will check the appended Luhn check digit in a provided challenge </t> <t hangText="">FALSE device will not check appended Luhn check digit in challenge</t> </list> </t> </list> </t> <t>Min (MANDATORY) <list style="hanging"> <t hangText="">Defines the minimum size of the challenge accepted by the device for CR mode.</t> <t>If the Format attribute is 'DECIMAL', 'HEXADECIMAL' or 'ALPHANUMERIC' this value indicates the minimum number of digits/characters.</t> <t>If the Format attribute is 'BASE64' or 'BINARY', this value indicates the minimum number of bytes of the unencoded value.</t> <t>Value MUST be:</t> <t> <list style="hanging"> <t hangText="">Unsigned integer.</t> </list> </t> </list> </t> <t>Max (MANDATORY) <list style="hanging"> <t hangText="">Defines the maximum size of the challenge accepted by the device for CR mode.</t> <t>If the Format attribute is 'DECIMAL', 'HEXADECIMAL' or 'ALPHANUMERIC' this value indicates the maximum number of digits/characters.</t> <t>If the Format attribute is 'BASE64' or 'BINARY', this value indicates the maximum number of bytes of the unencoded value.</t> <t>Value MUST be:</t> <t> <list style="hanging"> <t hangText="">Unsigned integer.</t> </list> </t> </list> </t> </list> </t> </section> <section title="ResponseFormat element (MANDATORY)"> <t>The ResponseFormat element defines the characteristics of the result of a computation. This defines the format of the OTP or of the response to a challenge. For cases where the key is a PIN value this element contains the format of the PIN itself. The Response attribute is defined by the following attributes: <list style="symbols"> <t>Format (MANDATORY) <list style="hanging"> <t hangText="">Defines the format of the response generated by the device and MUST be one of the values defined in <xref target="ValueFormat"/> </t> </list> </t> <t>CheckDigit (OPTIONAL) <list style="hanging"> <t hangText="">Defines if the device needs to append a Luhn check digit to the response. This is only valid if the Format attribute is 'DECIMAL'. Value MUST be: <list style="hanging"> <t hangText="">TRUE device will append a Luhn check digit to the response. </t> <t hangText="">FALSE device will not append a Luhn check digit to the response.</t> </list> </t> </list> </t> <t>Length (MANDATORY) <list style="hanging"> <t hangText="">Defines the length of the response generated by the device.</t> <t>If the Format attribute is 'DECIMAL', 'HEXADECIMAL' or 'ALPHANUMERIC' this value indicates the number of digits/characters.</t> <t>If the Format attribute is 'BASE64' or 'BINARY', this value indicates the number of bytes of the unencoded value.</t> <t>Value MUST be:</t> <t> <list style="hanging"> <t hangText="">Unsigned integer. </t> </list> </t> </list> </t> </list> </t> </section> </section> </section> <section anchor="ValueFormat" title="ValueFormat"> <t>The ValueFormat element defines allowed formats for challenges or responses in OTP algorithms.</t> <t>ValueFormat is defined as follows:</t> <figure> <preamble/> <artwork><![CDATA[ <simpleType name="ValueFormat"> <restriction base="string"> <enumeration value="DECIMAL"/> <enumeration value="HEXADECIMAL"/> <enumeration value="ALPHANUMERIC"/> <enumeration value="BASE64"/> <enumeration value="BINARY"/> </restriction> </simpleType> ]]></artwork> <postamble/> </figure> <t> <list style="hanging"> <t hangText="">DECIMAL Only numerical digits</t> <t hangText="">HEXADECIMAL Hexadecimal response</t> <t hangText="">ALPHANUMERIC All letters and numbers (case sensitive)</t> <t hangText="">BASE64 Base 64 encoded</t> <t hangText="">BINARY Binary data, this is mainly used in case of connected devices</t> </list> </t> </section> <section anchor="PINPolicyElement" title="PINPolicy"> <t>The PINPolicy element provides a mean to define how the usage of a specific key is protected by a PIN. The PIN itself can be transmitted as a key using the container.</t> <t>If the PINPolicy element is present in the Key element then the key is protected with a PIN as defined within the PINPolicy element.</t> <t>PINPolicy is defined as follows:</t> <figure> <preamble/> <artwork><![CDATA[ <xs:complexType name="PINPolicyType"> <xs:sequence> <xs:element name="PINUsageMode" type="pskc:PINUsageModeType"/> <xs:element name="WrongPINTry" type="xs:unsignedInt" minOccurs="0"/> <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:attribute name="PINPolicyId" type="xs:ID" use="optional"/> <xs:attribute name="PINKeyId" type="xs:string" use="optional"/> </xs:complexType> ]]></artwork> <postamble/> </figure> <t> The attributes of PINPolicy have the following meaning <list style="symbols"> <t>PINPolicyId (OPTIONAL), the unique Id of this PINPolicy within this container </t> <t>PINKeyId (OPTIONAL), the unique key Id within this container that contains the value of the PIN that protects the key</t> </list> </t> <t> The elements of PINPolicy have the following meaning <list style="symbols"> <t><PINUsageMode (MANDATORY)> , the way the PIN is used during the usage of the key as defined in <xref target="PINUsageModeElement"/></t> <t><WrongPINTry (OPTIONAL)>, the number of times the PIN can be entered wrongly before it MUST not be possible to use the key anymore</t> </list> </t> <section anchor="PINUsageModeElement" title="PINUsageMode"> <t>The PINUsageMode element defines how the PIN is used with a specific key</t> <t>PINUsageMode is defined as follows:</t> <figure> <preamble/> <artwork><![CDATA[ <xs:complexType name="PINUsageModeType"> <xs:choice maxOccurs="unbounded"> <xs:element name="Local"/> <xs:element name="Prepend"/> <xs:element name="InAlgo"/> <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/> </xs:choice> </xs:complexType> ]]></artwork> <postamble/> </figure> <t> The elements of PINPolicy have the following meaning <list style="symbols"> <t><Local>, the PIN is checked locally on the device before allowing the key to be used in executing the algorithm</t> <t><Prepend>, the PIN is prepended to the OTP or response hance it MUST be chacked by the validation server</t> <t><InAlgo>, the PIN is used as part of the algorithm computation</t> </list> </t> </section> </section> </section> </section> <section anchor="SecurityAlgorithmDescription" title="Usage and profile of algorithms for the portable symmetric key container"> <t>This section details the use of the XML encryption and XML signature elements to protect the keys transported in the cotainer. It also profiles the number of algorithms supported by XML encryption and XML signature to a mandatory subset for interoperability. </t> <t>When no algorithm is provided the values within the container are unencrypted, implementations SHALL ensure the privacy of the key data through other standard mechanisms e.g. transport level encryption.</t> <section anchor="EncryptionKeyDescription" title="Usage of EncryptionKey to protect keys in transit"> <t>The EncryptionKey element in the KeyContainer defines the key, algorithm and parameters used to encrypt the Secret Key data attributes in the Container. The standard schema <xref target="XMLENC"/> is adopted in carry such information and an encrypted value. The encryption is applied on each individual Secret Key data in the Container. The encryption method MUST be the same for all Secret Key data in the container. </t> <t>The following sections define specifically the different supported means to protect the keys: </t> <section anchor="SymmetricKeyProtectionDescription" title="Protecting keys using a pre-shared key via symmetric algorithms"> <t>When protecting the payload with pre-shared keys implementations SHOULD set the name of the specific pre-shared key in the KeyName element of the EncryptionKey of the KeyContainer. For example: <figure> <preamble/> <artwork><![CDATA[ <KeyContainer Version="1.0" xmlns="urn:ietf:params:xml:ns:keyprov:container:1.0" 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> .... ]]></artwork> <postamble/> </figure> </t> <t> The following is the list of symmetric key encryption algorithm and possible parameters used to protect the Secret Key data in the container. Systems implementing PSKC MUST support the MANDATORY algorithms detailed below.</t> <t>The encryption algorithm URI can be one of the following. <list style="symbols"> <t>http://www.w3.org/2001/04/xmlenc#tripledes-cbc - MANDATORY</t> <t>http://www.w3.org/2001/04/xmlenc#aes128-cbc - MANDATORY</t> <t>http://www.w3.org/2001/04/xmlenc#aes192-cbc - OPTIONAL</t> <t>http://www.w3.org/2001/04/xmlenc#aes256-cbc - MANDATORY</t> <t>http://www.w3.org/2001/04/xmlenc#kw-tripledes - MANDATORY</t> <t>http://www.w3.org/2001/04/xmlenc#kw-aes128 - MANDATORY</t> <t>http://www.w3.org/2001/04/xmlenc#kw-aes256 - MANDATORY</t> <t>http://www.w3.org/2001/04/xmlenc#kw-aes512 - OPTIONAL</t> </list> </t> <t>When algorithms without integrity checks are used (e.g. http://www.w3.org/2001/04/xmlenc#aes256-cbc) a keyed MAC value using the same key as the encryption key SHOULD be placed in the ValueMAC element of the Data element. In this case the MAC algorithm type MUST be set in the MACAlgorithm element in the key container entity as defined in <xref target="KeyContainerEntity"/>. Implementations of PSKC MUST support the MANDATORY MAC algorithms detailed below. The MACAlgorithm URI can be one of the following: <list style="symbols"> <t>http://www.w3.org/2000/09/xmldsig#hmac-sha1 - MANDATORY</t> </list> For example: <figure> <preamble/> <artwork><![CDATA[ <KeyContainer Version="1.0" xmlns="urn:ietf:params:xml:ns:keyprov:container:1.0" 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> <MACAlgorithm>http://www.w3.org/2000/09/xmldsig#hmac-sha1 </MACAlgorithm> ..... ]]></artwork> <postamble/> </figure> </t> </section> <section title="Protecting keys using passphrase based encryption keys"> <t>To be able to support passphrase based encryption keys as defined in PKCS#5 the following XML representation of the PBE relates parameters have been introduced in the schema. Although the approach is extensible implementations of PSKC MUST support the KeyDerivationMethod algorithm URI of http://www.rsasecurity.com/rsalabs/pkcs/schemas/pkcs-5#pbkdf2. </t> <figure> <preamble/> <artwork><![CDATA[ <xs:complexType name="DerivedKeyType"> <xs:sequence> <xs:element name="KeyDerivationMethod" type="pskc:KeyDerivationMethodType" minOccurs="0"/> <xs:element ref="xenc:ReferenceList" minOccurs="0"/> <xs:element name="CarriedKeyName" type="xs:string" minOccurs="0"/> </xs:sequence> <xs:attribute name="Id" type="xs:ID" use="optional"/> <xs:attribute name="Type" type="xs:anyURI" use="optional"/> </xs:complexType> <xs:complexType name="KeyDerivationMethodType"> <xs:sequence> <xs:any namespace="##other" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:attribute name="Algorithm" type="xs:anyURI" use="required"/> </xs:complexType> ]]></artwork> <postamble/> </figure> <t>The attributes of the DerivedKey have the following meanings: <list style="symbols"> <t>ID (OPTIONAL), the unique ID for this key</t> <t>Type (OPTIONAL), This attribute was included for conformance with xml encryption, it is an optional attribute identifying type information about the plaintext form of the encrypted content. Please see <xref target="XMLENC"/> section 3.1 Type for more details.</t> </list> </t> <t>The elements of the DerivedKey have the following meanings: <list style="symbols"> <t><KeyDerivationMethod>: URI of the algorithms used to derive the key e.g. (http://www.rsasecurity.com/rsalabs/pkcs/schemas/pkcs-5#pbkdf2)</t> <t><ReferenceList (OPTIONAL)>: a list of IDs of the elements that have been encrypted by this key</t> <t><CarriedKeyName (OPTIONAL)>: friendly name of the key</t> </list> </t> <t> When using the PKCS5 PBE algorithm (URI=http://www.rsasecurity.com/rsalabs/pkcs/schemas/pkcs-5#pbes2) and related parameters, the DerivedKey element MUST be used within the EncryptionKey element of the KeyContainer in exactly the form as shown below: <figure> <preamble/> <artwork><![CDATA[ <?xml version="1.0" encoding="UTF-8"?> <KeyContainer xmlns="urn:ietf:params:xml:ns:keyprov:container:1.0" xmlns:pkcs-5= "http://www.rsasecurity.com/rsalabs/pkcs/schemas/pkcs-5v2-0#"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; xmlns:ds="http://www.w3.org/2000/09/xmldsig#"; xmlns:xenc="http://www.w3.org/2001/04/xmlenc#"; Version="1.0"> <EncryptionKey> <DerivedKey Id="#Passphrase1"> <CarriedKeyName>Passphrase1</CarriedKeyName> <KeyDerivationMethod Algorithm= "http://www.rsasecurity.com/rsalabs/pkcs/schemas/pkcs-5#pbkdf2";> <Parameters xsi:type="pkcs-5:PBKDF2ParameterType"> <Salt> <Specified>Df3dRAhjGh8=</Specified> </Salt> <IterationCount>2000</IterationCount> <KeyLength>16</KeyLength> <PRF/> </Parameters> </KeyDerivationMethod> </DerivedKey> </EncryptionKey> .... ]]></artwork> <postamble/> </figure> </t> </section> </section> <section title="Protecting keys using asymmetric algorithms"> <t>The following is the list of asymmetric key encryption algorithm and possible parameters used to protect the Secret Key data in the container. Systems implementing PSKC MUST support the MANDATORY algorithms detailed below. The encryption algorithm URI can be one of the following. <list style="symbols"> <t>http://www.w3.org/2001/04/xmlenc#rsa-1_5 - MANDATORY</t> <t>http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p - OPTIONAL</t> </list> </t> <t> For example: <figure> <preamble/> <artwork><![CDATA[ <?xml version="1.0" encoding="UTF-8"?> <pskc:KeyContainer Version="1.0" xmlns:pskc="urn:ietf:params:xml:ns:keyprov:container:1.0" xmlns:ds="http://www.w3.org/2000/09/xmldsig#"; xmlns:xenc="http://www.w3.org/2001/04/xmlenc#";> <pskc:EncryptionKey> <ds:X509Data> <ds:X509Certificate>miib</ds:X509Certificate> </ds:X509Data> </pskc:EncryptionKey> <pskc:Device> <pskc:DeviceId> <pskc:Manufacturer>ACME</pskc:Manufacturer> <pskc:SerialNo>0755225266</pskc:SerialNo> </pskc:DeviceId> <pskc:Key KeyAlgorithm= "http://www.ietf.org/keyprov/pskc#hotp"; KeyId="0755225266"> <pskc:Issuer>AnIssuer</pskc:Issuer> <pskc:Usage OTP="true"> <pskc:ResponseFormat Length="8" Format="DECIMAL"/> </pskc:Usage> <pskc:Data Name="COUNTER"> <pskc:PlainValue>AprkuA==</pskc:PlainValue> </pskc:Data> <pskc:Data Name="SECRET"> <pskc:EncryptedValue Id="ED"> <xenc:EncryptionMethod Algorithm= "http://www.w3.org/2001/04/xmlenc#rsa_1_5"/> <xenc:CipherData> <xenc:CipherValue>rf4dx3rvEPO0vKtKL14NbeVu8nk= </xenc:CipherValue> </xenc:CipherData> </pskc:EncryptedValue> </pskc:Data> </pskc:Key> </pskc:Device> </pskc:KeyContainer>]]></artwork> <postamble/> </figure> </t> </section> <section anchor="KeyAlgorithmAttribute" title="Profile of Key Algorithm"> <t>This section profiles the type(s) of algorithm of that can be used by the key(s) transported in the container. The following algorithm URIs are among the default support list. <list style="symbols"> <t>http://www.w3.org/2001/04/xmlenc#tripledes-cbc</t> <t>http://www.w3.org/2001/04/xmlenc#aes128-cbc</t> <t>http://www.w3.org/2001/04/xmlenc#aes192-cbc</t> <t>http://www.w3.org/2001/04/xmlenc#aes256-cbc</t> <t>http://www.ietf.org/keyprov/pskc#hotp</t> <t>http://www.ietf.org/keyprov/pskc#pin</t> </list> </t> <section anchor="OTPAlgorithm" title="OTP Key Algorithm Identifiers"> <t>OTP key algorithm URIs have not been defined in a commonly available standard specification. This document defines the following URIs for the standard OTP algorithms defined in <xref target="HOTP"/>.</t> <section anchor="HOTPOTPAlgorithm" title="HOTP"> <t>Standard document: RFC4226</t> <t>Identifier: http://www.ietf.org/keyprov/pskc#hotp</t> <t>Note that the actual URL will be finalized once a URL for this document is determined.</t> </section> <section anchor="VendorOTPAlgorithm" title="Other OTP Algorithms"> <t>An implementation should refer to vendor registered OTP key algorithm URIs for other existing OTP algorithms, for example, the RSA SecurID OTP algorithm as follows. <list style="symbols"> <t>http://www.rsa.com/rsalabs/otps/schemas/2005/09/otps-wst#SecurID-AES</t> </list> </t> </section> </section> <section anchor="ValueCompareAlgorithm" title="PIN key value compare algorithm identifier"> <t>PIN key algorithm URIs have not been defined in a commonly available standard specification. This document defines the following URIs for a straight value comaprison of the transported secret key data as when required to compare a PIN.</t> <t>Identifier: http://www.ietf.org/keyprov/pskc#pin</t> <t>Note that the actual URL will be finalized once a URL for this document is determined.</t> </section> </section> </section> <section anchor="DataAttributeNames" title="Reserved data attribute names"> <t>The following key data attribute names have been reserved: <list style="hanging"> <t hangText="">SECRET: the shared secret key value in binary, base64 encoded</t> <t hangText="">COUNTER: the event counter for event based OTP algorithms. 8 bytes unsigned integer in big endian (i.e. network byte order) form base64 encoded</t> <t hangText="">TIME: the time for time based OTP algorithms. 8 bytes unsigned integer in big endian (i.e. network byte order) form base64 encoded (Number of seconds since 1970)</t> <t hangText="">TIME_INTERVAL: the time interval value for time based OTP algorithms. 8 bytes unsigned integer in big endian (i.e. network byte order) form base64 encoded.</t> <t hangText="">TIME_DRIFT: the device clock drift value for time based OTP algorithms. The value indicates number of seconds that the device clock may drift each day. 2 bytes unsigned integer in big endian (i.e. network byte order) form base64 encoded.</t> </list> </t> </section> <section anchor="schema" title="Formal Syntax"> <t>The following syntax specification uses the widely adopted XML schema format as defined by a W3C recommendation (http://www.w3.org/TR/xmlschema-0/). It is a complete syntax definition in the XML Schema Definition format (XSD)</t> <t>All implementations of this standard must comply with the schema below.</t> <figure> <preamble/> <artwork><![CDATA[ <?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:container:1.0" 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:container:1.0" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.0"> <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/ xmlenc-core/xenc-schema.xsd"/> <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="Device" type="pskc:DeviceType" maxOccurs="unbounded"/> <xs:element name="KeyProperties" type="pskc:KeyPropertiesType" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="Signature" type="ds:SignatureType" minOccurs="0"/> <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:attribute name="Version" type="pskc:VersionType" use="required"/> <xs:attribute name="KeyContainerID" 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="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:DataType" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="PINPolicy" type="pskc:PINPolicyType" minOccurs="0"/> <xs:element name="ExpiryDate" type="xs:dateTime" minOccurs="0"/> <xs:element name="StartDate" type="xs:dateTime" minOccurs="0"/> <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:attribute name="KeyPropertiesId" type="xs:ID" use="required"/> <xs:attribute name="KeyAlgorithm" type="pskc:KeyAlgorithmType" use="optional"/> </xs:complexType> <xs:complexType name="KeyType"> <xs:sequence> <xs:element name="Issuer" type="xs:string" minOccurs="0"/> <xs:element name="Usage" type="pskc:UsageType"/> <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:DataType" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="PINPolicy" type="pskc:PINPolicyType" minOccurs="0"/> <xs:element name="ExpiryDate" type="xs:dateTime" minOccurs="0"/> <xs:element name="StartDate" type="xs:dateTime" minOccurs="0"/> <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:attribute name="KeyId" type="xs:string" use="required"/> <xs:attribute name="KeyAlgorithm" type="pskc:KeyAlgorithmType" use="required"/> <xs:attribute name="KeyPropertiesId" type="xs:IDREF" use="optional"/> </xs:complexType> <xs:complexType name="DerivedKeyType"> <xs:sequence> <xs:element name="KeyDerivationMethod" type="pskc:KeyDerivationMethodType" minOccurs="0"/> <xs:element ref="xenc:ReferenceList" minOccurs="0"/> <xs:element name="CarriedKeyName" type="xs:string" minOccurs="0"/> </xs:sequence> <xs:attribute name="Id" type="xs:ID" use="optional"/> <xs:attribute name="Type" type="xs:anyURI" use="optional"/> </xs:complexType> <xs:complexType name="KeyDerivationMethodType"> <xs:sequence> <xs:any namespace="##other" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:attribute name="Algorithm" type="xs:anyURI" use="required"/> </xs:complexType> <xs:complexType name="PINPolicyType"> <xs:sequence> <xs:element name="PINUsageMode" type="pskc:PINUsageModeType"/> <xs:element name="WrongPINTry" type="xs:unsignedInt" minOccurs="0"/> <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:attribute name="PINPolicyId" type="xs:ID" use="optional"/> <xs:attribute name="PINKeyId" type="xs:string" use="optional"/> </xs:complexType> <xs:complexType name="PINUsageModeType"> <xs:choice maxOccurs="unbounded"> <xs:element name="Local"/> <xs:element name="Prepend"/> <xs:element name="Embed"/> <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/> </xs:choice> </xs:complexType> <xs:complexType name="DeviceIdType"> <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="ExpiryDate" type="xs:dateTime" minOccurs="0"/> <xs:element name="StartDate" type="xs:dateTime" minOccurs="0"/> <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence