Dynamic Symmetric Key Provisioning Protocol
(DSKPP)
V0.9
AUGUST 1, 2006
By
Open AuTHentication (OATH)
Editors
Mingliang Pei, VeriSign
mpei@verisign.com
Salah Machani, Diversinet
smachani@diversinet.com
1
Table of Contents
1
INTRODUCTION ................................................................................. 3
1.1
OVERVIEW ................................................................................................................................... 3
1.2
USE CASES ................................................................................................................................... 3
1.3
REQUIREMENTS ............................................................................................................................ 5
1.3.1
Good to have........................................................................................................................... 6
1.3.2
Non-Requirements .................................................................................................................. 6
2
NOTATIONS AND TERMINOLOGY ............................................... 6
2.1
2.2
3
PROTOCOL FLOW ............................................................................. 6
3.1
3.2
3.3
3.4
3.5
3.6
4
CONVENTIONS USED IN THIS DOCUMENT ...................................................................................... 6
ACRONYMS AND ABBREVIATIONS................................................................................................ 6
SHARED SECRET RESPONSE FORMAT ............................................................................................ 7
CLIENT AUTHENTICATION............................................................................................................ 7
SERVER AUTHENTICATION ..........................................................................................................10
ENCRYPTION KEY FOR CREDENTIAL RESPONSE ..........................................................................10
SIMPLE REQUEST AND RESPONSE WITH SECURE CHANNEL...........................................................10
FULL MESSAGE EXCHANGES WITH NON-SECURE CHANNEL..........................................................12
PROTOCOL MESSAGES .................................................................. 12
4.1
4.2
4.3
4.4
4.5
GETAUTHNONCE ........................................................................................................................12
GETAUTHNONCERESPONSE ........................................................................................................13
GETSHAREDSECRET....................................................................................................................13
GETSHAREDSECRETRESPONSE ...................................................................................................15
ACTIVATIONCODE ......................................................................................................................16
5
PROTOCOL BINDING ...................................................................... 17
6
SECURITY CONSIDERATION ....................................................... 17
6.1
6.2
6.3
AUTHENTICATION .......................................................................................................................17
CONFIDENTIALITY .......................................................................................................................18
INTEGRITY...................................................................................................................................18
7
SCHEMA .............................................................................................. 18
8
REFERENCES ..................................................................................... 26
9
ACKNOWLEDGMENTS ................................................................... 26
APPENDIX A: WEB SERVICE DEFINITION ...................................... 26
2
1 Introduction
1.1 Overview
This document describes a client-server protocol that enables a client device to download
and install authentication credentials from a provisioning server in a secure and efficient
manner. The prime example of such an authentication credential is a shared secret for
One-Time-Password (OTP) software token in a device. The protocol is for dynamic
provisioning of credentials to a user device; it is not a bulk provisioning protocol that
transfers token records from a provisioning server to an authentication system.
This protocol will only support provisioning for symmetric key credential types.
Asymmetric key pair provisioning isn’t the purpose of this protocol. It is a web services
XML-based protocol, with multiple profiles to support lightweight small footprint clients
such as smart cards, as well as more advanced device platforms such as USB tokens and
PDAs/smart phones.
Existing credential delivery protocols are specific to one authentication method, or are
proprietary to a particular vendor implementation. The industry needs a simple
provisioning protocol standard to enable interoperability across vendors and to provision
multiple credential types.
1.2 Use Cases
Provisioning
Client
Application
Web Services based protocol
for credential provisioning
Provisioning
Server
Credential
Issuer
1) Use Case #1: A mobile device user wants to obtain an HOTP credential (shared
secret) for use with an OTP software token on the device.
The credential may be pre-generated by a back end issuance server, or generated by the
provisioning server at the start of the provisioning process. A unique Credential ID is
assigned to the credential by the provisioning server. This protocol enables the client
device to request the credential, authenticate to the provisioning server, download the
credential over-the-air (OTA) and install it on the mobile device.
2) Use Case #2: A device user acquires multiple credentials of different types to its
device
The provisioning process should allow a user to acquire multiple credentials to its device
such as a flash drive or a desktop. The credentials may or may not be the same type such
as HOTP, symmetric challenge-response, or other algorithms. The protocol must provide
3
for a mechanism to uniquely identify a specific credential in the device using a token
identification to allow device authentication before provisioning.
3) Use Case 3: Credential renewal with the same credential ID
The provisioning allows a user to get a new key using the same Credential ID, in the case
of a lost/failed/locked or upgraded token device.
4) Use Case #4: A credential is associated with a validity period
After a user acquires a credential, the credential consuming application is able to check
whether the credential should be terminated after certain period of time. Instead of
defining such validity by the consuming or credential authentication system, the
provisioning service defines validity for credentials that it issues.
5) Use case #5: A user acquires credentials for its device from an issuer as a Relying
Party of a credential provisioning service provider
A credential issuer leverages third party credential provisioning and validation service
provider to offer its user software tokens. This is a case different from a fully hosted
enterprise customer case where an enterprise hosts its own provisioning server. In the
current case, the end user client application communicates with the issuer proxy server
that delegates request to provisioning service to acquire a credential after it authenticates
the user. The issuer entity is responsible to authenticate its users but not manufacturing
credentials; it acquires credentials from service provider. The case falls into dynamical
provisioning scenario instead of bulk provisioning between credential manufacturers and
authentication system providers.
Mutual authentication is typically needed between an issuing relying party and a
provisioning service provider. Because these are typically machine to machine
authentication, a certificate based authentication is good candidate. If a shared secret is
used, the shared secret can be long strong one.
6) Use Case #6: Administrator initialization before use
This use case represents a special case of credential renewal in which a local
administrator can authenticate the user procedurally before initiating the dynamic
provisioning. It also allows for keys on physical tokens to be issued with a restriction
that the key must be replaced with a new key prior to token use.
While bulk initialization under controlled conditions during manufacture is likely to meet
the security needs of most applications reliance on a pre-disclosed secret is unacceptable
to some circumstances, in particular tokens issued for classified government use or high
security applications. In such cases the token issuer requires the ability to remove all the
secret information installed on the token during manufacture and replace it with secret
keys established under conditions controlled by the issuer. It is however in most cases
4
impractical for the administrator to apply a physical marking to the token itself such as a
serial number. It is therefore necessary for the enrollment process to communicate the
token serial number to the provisioning service. Another situation in which initialization
before use may be required is the case where the OTP functionality is installed on a
previously manufactured device as software.
Another variation of this use case is that some enterprises may prefer to re-provision a
new secret to an existing token if they decide to reuse the token that was with one user
and for a new user.
7) Use Case #7: Post issuance smart card update
A smart card has been issued to a user. After issuance the smart card is updated with an
HOTP application. The key for the HOTP application will then be provisioned using a
secure channel mechanism present in many smart card platforms. This allows a direct
secure channel to be established between the smart card chip and the provisioning server.
EG the card commands (APDUs Application Protocol Data Unit) is encrypted with a preshared transport key and sent directly to the smart card chip allowing secure in-the-field
post issuance provisioning even passing different SSL or other transport security
boundaries.
This use case in therefore not in bulk but will require the protocol to be tunneled and the
provisioning server to know the correct previously set up transport key.
1.3 Requirements
The protocol addresses the following requirements.
1. Supports multiple types of credentials for symmetric key based authentication
methods
2. Supports pre-generated credentials (by separate credential issuance server/service)
or locally generated credentials in real-time (by provisioning server)
3. Supports a device to host multiple credentials; each credential can be acquired in
its own session
4. Supports renewal of credential with the same credential ID
5. Allows the client to specify its cryptographic and security capabilities to the
server.
6. Provides mutual authentication and confidentiality of sensitive provisioning data
7. Does not require client-side digital certificates to be supported for all client types
(e.g., allows for protocol options/profiling that supports use of PKI in some cases
and not others for symmetric key protection and device authentication)
8. Does not rely on transport level security (e.g., SSL/TLS) for core security
requirements (since not all devices have SSL support). Should be SSL-compatible
when available
9. Allows an issuer to set credential expiry for its tokens
5
10. Allows on the server side to use pre-loaded symmetric transport keys on a device
by device basis (smart card update keys, e.g. secure channel in Global platform)
11. Enables simple user experience for provisioning process
12. Protects against replay attacks
13. Protects against man-in-the middle attacks
1.3.1 Good to have
1. Supports mutually generated secrets by both client and server
2. Supports a device to acquire multiple credentials in the same session
3. Should allow the provisioning server to verify that the key has been correctly
provisioned to the client
4. Allow a client to notify credential deletion
1.3.2 Non-Requirements
1. Supports client generated credentials to upload to provisioning server
2. Supports credential lifecycle management, for example, disabling a token when
an owner reports that it is lost; it is an authentication system function.
3. Supports asymmetric key pair provisioning
2 Notations and Terminology
2.1 Conventions used in this document
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 RFC 2119.
2.2 Acronyms and Abbreviations
The following (non-normative) table defines acronyms and abbreviations for this
document.
Term
Definition
OTP
HMAC
SHA1
SOAP
One Time Password
Hashing for Message Authentication
Secure Hash Algorithm 1
Simple Object Access Protocol
Uniform Resource Identifier
Extensible Markup Language
URI
XML
3 Protocol flow
The basic protocol consists of two pair request and response message exchanges between
a client and a provisioning server. The first pair of messages, namely, GetAuthNonce and
GetAuthNonceResponse, enables a client to contact server for a nonce value before it
6
sends authentication data in the actual credential request. The server nonce is used to
construct client authentication data that cannot be replayed. This round trip is only
needed when a non-secure transport channel is used and client authentication is required.
The second pair of messages (GetSharedSecret and GetSharedSecretResponse) is the
actual credential provisioning round trip where a client authentication data is sent in the
request. For typical provisioning web service implementation where secure transport
(TLS) is enabled, a client only needs to send one request, namely the message
“GetSharedSecret”. Of course, a client can use the two round trips even if secure
transport layer is used.
Server
Client
GetAuthNon
ce
ce
GetAuthNon
R e sp o n se
GetSharedSe
c
dSecre
GetShare
ret
tRespons
e
3.1 Shared secret response format
The protocol uses Portal Symmetric Key Container (PSKC) defined by OATH
submission to RFC to carry a resulting shared secret value. It also allows other formats
such as PKCS#12 or PKCS#5 XML format through a general extension.
3.2 Client Authentication
Credential provisioning process typically needs to determine whether a given client is
allowed to acquire a token credential. The client authentication, however, may or may not
be in-band where authentication data is part of request message and authentication must
be carried out by the provisioning server. Client authentication may be done out of band
before provisioning flow occurs. For example, a provisioning web application for desktop
software token may authenticate user first, and then accepts a provisioning request
message; the client application doesn’t need to send any authentication data inside the
credential request message.
When authentication data is expected from a request, such data is typically a device
certificate or an activation code acquired out of band by the device owner from credential
7
issuer. For the later case, a user typically goes to a credential issuer to pay and get an
activation code; the user downloads a credential to its device after submitting such an
activation code.
When a credential issuer is actually an issuing relying party of a provisioning service
provider, the authentication also happens between the issuer and the service provider. The
authentication between the client and the relying party proxy server can be done as if the
proxy server is the actual provisioning service. The authentication between the proxy and
service provider may depend on either an enterprise certificate or a shared secret between
the two parties. Because it is machine to machine authentication, an enterprise certificate
is often more secure and convenient. If a shared secret is used, the shared secret can be
long strong one in comparison with end user activation code that needs to be entered into
some UI.
Considering an activation code as a special form of shared secret between user and
provisioning service, we have two kinds of authentication data: shared secret and a
certificate for either a user or an organization.
When a user has an authentication activation code, it must be sent to provisioning server
in a secure way. If underlying transport channel is secure, the authentication data can be
the original activation code or hashed form:
AuthenticationData = HASH (activation code)
where some server information such as server IP or URL could be optionally used along
with activation code for hashing. Otherwise, the authentication data is derived from the
activation code and a server provided nonce value:
AuthenticationData = HMAC (activation code, serverNonce)
This prevents man-in-the-middle attack because the hashed data doesn’t expose original
activation code to the hacker and the data cannot be replayed due to server nonce.
When a certificate is used for authentication, the authentication data can be client signed
data.
In addition to the authentication data, the full authentication token element may contain
an identifier such as username, account ID, device ID or a server issued ID. Thus the
authentication token element for the credential request has the following form.
<complexType name="AuthenticationTokenType">
<annotation>
<documentation xml:lang="en">
Authentication data holder for a request. When authentication type
is "PASSCODE", the data can be any one of the three activation
code related types.
</documentation>
</annotation>
8
<sequence>
<element name="ID" type="string" minOccurs="0"/>
<choice minOccurs="0">
<element name="ActivationCode" type="kp:ActivationCodeType"/>
<element name="ActivationCodeDigest" type="kp:ActivationCodeDigestType"/>
<element name="ActivationCodeNonce" type="kp:ActivationCodeNonceType"/>
<any namespace="##other" processContents="strict"/>
</choice>
</sequence>
<attribute name="authDataType" type="kp:AuthDataTypeType" default="PASSCODE"/>
</complexType>
For the relying party provisioning proxy scenario where a shared secret is used, the
authentication data type can use <ActivationCodeDigest> along with its account ID carried in
<ID>.
Examples:
<AuthenticationToken authDataType=”PASSCODE”>
< ActivationCode>10222134</ActivationCode>
</AuthenticationToken>
<AuthenticationToken authDataType=”PASSCODE”>
<ID>DeviceX</ID>
<ActivationCodeDigest
algorithm="http://www.w3.org/2000/09/xmldsig#sha1">RMCz+ciKcZBNZ0VY+z2fZL0DhuY
=</ActivationCodeDigest>
</AuthenticationToken>
<AuthenticationToken authDataType=”PASSCODE”>
< ID>DeviceX</ID>
<ActivationCodeNonce algorithm="http://www.w3.org/2000/09/xmldsig#hmac-sha1">
<Data>HMAC(passcode, nonce)</Data>1
</ActivationCodeNonce>
</AuthenticationToken>
<AuthenticationToken authDataType=”CERT”/>
<AuthenticationToken authDataType=”PASSCODE”>
<ID>AccountID:Acme</ID>
<ActivationCodeDigest
algorithm="http://www.w3.org/2000/09/xmldsig#sha1">RMCz+ciKcZBNZ0VY+z2fZL0DhuY
=</ActivationCodeDigest>
</AuthenticationToken>
When authentication token type is “CERT”, a XML <Signature> element is expected from the
request. This is typically the signing of entire request document, and standard XML signature is
used.
1
Nonce element is optional.
9
3.3 Server Authentication
With HTTP based web service protocol, SSL server certificate is used for server
authentication.
If transport layer doesn’t provide server authentication and the symmetric key payload is
encrypted with a shared secret, a client accepts server issued credential by verifying the
response message.
In case where a device certificate is used for authentication, a client won’t be able to
ensure that a response is from a legitimate service; it could be a man in the middle that
issues a secret encrypted with the client certificate public key. However, this doesn’t
seem to be a typical case; a device that is capable to handle a device certificate should be
able to support SSL. It is recommended that secure channel is used for devices with a
certificate for client authentication.
3.4 Encryption Key for Credential Response
The credential response can be encrypted with the following possible keys.
A. A pre-generated shared secret between the client and the server. This can be either a
key derived from activation code that the credential issuer provides to a device owner, or
a pre-loaded transport key available in server side on per device base.
B. Public key of the client certificate when a device certificate is used for authentication
C. Other server specified keys
The element in the server response provides all the encryption key related information.
With PSKC format, the encryption method is defined by “EncryptionMethodType”.




Identifier for shared secret
Implicitly implied – the default is the key derived from activation code used for
authentication
Client’s public key. The provisioning server should authenticate the client
certificate in this case.
Server’s private key encryption with public key in response, which requires
secure channel
3.5 Simple request and response with secure channel
A user acquires an activation code from a credential issuer before it accesses provisioning
service to load a secret for its device. The device client contacts provisioning web service
with the following sample request GetSharedSecret.
<?xml version="1.0" encoding="UTF-8"?>
<GetSharedSecret id="1234abcd" version="1.0">
<CredentialIdManufacturerCode>VSMB</CredentialIdManufacturerCode>
<ClientType>MOBILEPHONE</ClientType>
10
<AuthenticationToken authDataType=”PASSCODE”>
<ActivationCode>12345678</ActivationCode>
</AuthenticationToken>
<DeviceId>
<Manufacturer>SAMSUNG</Manufacturer>
<SerialNo>XA1234</SerialNo>
<Model>SPH-A900</Model>
<Expiry>Dec 2006</Expiry>
</DeviceId>
<LogoPreference>
<xSize>360</xSize>
<ySize>240</ySize>
</LogoPreference>
<OtpAlgorithm type="HMAC-SHA1-TRUNC-6DIGITS"/>
<SharedSecretDeliveryMethod>HTTPS</SharedSecretDeliveryMethod>
<SupportedEncryptionAlgorithm>PBE-3DES112-CBC</SupportedEncryptionAlgorithm>
</GetSharedSecret>
The server delivers an encrypted shared secret after authentication check.
<?xml version="1.0" encoding="UTF-8"?>
<GetSharedSecretResponse requestId="1234abcd" version="1.0">
<Status>
<StatusCode>Success</StatusCode>
<StatusMessage>Success</StatusMessage>
</Status>
<SharedSecretDeliveryMethod>HTTPS</SharedSecretDeliveryMethod>
<Credential format=”PSKC”>
<SecretContainer Version="1.0">
<EncryptionMethod>
<EncryptionAlgorithm>PBE-3DES112-CBC</EncryptionAlgorithm>
<EncKeyLabel>MyKey</EncKeyLabel>
</EncryptionMethod>
<Device>
<Secret type="HOTP" Id="SDU312345678">
<Issuer>EBAY</Issuer>
<Usage otp="true">
<AI type="HMAC-SHA1-TRUNC-6DIGITS"/>
<Counter>50</Counter>
</Usage>
<FriendlyName>Ebay Token</FriendlyName>
<Data>
<Cipher>PHUIoaByd/O43DWmhpj9GqbXeOoWi4TmylkhTY0ww9717eJk9Wcv4Wk22x+ShVUOa
8WIdSDzla5MS5LkRjyeE9pHNAqDj4DZotUPYNXNZPM47qdtdcBCwg1D3q+KGwJoCRTFl6hakl
Oe/3T2kmMQzdWHpzLtxn2a2pNZTx4LqNw=
</Cipher>
<Digest algorithm="HMAC-SHA1">qZk+NkcGgWq6PiVxeFDCbJzQ2J0=</Digest>
</Data>
<Expiry>2007-04-30T12:00:00</Expiry>
<IssuerLogo MimeType="image/gif">fba53259bcbef35345bef96832ba
</IssuerLogo>
</Secret>
</Device>
</SecretContainer>
</GetSharedSecretResponse>
11
3.6 Full message exchanges with non-secure channel
Client sends a request to acquire server nonce.
<?xml version="1.0" encoding="UTF-8"?>
<GetAuthNonce id=”1234abcd” version=”1.0”>
<DeviceId>
<Manufacturer>Acme</Manufacturer>
<SerialNo>FA0033F4550B01FFDA05</SerialNo>
</DeviceId>
</GetAuthNonce>
Server replies with a nonce for the session.
<?xml version="1.0" encoding="UTF-8"?>
<kp:GetAuthNonceResponse version="1.0" requestId="1234abcd"
serverNonce="DFRWE23DFFeDtD">
<Status>
<StatusCode>Continue</StatusCode>
</Status>
<CredentialID>DEAB0000FFFF</CredentialID>
<ServiceID>EBAY</ServiceID>
</kp:GetAuthNonceResponse>
Client goes to get shared secret. See samples in section 3.5.
4 Protocol messages
4.1 GetAuthNonce
This is the first request from a client when transport channel isn’t secure. It is used to
acquire a server nonce value in order securely send user authentication data to the server.
<element name="GetAuthNonce" type="kp:GetAuthNonceType"/>
<complexType name="GetAuthNonceType">
<complexContent>
<extension base="kp:RequestAbstractType">
<sequence>
<element name="DeviceId" type="kp:DeviceIdType"/>
</sequence>
</extension>
</complexContent>
</complexType>
where

<DeviceId> contains the device information.

<version> attribute, inherited from <RequestAbstractType>, is the message
version used in the client.
12

<id> attribute, inherited from <RequestAbstractType>, is a a unique identifier to
track this request.
4.2 GetAuthNonceResponse
Server returns a nonce value for the request. It can also optionally return credential ID for
the credential to issue, and service ID for service information.
<element name="GetAuthNonceResponse" type="kp:GetAuthNonceResponseType" />
<complexType name="GetAuthNonceResponseType">
<complexContent>
<extension base="kp:ResponseAbstractType">
<sequence minOccurs=”0” maxOccurs="unbounded">
<element name="CredentialID" type="kp:IdentifierType"/>
<element name="ServiceID" type="kp:IdentifierType"/>
</sequence>
<attribute name="serverNonce" type="base64Binary"/>
<attribute name="sessionID" type="kp:IdentifierType" use=”optional”/>
</extension>
</complexContent>
</complexType>

<CredentialID> contains server assigned credential ID

<ServiceID> indicates service information.

<serverNonce> is a pseudorandom string generated by the provisioning server. It
should be used along with activation code to construct authentication token to acquire
a credential.

<sessionID> is a server generated ID for this request. The server typically accepts the
request ID from the request and won’t generate a new ID. This allows a server to
choose its own session ID to identify a request.

<version> attribute, inherited from <ResponseAbstractType>, indicates the message
protocol version used by the server.

<requestId> attribute, inherited from <ResponseAbstractType>, is the ID that the
corresponding request sent.
4.3 GetSharedSecret
<element name="GetSharedSecret" type="kp:GetSharedSecretType"/>
<complexType name="GetSharedSecretType">
<complexContent>
<extension base="kp:RequestAbstractType">
<sequence maxOccurs="unbounded">
<choice minOccurs=”0”>
<element ref="kp:CredentialId"/>
13
<element ref="kp:CredentialIdManufacturerCode"/>
</choice>
<element ref="kp:ClientType" minOccurs=”0”/>
<element name="DeviceId" type="pskc:DeviceIdType" minOccurs="0"/>
<element name="AuthenticationToken" type="kp:AuthenticationTokenType"/>
<element ref="pskc:LogoPreference" minOccurs="0"/>
<element name="OtpAlgorithm" type="pskc:OtpAlgorithmIdentifierType"
minOccurs="0"/>
<element ref="kp:SharedSecretDeliveryMethod" minOccurs="0"/>
<element ref="kp:SupportedEncryptionAlgorithm" minOccurs="0"/>
<element name="Extension" type="kp:ExtensionType" minOccurs="0"
maxOccurs="unbounded"/>
</sequence>
</extension>
</complexContent>
</complexType>

<CredentialID> can be either client supplied or server assigned. If a Credential ID
isn’t given in a request, it should generally contain a
<CredentialIdManufacturerCode> to indicate a block of credential IDs assigned to
either an credential issuer or device manufacturer. This is typically a credential ID
prefix in current credential ID naming practice. A device manufacturer may not be a
credential issuer but it gets such a code from credential issuer for all its devices when
a credential is provisioned to its device. This can be also used to allow a provisioning
service to issue tokens for different token issuers where an issuer may choose its own
credential ID code. Depending on credential ID standard, it could be the so called
manufacturer code today or Organizational Unique ID (OUI) in EUI-48 as part of
credential ID. If this element isn’t given in a request, the server will assign a token
ID.

<ClientType> indicates the device type.

<DeviceId> conveys the device information. It is defined in OATH PSKC
specification.

<LogoPreference> describes preferred logo that the issuer should return.

<AuthenticationToken> carries authentication data that can be a pre-acquired
authentication credential by the user for the service authorization, a server nonce
mixed hash data, or device certificate signed data.

<OtpAlgorithm> indicates the algorithm supported by the token-device.

<SharedSecretDeliveryMethod> specifies the mechanism to be used for delivering
the shared-secret e.g. via HTTPS or SMS . For example, a request may be initiated
from a desktop environment, and asks the server to send the secret to a cell phone
through SMS for those phones that doesn’t support internet access.
14

<SupportedEncryptionAlgorithm> indicates the algorithm that the service should use
to encrypt the shared-secret. The inherited optional element Signature may contain
the signature over the entire request document depending upon the capabilities of the
device and the presence of a device certificate.

<Extension> allows additional request information.
It also contains a version number and request ID attribute inherited from
<RequestAbstractType> that indicate respectively the client protocol version and a
unique identifier to track this request.
4.4 GetSharedSecretResponse
The GetSharedSecretResponse element represents a provisioning service response
message corresponding to a shared secret request. Such a message contains shared secret
container similarly defined by OATH PSKC and a field that specifies the mechanism
being used for delivering the shared-secret e.g. via HTTPS or SMS. Either the user
Activation Code derived key or public key of a device certificate can act as the
encryption key in SecretContainer to encrypt the secret. The message is defined as
follows.
<element name="GetSharedSecretResponse" type="kp:GetSharedSecretResponseType"/>
<complexType name="GetSharedSecretResponseType">
<complexContent>
<extension base="kp:ResponseAbstractType">
<sequence minOccurs="0">
<element ref="kp:SharedSecretDeliveryMethod" minOccurs="0"/>
<element name="Credential" type=”kp:CredentialType” minOccurs="0"/>
<element name="Extension" type="kp:ExtensionType" minOccurs="0"
maxOccurs="unbounded"/>
</sequence>
</extension>
</complexContent>
</complexType>

<SharedSecretDeliveryMethod> specifies the shared secret delivery method. The
value can be HTTPS or SMS.

<Credential> contains credential related information. It can be one or many
credentials. The default format of credential is PSKC. Other credential format such as
PKCS12 can also be used by a provisioning server.

<Extension> allows a server to return additional information. A provisioning service
provider may specify its own extensions.
15
4.5 ActivationCode
This protocol supports two kinds of authentication data for a user to acquire a credential,
namely, namely, activation code and device certificate. For a device that doesn’t use a
device certificate, a user can acquire an activation code from its token issuer before it
provisions a shared secret from provisioning service to its device. An activation code may
or may not contain alpha letters in addition to numerical digits depending on the device
type and issuer policy. For a mobile phone, it is often a good practice that only numerical
digits are used for easy to input.
An activation code can be sent to a provisioning server in either its clear form, hashed
data or keyed HMAC form with a server nonce value. When it is sent in its original form,
the following definition is used.
<!-- ActivationCodeType -->
<simpleType name="ActivationCodeType">
<annotation>
<documentation xml:lang="en">
Maximum length of activation code restricted to 20 bytes
</documentation>
</annotation>
<restriction base="string">
<maxLength value="20"/>
</restriction>
</simpleType>
When a hashed form is sent, the following element should be used.
<complexType name="ActivationCodeDigestType">
<annotation>
<documentation xml:lang="en">
Includes a digest of activation code.
</documentation>
</annotation>
<simpleContent>
<extension base="base64Binary">
<attribute name="algorithm" type="kp:DigestAlgorithmType" use="required"/>
</extension>
</simpleContent>
</complexType>
The <algorithm> attribute indicates one of supported message digest methods. By
default, it can use SHA1 with identifier
“http://www.w3.org/2000/09/xmldsig#sha1”
The other choices are
“http://www.w3.org/2001/04/xmldsig-more#sha256”
“http://www.w3.org/2001/04/xmldsig-more#sha512”
When a nonce value is mixed with the activation code, the following type should be used.
16
<!-- ActivationCodeNonceType -->
<complexType name="ActivationCodeNonceType">
<annotation>
<documentation xml:lang="en">
Includes a HMAC of activation code with nonce as key.
</documentation>
</annotation>
<sequence>
<element name="Data" type="base64Binary"/>
<element name="Nonce" type="kp:NonceType" minOccurs="0"/>
</sequence>
<attribute name="algorithm" type="kp:HMACAlgorithmType" use="required"/>
</complexType>
The <algorithm> attribute indicates one of supported MAC algorithms. By default, it can
use HMAC-SHA1 with identifier
“http://www.w3.org/2000/09/xmldsig#hmac-sha1”
The other choices can be the following.
“http://www.w3.org/2001/04/xmldsig-more#hmac-sha256”
“http://www.w3.org/2001/04/xmldsig-more#hmac-sha512”
5 Protocol Binding
The provisioning messages can support HTTP and SOAP binding to enable web service
support.
For HTTP binding, the requests can be simply posted with HTTP header application/xml.
The server parses message content to determine the request type. SOAP binding uses
standard SOAP header. The protocol doesn’t require special headers.
6 Security Consideration
The protocol messages contain sensitive information such as user authentication data and
symmetric keys that are transported between a provisioning service provider and end user
device. The protocol has defined mechanisms to protect the messages for confidentiality,
authenticity, and integrity. Implementation must pay attention to different choices and
their strength according to standard security best practices, in particular, when data is sent
over non-secure channel.
6.1 Authentication
Mutual authentication MUST be used between a client and the provisioning service. A
service provider should authenticate a client to ensure that an issued secret is given to an
intended device.
17
When a device certificate is used for client authentication, the provisioning server should
follow standard certificate verification process to ensure that it is a trusted device.
When an activation code is used for authentication, the authentication data is subject to
typical password dictionary attack. When a secure channel (e.g., HTTPS) between a
client and the service is used, a successful activation code guess would allow a user to get
a free credential; but it won’t leak a legitimate user’s credential to another user. An
expiration window and proper length to mitigate such misuse risks can be used according
to standard best practice.
It is recommended that a secure channel HTTPS should be generally used unless a device
isn’t able to support it. In case that a non-secure channel has to be used, a nonce value
acquired from provisioning service is used to prevent replay attack and man-in-themiddle spoof of the activation code. The sensitive activation code and nonce value must
be strong enough to prevent offline brute force recovery of activation code from HMAC
data. Because nonce value is almost public across a non-secure channel, the key strength
lies in the activation code. The activation code length should be generally longer than
those used over a secure channel. When a device cannot friendly handle long activation
code such as some mobile phone with small screen, it is necessary to use only secure
channel to communicate with a provisioning service.
See section 3.3 about server authentication.
6.2 Confidentiality
The credential payload is encrypted by either a client’s public key or a key derived from a
mutual secret (activation code or pre-generated key) between a user and the service.
When data is sent over a non-secure channel, the encryption key may be subject to brute
force attack if the underlying key material isn’t properly chosen. In addition to strong
activation code choice, the service should follow standard practice to adopt proper
encryption algorithm.
6.3 Integrity
Provisioning request message has an optional signature element to ensure integrity of
message and request. For an environment where credentials are tracked according to
device IDs and there is no binding relationship between a device ID and authentication
data (e.g., Activation Code), it is recommended to enforce use of Signature to prevent a
user from binding a credential to other’s device.
7 Schema
<?xml version="1.0" encoding="UTF-8" ?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:kp="http://www.openauthentication.org/OATH/KeyProv"
xmlns:pskc="http://www.openauthentication.org/OATH/PSKC"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
18
targetNamespace="http://www.openauthentication.org/OATH/KeyProv"
elementFormDefault="qualified" attributeFormDefault="unqualified">
<import namespace="http://www.w3.org/2000/09/xmldsig#"
schemaLocation="http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/xmldsig-coreschema.xsd"/>
<annotation>
<documentation xml:lang="en">XML Schema for OATH Dynamical Symmetric Key
Provisioning Web Services</documentation>
</annotation>
<!-- MessageAbstractType -->
<complexType name="MessageAbstractType" abstract="true">
<annotation>
<documentation xml:lang="en">
Abstract class for all messages that are part of the UA Web Service.
</documentation>
</annotation>
<attribute name="version" type="kp:VersionType" use="required"/>
</complexType>
<!-- VersionType -->
<simpleType name="VersionType" final="restriction">
<restriction base="string">
<pattern value="\d{1,9}\.\d{0,9}"/>
</restriction>
</simpleType>
<!-- RequestAbstractType -->
<complexType name="RequestAbstractType" abstract="true">
<annotation>
<documentation xml:lang="en">
Abstract class for all request messages. Id is a pseudo-random
number used for request-response matching.
</documentation>
</annotation>
<complexContent>
<extension base="kp:MessageAbstractType">
<sequence>
<element ref="ds:Signature" minOccurs="0"/>
</sequence>
<attribute name="id" type="kp:IdentifierType" use="optional"/>
</extension>
</complexContent>
</complexType>
<!-- ResponseAbstractType -->
<complexType name="ResponseAbstractType" abstract="true">
<annotation>
<documentation xml:lang="en">
Abstract class for all responses sent by the UA Web Service.
RequestId contains the Id received in the request.
Response messages also contains a status indicating success or cause of failure.
</documentation>
</annotation>
<complexContent>
19
<extension base="kp:MessageAbstractType">
<sequence>
<element name="Status" type="kp:StatusType"/>
</sequence>
<attribute name="requestId" type="kp:IdentifierType" use="optional"/>
</extension>
</complexContent>
</complexType>
<!-- StatusType -->
<complexType name="StatusType">
<annotation>
<documentation xml:lang="en">
Contains a status code indicating success or causes of failure, and
a status message that includes a brief description.
</documentation>
</annotation>
<sequence>
<element name=”StatusCode” type="kp:StatusCodeType"/>
<element name="StatusMessage" type="string" minOccurs="0"/>
</sequence>
</complexType>
<!-- StatusCodeType -->
<simpleType name="StatusCodeType">
<annotation>
<documentation xml:lang="en">
Can contain one of the following status values.
</documentation>
</annotation>
<restriction base="string">
<enumeration value="Continue"/>
<enumeration value="Success"/>
<enumeration value="Abort"/>
<enumeration value="UnsupportedVersion"/>
<enumeration value="UnsupportedKeyType"/>
<enumeration value="UnsupportedEncryptionAlgorithm"/>
<enumeration value="AccessDenied"/>
<enumeration value="MalformedRequest"/>
<enumeration value="SessionExpired"/>
<enumeration value="CredentialNotFound"/>
<enumeration value="UnknownClient"/>
<enumeration value="UnknownRequest"/>
<enumeration value="OtherFailure"/>
</restriction>
</simpleType>
<complexType name="AuthenticationTokenType">
<annotation>
<documentation xml:lang="en">
Authentication data holder for a request. When authentication type
is "PASSCODE", the data can be any one of the three activation
code related types.
</documentation>
</annotation>
<sequence>
20
<element name="ID" type="string" minOccurs="0"/>
<choice minOccurs="0">
<element name="ActivationCode" type="kp:ActivationCodeType"/>
<element name="ActivationCodeDigest" type="kp:ActivationCodeDigestType"/>
<element name="ActivationCodeNonce" type="kp:ActivationCodeNonceType"/>
<any namespace="##other" processContents="strict"/>
</choice>
</sequence>
<attribute name="authDataType" type="kp:AuthDataTypeType" default="PASSCODE"/>
</complexType>
<!-- Authenticaton Type-->
<simpleType name="AuthDataTypeType">
<restriction base="string">
<enumeration value="PASSCODE"/>
<enumeration value="CERT"/>
</restriction>
</simpleType>
<!-- Credential Format -->
<simpleType name="CredentialFormatType">
<restriction base="string">
<enumeration value="PSKC"/>
<enumeration value="PKCS12"/>
<enumeration value="XMLP5"/>
</restriction>
</simpleType>
<simpleType name="NonceType">
<restriction base="base64Binary">
<minLength value="8"/>
</restriction>
</simpleType>
<!-- Client gets server nonce -->
<element name="GetAuthNonce" type="kp:GetAuthNonceType"/>
<complexType name="GetAuthNonceType">
<annotation>
<documentation xml:lang="en">
A client initiates contact with server to acquire a server nonce.
</documentation>
</annotation>
<complexContent>
<extension base="kp:RequestAbstractType">
<sequence>
<element name="DeviceId" type="pskc:DeviceIdType"/>
</sequence>
</extension>
</complexContent>
</complexType>
<!-- Server Response for GetAuthNonce request -->
<element name="GetAuthNonceResponse" type="kp:GetAuthNonceResponseType" />
<complexType name="GetAuthNonceResponseType">
<complexContent>
21
<extension base="kp:ResponseAbstractType">
<sequence minOccurs="0" maxOccurs="unbounded">
<element name="CredentialID" type="kp:CredentialIdType"/>
<element name="ServiceID" type="kp:IdentifierType"/>
</sequence>
<attribute name="serverNonce" type="kp:NonceType"/>
<attribute name="sessionID" type="kp:IdentifierType" use="optional"/>
</extension>
</complexContent>
</complexType>
<simpleType name="IdentifierType">
<restriction base="string">
<maxLength value="128"/>
</restriction>
</simpleType>
<element name="GetSharedSecret" type="kp:GetSharedSecretType"/>
<!-- GetSharedSecretType -->
<complexType name="GetSharedSecretType">
<annotation>
<documentation xml:lang="en">
Type for a shared-secret provisioning request. CredentialId is part
of the request except for a server-generated token where only the
token manufacturer code is included in the request. The manufacturer
code is typically the credential ID prefix assigned to a manufacturer.
DeviceId indicates the device information. LogoPreference describes
preferred logo that the issuer should return. OtpAlgorithm indicates the
algorithm supported by the token-device. SharedSecretDeliveryMethod
specifies the mechanism to be used for delivering the shared-secret
e.g. via HTTPS or SMS. SupportedEncryptionAlgorithm indicates
the algorithm that the service should use to encrypt the
shared-secret. The inherited optional element Signature may
contain the signature over the CredentialId or the CredentialIdManufacturerCode
element of the request depending upon the capabilities of the
device and the presence of a device certificate.
</documentation>
</annotation>
<complexContent>
<extension base="kp:RequestAbstractType">
<sequence maxOccurs="unbounded">
<choice minOccurs="0">
<element name="CredentialId" type="kp:CredentialIdType"/>
<element name="CredentialIdManufacturerCode"
type="kp:CredentialIdManufacturerCodeType"/>
</choice>
<element ref="kp:ClientType" minOccurs="0"/>
<element name="DeviceId" type="pskc:DeviceIdType" minOccurs="0"/>
<element name="AuthenticationToken" type="kp:AuthenticationTokenType
minOccurs=”0"/>
<element name="LogoPreference" type="pskc:LogoImageInfoType" minOccurs="0"/>
<element name="OtpAlgorithm" type="pskc:OtpAlgorithmIdentifierType" minOccurs="0"/>
<element ref="kp:SharedSecretDeliveryMethod" minOccurs="0"/>
<element ref="kp:SupportedEncryptionAlgorithm" minOccurs="0"/>
<element name="Extension" type="kp:ExtensionType" minOccurs="0"
maxOccurs="unbounded"/>
22
</sequence>
</extension>
</complexContent>
</complexType>
<!-- Extension Type -->
<complexType name="ExtensionType" abstract="true">
<sequence>
<element name="ExtensionID" type="anyURI"/>
<element name="ExtensionValue" type="base64Binary"/>
</sequence>
<attribute name="critical" type="boolean"/>
</complexType>
<!-- CredentialIdType -->
<simpleType name="CredentialIdType">
<annotation>
<documentation xml:lang="en">
Credential identifier for a credential. It is limited to at most 40 characters.
</documentation>
</annotation>
<restriction base="string">
<maxLength value="40"/>
</restriction>
</simpleType>
<!-- CredentialIdManufacturerCodeType -->
<simpleType name="CredentialIdManufacturerCodeType">
<annotation>
<documentation xml:lang="en">
Unique identifier to indicate block of credential IDs assigned to
either an credential issuer or device manufacturer. This is typically
a credential ID prefix in current credential ID naming practice.
A device manufacturer may not be a credential issuer but it gets such
a code from credential issuer for all its devices when a credential
is provisioned to its device. This can also be used to allow a
provisioning service to issue tokens for different token issuers; and
an issuer may choose its own credential ID code.
</documentation>
</annotation>
<restriction base="string">
<minLength value="2"/>
<maxLength value="8"/>
</restriction>
</simpleType>
<element name="ClientType" type="kp:ClientTypeType"/>
<!-- ClientTypeType -->
<simpleType name="ClientTypeType">
<annotation>
<documentation xml:lang="en">
It can be one of the following supported device types.
</documentation>
</annotation>
<restriction base="string">
<enumeration value="DEVICE"/>
23
<enumeration value="MOBILEPHONE"/>
<enumeration value="DESKTOP"/>
</restriction>
</simpleType>
<simpleType name="HMACAlgorithmType">
<annotation>
<documentation xml:lang="en">
List of supported HMAC algorithms.
</documentation>
</annotation>
<restriction base="string">
<enumeration value="http://www.w3.org/2000/09/xmldsig#hmac-sha1"/>
<enumeration value="http://www.w3.org/2001/04/xmldsig-more#hmac-sha256"/>
<enumeration value="http://www.w3.org/2001/04/xmldsig-more#hmac-sha512"/>
</restriction>
</simpleType>
<simpleType name="DigestAlgorithmType">
<annotation>
<documentation xml:lang="en">
List of supported message digest algorithms.
</documentation>
</annotation>
<restriction base="string">
<enumeration value="http://www.w3.org/2000/09/xmldsig#sha1"/>
<enumeration value="http://www.w3.org/2001/04/xmldsig-more#sha256"/>
<enumeration value="http://www.w3.org/2001/04/xmldsig-more#sha512"/>
</restriction>
</simpleType>
<!-- ActivationCodeType -->
<simpleType name="ActivationCodeType">
<annotation>
<documentation xml:lang="en">
Maximum length of activation code restricted to 20 bytes
</documentation>
</annotation>
<restriction base="string">
<maxLength value="20"/>
</restriction>
</simpleType>
<complexType name="ActivationCodeDigestType">
<annotation>
<documentation xml:lang="en">
Includes a digest of activation code.
</documentation>
</annotation>
<simpleContent>
<extension base="base64Binary">
<attribute name="algorithm" type="kp:DigestAlgorithmType" use="required"/>
</extension>
</simpleContent>
</complexType>
24
<!-- ActivationCodeNonceType -->
<complexType name="ActivationCodeNonceType">
<annotation>
<documentation xml:lang="en">
Includes a HMAC of activation code with nonce as key.
</documentation>
</annotation>
<sequence>
<element name="Data" type="base64Binary"/>
<element name="Nonce" type="kp:NonceType" minOccurs="0"/>
</sequence>
<attribute name="algorithm" type="kp:HMACAlgorithmType" use="required"/>
</complexType>
<element name="SharedSecretDeliveryMethod" type="kp:SharedSecretDeliveryMethodType"/>
<!-- SharedSecretDeliveryMethodType -->
<simpleType name="SharedSecretDeliveryMethodType">
<annotation>
<documentation xml:lang="en">
Can be one of the following transports.
</documentation>
</annotation>
<restriction base="string">
<enumeration value="HTTPS"/>
<enumeration value="SMS"/>
</restriction>
</simpleType>
<element name="SupportedEncryptionAlgorithm" type="pskc:EncryptionAlgorithmType"/>
<!-- Credential Type -->
<complexType name="CredentialType">
<choice>
<element name="SecretContainer" type="pskc:SecretContainerType"/>
<any namespace="##other" processContents="strict"/>
</choice>
<attribute name="format" type="kp:CredentialFormatType" default="PSKC"/>
</complexType>
<element name="GetSharedSecretResponse" type="kp:GetSharedSecretResponseType"/>
<!-- GetSharedSecretResponseType -->
<complexType name="GetSharedSecretResponseType">
<annotation>
<documentation xml:lang="en">
Type for a shared-secret provisioning response.
SharedSecretDeliveryMechanism specifies the mechanism being used for
delivering the shared-secret e.g. via HTTPS or SMS.
</documentation>
</annotation>
<complexContent>
<extension base="kp:ResponseAbstractType">
<sequence minOccurs="0">
<element ref="kp:SharedSecretDeliveryMethod" minOccurs="0"/>
<element name="Credential" type="kp:CredentialType" minOccurs="0"/>
<element name="Extension" type="kp:ExtensionType" minOccurs="0"
maxOccurs="unbounded"/>
25
</sequence>
</extension>
</complexContent>
</complexType>
</schema>
8 References
[OATH]
"Initiative for Open AuTHentication",
URL: http://www.openauthentication.org
A. Vassilev et., “Portable Shared Secret Container”,
IETF Draft URL: http://www.ietf.org/internet-drafts/draft-vassilev-portablesymmetric-key-container-00.txt
[PSKC]
[PKCS12] RSA Laboratories, "PKCS #12: Personal Information Exchange
Syntax Standard", Version 1.0,
URL: ftp://ftp.rsasecurity.com/pub/pkcs/pkcs-12/.
[PKCS5] RSA Laboratories, "PKCS #5: Password-Based Cryptography
Standard", Version 2.0, URL: ftp://ftp.rsasecurity.com/pub/pkcs/pkcs-5/,
March 1999.
[XMLSIG] Eastlake, D., "XML-Signature Syntax and Processing",
URL: http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/,
W3C Recommendation, February 2002.
9 Acknowledgments
Parts of this document are based on merits in provisioning protocols from VeriSign and
Diversinet. OATH provisioning group produced use cases and requirements for an
industry wide protocol, and drove to define OATH provisioning protocol. This includes
the following individuals in the group from OATH member companies: Stu Vaeth
(Diversinet), Phillip Hallam-Baker (VeriSign), Siddharth Bajaj (VeriSign), Susan Cannon
(SanDisk), Jon Martinsson (Portwise), Jeffrey Bohren (BMC), Philip Hoyer
(ActiveIdentity), Ron LaPedis (SanDisk), Kevin Lewis (SanDisk), Robert Zuccherato
(Entrust), Jim Spring (Ironkey), and Shuh Chang (Gemalto).
Appendix A: Web Service Definition
TBD
26