RFC 6063
Dynamic Symmetric Key Provisioning Protocol (DSKPP)
4. Four-Pass Protocol Usage
This section describes the methods and message flow that comprise the four-pass protocol variant. Four-pass DSKPP depends on a client- server key agreement mechanism.4.1. The Key Agreement Mechanism
With four-pass DSKPP, the symmetric key that is the target of provisioning, is generated on-the-fly without being transferred between the DSKPP Client and DSKPP Server. The data flow and computation are described below.4.1.1. Data Flow
A sample data flow showing key generation during the four-pass protocol is shown in Figure 3.
+----------------------+ +----------------------+ | +------------+ | | | | | Server key | | | | | +<-| Public |------>------------->-------------+---------+ | | | | Private | | | | | | | | +------------+ | | | | | | | | | | | | | | V V | | V V | | | +---------+ | | +---------+ | | | | | Decrypt |<-------<-------------<-----------| Encrypt | | | | | +---------+ | | +---------+ | | | | | +--------+ | | ^ | | | | | | Server | | | | | | | | | | Random |--->------------->------+ +----------+ | | | | | +--------+ | | | | Client | | | | | | | | | | | Random | | | | | | | | | | +----------+ | | | | | | | | | | | | | | V V | | V V | | | | +------------+ | | +------------+ | | | +-->| DSKPP PRF | | | | DSKPP PRF |<----+ | | +------------+ | | +------------+ | | | | | | | | V | | V | | +-------+ | | +-------+ | | | Key | | | | Key | | | +-------+ | | +-------+ | | +-------+ | | +-------+ | | |Key Id |-------->------------->------|Key Id | | | +-------+ | | +-------+ | +----------------------+ +----------------------+ DSKPP Server DSKPP Client Figure 3: Principal Data Flow for DSKPP Key Generation Using Public Server Key The inclusion of the two random nonces (R_S and R_C) in the key generation provides assurance to both sides (the cryptographic module and the DSKPP Server) that they have contributed to the key's randomness and that the key is unique. The inclusion of the encryption key (K) ensures that no man in the middle may be present, or else the cryptographic module will end up with a key different from the one stored by the legitimate DSKPP Server. Conceptually, although R_C is one pseudorandom string, it may be viewed as consisting of two components, R_C1 and R_C2, where R_C1 is generated during the protocol run, and R_C2 can be pre-generated and
loaded on the cryptographic module before the device is issued to the user. In that case, the latter string, R_C2, SHOULD be unique for each cryptographic module. A man in the middle (in the form of corrupt client software or a mistakenly contacted server) may present his own public key to the cryptographic module. This will enable the attacker to learn the client's version of K_TOKEN. However, the attacker is not able to persuade the legitimate server to derive the same value for K_TOKEN, since K_TOKEN is a function of the public key involved, and the attacker's public key must be different than the correct server's (or else the attacker would not be able to decrypt the information received from the client). Therefore, once the attacker is no longer "in the middle," the client and server will detect that they are "out of sync" when they try to use their keys. In the case of encrypting R_C with K_SERVER, it is therefore important to verify that K_SERVER really is the legitimate server's key. One way to do this is to independently validate a newly generated K_TOKEN against some validation service at the server (e.g., using a connection independent from the one used for the key generation).4.1.2. Computation
In four-pass DSKPP, the client and server both generate K_TOKEN and K_MAC by deriving them from a provisioning key (K_PROV) using the DSKPP-PRF (refer to Section 3.4.2) as follows: K_PROV = DSKPP-PRF(k,s,dsLen), where k = R_C (i.e., the secret random value chosen by the DSKPP Client) s = "Key generation" || K || R_S (where K is the key used to encrypt R_C and R_S is the random value chosen by the DSKPP Server) dsLen = (desired length of K_PROV whose first half constitutes K_MAC and second half constitutes K_TOKEN) Then, K_TOKEN and K_MAC are derived from K_PROV, where K_PROV = K_MAC || K_TOKEN When computing K_PROV, the derived keys, K_MAC and K_TOKEN, MAY be subject to an algorithm-dependent transform before being adopted as a key of the selected type. One example of this is the need for parity in DES keys. Note that this computation pertains to four-pass DSKPP only.
4.2. Message Flow
The four-pass protocol flow consists of two message exchanges: 1: Pass 1 = <KeyProvClientHello>, Pass 2 = <KeyProvServerHello> 2: Pass 3 = <KeyProvClientNonce>, Pass 4 = <KeyProvServerFinished> The first pair of messages negotiate cryptographic algorithms and exchange nonces. The second pair of messages establishes a symmetric key using mutually authenticated key agreement. The purpose and content of each message are described below. XML format and examples are in Section 8 and Appendix B.4.2.1. KeyProvTrigger
DSKPP Client DSKPP Server ------------ ------------ [<---] AD, [DeviceID], [KeyID], [URL_S] When this message is sent: The "trigger" message is optional. The DSKPP Server sends this message after the following out-of-band steps are performed: 1. A user directed their browser to a key provisioning web application and signs in (i.e., authenticates). 2. The user requests a key. 3. The web application processes the request and returns an Authentication Code to the user, e.g., in response to an enrollment request via a secure web session. 4. The web application retrieves the Authentication Code from the user (possibly by asking the user to enter it using a web form, or alternatively by the user selecting a URL in which the Authentication Code is embedded). 5. The web application derives Authentication Data (AD) from the Authentication Code as described in Section 3.4.1. 6. The web application passes AD, and possibly a DeviceID (identifies a particular device to which the key is to be provisioned) and/or KeyID (identifies a key that will be replaced) to the DSKPP Server. Purpose of this message: To start a DSKPP session: The DSKPP Server uses this message to trigger a client-side application to send the first DSKPP message. To provide a way for the key provisioning system to get the DSKPP Server URL to the DSKPP Client.
So the key provisioning system can point the DSKPP Client to a
particular cryptographic module that was pre-configured in the
DSKPP provisioning server.
In the case of key renewal, to identify the key to be replaced.
What is contained in this message:
AD MUST be provided to allow the DSKPP Server to authenticate the
user before completing the protocol run.
A DeviceID MAY be included to allow a key provisioning application
to bind the provisioned key to a specific device.
A KeyID MAY be included to allow the key provisioning application
to identify a key to be replaced, e.g., in the case of key
renewal.
The Server URL MAY be included to allow the key provisioning
application to inform the DSKPP Client of which server to contact.
4.2.2. KeyProvClientHello
DSKPP Client DSKPP Server
------------ ------------
SAL, [AD],
[DeviceID], [KeyID] --->
When this message is sent:
When a DSKPP Client first connects to a DSKPP Server, it is
required to send the <KeyProvClientHello> as its first message.
The client can also send a <KeyProvClientHello> in response to a
<KeyProvTrigger>.
What is contained in this message:
The Security Attribute List (SAL) included with
<KeyProvClientHello> contains the combinations of DSKPP versions,
variants, key package formats, key types, and cryptographic
algorithms that the DSKPP Client supports in order of the client's
preference (favorite choice first).
If <KeyProvClientHello> was preceded by a <KeyProvTrigger>, then
this message MUST also include the Authentication Data (AD),
DeviceID, and/or KeyID that was provided with the trigger.
If <KeyProvClientHello> was not preceded by a <KeyProvTrigger>,
then this message MAY contain a DeviceID that was pre-shared with
the DSKPP Server, and a key ID associated with a key previously
provisioned by the DSKPP provisioning server.
Application note:
If this message is preceded by trigger message <KeyProvTrigger>,
then the application will already have AD available (see
Section 4.2.1). However, if this message was not preceded by
<KeyProvTrigger>, then the application MUST retrieve the User
Authentication Code, possibly by prompting the user to manually
enter their Authentication Code, e.g., on a device with only a
numeric keypad.
The application MUST also derive Authentication Data (AD) from the
Authentication Code, as described in Section 3.4.1, and save it
for use in its next message, <KeyProvClientNonce>.
How the DSKPP Server uses this message:
The DSKPP Server will look for an acceptable combination of DSKPP
version, variant (in this case, four-pass), key package format,
key type, and cryptographic algorithms. If the DSKPP Client's SAL
does not match the capabilities of the DSKPP Server, or does not
comply with key provisioning policy, then the DSKPP Server will
set the Status attribute to something other than "Continue".
Otherwise, the Status attribute will be set to "Continue".
If included in <KeyProvClientHello>, the DSKPP Server will
validate the Authentication Data (AD), DeviceID, and KeyID. The
DSKPP Server MUST NOT accept the DeviceID unless the server sent
the DeviceID in a preceding trigger message. Note that it is also
legitimate for a DSKPP Client to initiate the DSKPP run without
having received a <KeyProvTrigger> message from a server, but in
this case any provided DeviceID MUST NOT be accepted by the DSKPP
Server unless the server has access to a unique key for the
identified device and that key will be used in the protocol.
4.2.3. KeyProvServerHello
DSKPP Client DSKPP Server
------------ ------------
<--- SAL, R_S, [K], [MAC]
When this message is sent:
The DSKPP Server will send this message in response to a
<KeyProvClientHello> message after it looks for an acceptable
combination of DSKPP version, variant (in this case, four-pass),
key package format, key type, and set of cryptographic algorithms.
If it could not find an acceptable combination, then it will still
send the message, but with a failure status.
Purpose of this message:
With this message, the context for the protocol run is set.
Furthermore, the DSKPP Server uses this message to transmit a
random nonce, which is required for each side to agree upon the
same symmetric key (K_TOKEN).
What is contained in this message:
A status attribute equivalent to the server's return code to
<KeyProvClientHello>. If the server found an acceptable set of
attributes from the client's SAL, then it sets status to Continue
and returns an SAL (selected from the SAL that it received in
<KeyProvClientHello>). The Server's SAL specifies the DSKPP
version and variant (in this case, four-pass), key type,
cryptographic algorithms, and key package format that the DSKPP
Client MUST use for the remainder of the protocol run.
A random nonce (R_S) for use in generating a symmetric key through
key agreement; the length of R_S may depend on the selected key
type.
A key (K) for the DSKPP Client to use for encrypting the client
nonce included with <KeyProvClientNonce>. K represents the
server's public key (K_SERVER) or a pre-shared secret key
(K_SHARED).
A MAC MUST be present if a key is being renewed so that the DSKPP
Client can confirm that the replacement key came from a trusted
server. This MAC MUST be computed using DSKPP-PRF (see
Section 3.4.2), where the input parameter k MUST be set to the
existing MAC key K_MAC' (i.e., the value of the MAC key that
existed before this protocol run; the implementation MAY specify
K_MAC' to be the value of the K_TOKEN that is being replaced), and
input parameter dsLen MUST be set to the length of R_S.
How the DSKPP Client uses this message:
When the Status attribute is not set to "Continue", this indicates
failure and the DSKPP Client MUST abort the protocol.
If successful execution of the protocol will result in the
replacement of an existing key with a newly generated one, the
DSKPP Client MUST verify the MAC provided in <KeyProvServerHello>.
The DSKPP Client MUST terminate the DSKPP session if the MAC does
not verify, and MUST delete any nonces, keys, and/or secrets
associated with the failed run.
If the Status attribute is set to "Continue", the cryptographic
module generates a random nonce (R_C) using the cryptographic
algorithm specified in the SAL. The length of the nonce R_C will
depend on the selected key type.
Encrypt R_C using K and the encryption algorithm included in the
SAL.
The method the DSKPP Client MUST use to encrypt R_C:
If K is equivalent to K_SERVER (i.e., the public key of the DSKPP
Server), then an RSA encryption scheme from PKCS #1 [PKCS-1] MAY
be used. If K is equivalent to K_SERVER, then the cryptographic
module SHOULD verify the server's certificate before using it to
encrypt R_C as described in [RFC2818], Section 3.1, and [RFC5280].
If K is equivalent to K_SHARED, the DSKPP Client MAY use the
DSKPP-PRF to avoid dependence on other algorithms. In this case,
the client uses K_SHARED as input parameter k (K_SHARED SHOULD be
used solely for this purpose) as follows:
dsLen = len(R_C), where "len" is the length of R_C
DS = DSKPP-PRF(K_SHARED, "Encryption" || R_S, dsLen)
This will produce a pseudorandom string DS of length equal to R_C.
Encryption of R_C MAY then be achieved by XOR-ing DS with R_C:
E(DS, R_C) = DS ^ R_C
The DSKPP Server will then perform the reverse operation to
extract R_C from E(DS, R_C).
4.2.4. KeyProvClientNonce
DSKPP Client DSKPP Server
------------ ------------
E(K,R_C), AD --->
When this message is sent:
The DSKPP Client will send this message immediately following a
<KeyProvServerHello> message whose status was set to "Continue".
Purpose of this message:
With this message the DSKPP Client transmits User Authentication
Data (AD) and a random nonce encrypted with the DSKPP Server's key
(K). The client's random nonce is required for each side to agree
upon the same symmetric key (K_TOKEN).
What is contained in this message:
Authentication Data (AD) that was derived from an Authentication
Code entered by the user before <KeyProvClientHello> was sent
(refer to Section 3.2).
The DSKPP Client's random nonce (R_C), which was encrypted as
described in Section 4.2.3.
How the DSKPP Server uses this message:
The DSKPP Server MUST use AD to authenticate the user. If
authentication fails, then the DSKPP Server MUST set the return
code to a failure status.
If user authentication passes, the DSKPP Server decrypts R_C using
its key (K). The decryption method is based on whether K that was
transmitted to the client in <KeyProvServerHello> was equal to the
server's public key (K_SERVER) or a pre-shared key (K_SHARED)
(refer to Section 4.2.3 for a description of how the DSKPP Client
encrypts R_C).
After extracting R_C, the DSKPP Server computes K_TOKEN using a
combination of the two random nonces R_S and R_C and its
encryption key, K, as described in Section 4.1.2. The particular
realization of DSKPP-PRF (e.g., those defined in Appendix D)
depends on the MAC algorithm contained in the <KeyProvServerHello>
message. The DSKPP Server then generates a key package that
contains key usage attributes such as expiry date and length. The
key package MUST NOT include K_TOKEN since in the four-pass
variant K_TOKEN is never transmitted between the DSKPP Server and
Client. The server stores K_TOKEN and the key package with the
user's account on the cryptographic server.
Finally, the server generates a key confirmation MAC that the
client will use to avoid a false "Commit" message that would cause
the cryptographic module to end up in state in which the server
does not recognize the stored key.
The MAC used for key confirmation MUST be calculated as follows:
msg_hash = SHA-256(msg_1, ..., msg_n)
dsLen = len(msg_hash)
MAC = DSKPP-PRF (K_MAC, "MAC 1 computation" || msg_hash, dsLen)
where
MAC The DSKPP Pseudorandom Function defined in Section 3.4.2 is
used to compute the MAC. The particular realization of DSKPP-
PRF (e.g., those defined in Appendix D) depends on the MAC
algorithm contained in the <KeyProvServerHello> message. The
MAC MUST be computed using the existing MAC key (K_MAC), and a
string that is formed by concatenating the (ASCII) string "MAC
1 computation" and a msg_hash.
K_MAC The key derived from K_PROV, as described in Section 4.1.2.
msg_hash The message hash (defined in Section 3.4.3) of messages
msg_1, ..., msg_n.
4.2.5. KeyProvServerFinished
DSKPP Client DSKPP Server
------------ ------------
<--- KP, MAC
When this message is sent:
The DSKPP Server will send this message after authenticating the
user and, if authentication passed, generating K_TOKEN and a key
package, and associating them with the user's account on the
cryptographic server.
Purpose of this message:
With this message, the DSKPP Server confirms generation of the key
(K_TOKEN) and transmits the associated identifier and application-
specific attributes, but not the key itself, in a key package to
the client for protocol completion.
What is contained in this message:
A status attribute equivalent to the server's return code to
<KeyProvClientNonce>. If user authentication passed, and the
server successfully computed K_TOKEN, generated a key package, and
associated them with the user's account on the cryptographic
server, then it sets the Status attribute to "Success".
If the Status attribute is set to "Success", then this message
acts as a "Commit" message, instructing the cryptographic module
to store the generated key (K_TOKEN) and associate the given key
identifier with this key. As such, a key package (KP) MUST be
included in this message, which holds an identifier for the
generated key (but not the key itself) and additional
configuration, e.g., the identity of the DSKPP Server, key usage
attributes, etc. The default symmetric key package format MUST be
based on the Portable Symmetric Key Container (PSKC) defined in
[RFC6030]. Alternative formats MAY include [RFC6031], PKCS #12
[PKCS-12], or PKCS #5 XML [PKCS-5-XML] format.
With KP, the server includes a key confirmation MAC that the
client uses to avoid a false "Commit" message. The MAC algorithm
is the same DSKPP-PRF that was sent in the <KeyProvServerHello>
message.
How the DSKPP Client uses this message:
When the Status attribute is not set to "Success", this indicates
failure and the DSKPP Client MUST abort the protocol.
After receiving a <KeyProvServerFinished> message with Status =
"Success", the DSKPP Client MUST verify the key confirmation MAC
that was transmitted with this message. The DSKPP Client MUST
terminate the DSKPP session if the MAC does not verify, and MUST,
in this case, also delete any nonces, keys, and/or secrets
associated with the failed run of the protocol.
If <KeyProvServerFinished> has Status = "Success", and the MAC was
verified, then the DSKPP Client MUST calculate K_TOKEN from the
combination of the two random nonces R_S and R_C and the server's
encryption key, K, as described in Section 4.1.2. The DSKPP-PRF
is the same one used for MAC computation. The DSKPP Client
associates the key package contained in <KeyProvServerFinished>
with the generated key, K_TOKEN, and stores this data permanently
on the cryptographic module.
After this operation, it MUST NOT be possible to overwrite the key
unless knowledge of an authorizing key is proven through a MAC on
a later <KeyProvServerHello> (and <KeyProvServerFinished>)
message.
5. Two-Pass Protocol Usage
This section describes the methods and message flow that comprise the
two-pass protocol variant. Two-pass DSKPP is essentially a transport
of keying material from the DSKPP Server to the DSKPP Client. The
DSKPP Server transmits keying material in a key package formatted in
accordance with [RFC6030], [RFC6031], PKCS #12 [PKCS-12], or PKCS #5
XML [PKCS-5-XML].
The keying material includes a provisioning master key, K_PROV, from
which the DSKPP Client derives two keys: the symmetric key to be
established in the cryptographic module, K_TOKEN, and a key, K_MAC,
used for key confirmation. The keying material also includes key
usage attributes, such as expiry date and length.
The DSKPP Server encrypts K_PROV to ensure that it is not exposed to any other entity than the DSKPP Server and the cryptographic module itself. The DSKPP Server uses any of three key protection methods to encrypt K_PROV: Key Transport, Key Wrap, and Passphrase-Based Key Wrap Key Protection methods. While the DSKPP Client and server may negotiate the key protection method to use, the actual key protection is carried out in the KeyPackage. The format of a KeyPackage specifies how a key should be protected using the three key protection methods. The following KeyPackage formats are defined for DSKPP: o PSKC Key Container [RFC6030] at urn:ietf:params:xml:ns:keyprov:dskpp:pskc-key-container o SKPC Key Container [RFC6031] at urn:ietf:params:xml:ns:keyprov:dskpp:skpc-key-container o PKCS12 Key Container [PKCS-12] at urn:ietf:params:xml:ns:keyprov:dskpp:pkcs12-key-container o PKCS5-XML Key Container [PKCS-5-XML] at urn:ietf:params:xml:ns:keyprov:dskpp:pkcs5-xml-key-container Each of the key protection methods is described below.5.1. Key Protection Methods
This section introduces three key protection methods for the two-pass variant. Additional methods MAY be defined by external entities or through the IETF process.5.1.1. Key Transport
Purpose of this method: This method is intended for PKI-capable devices. The DSKPP Server encrypts keying material and transports it to the DSKPP Client. The server encrypts the keying material using the public key of the DSKPP Client, whose private key part resides in the cryptographic module. The DSKPP Client decrypts the keying material and uses it to derive the symmetric key, K_TOKEN. This method is identified with the following URN: urn:ietf:params:xml:schema:keyprov:dskpp:transport The DSKPP Server and Client MUST support the following mechanism: http://www.w3.org/2001/04/xmlenc#rsa-1_5 encryption mechanism defined in [XMLENC].
5.1.2. Key Wrap
Purpose of this method: This method is ideal for pre-keyed devices, e.g., SIM cards. The DSKPP Server encrypts keying material using a pre-shared key wrapping key and transports it to the DSKPP Client. The DSKPP Client decrypts the keying material, and uses it to derive the symmetric key, K_TOKEN. This method is identified with the following URN: urn:ietf:params:xml:schema:keyprov:dskpp:wrap The DSKPP Server and Client MUST support all of the following key wrapping mechanisms: AES128 KeyWrap Refer to id-aes128-wrap in [RFC3394] and http://www.w3.org/2001/04/xmlenc#kw-aes128 in [XMLENC] AES128 KeyWrap with Padding Refer to id-aes128-wrap-pad in [RFC5649] and http://www.w3.org/2001/04/xmlenc#kw-aes128 in [XMLENC] AES-CBC-128 Refer to [FIPS197-AES] and http://www.w3.org/2001/04/xmlenc#aes128-cbc in [XMLENC]5.1.3. Passphrase-Based Key Wrap
Purpose of this method: This method is a variation of the Key Wrap Method that is applicable to constrained devices with keypads, e.g., mobile phones. The DSKPP Server encrypts keying material using a wrapping key derived from a user-provided passphrase, and transports the encrypted material to the DSKPP Client. The DSKPP Client decrypts the keying material, and uses it to derive the symmetric key, K_TOKEN. To preserve the property of not exposing K_TOKEN to any other entity than the DSKPP Server and the cryptographic module itself, the method SHOULD be employed only when the device contains facilities (e.g., a keypad) for direct entry of the passphrase. This method is identified with the following URN: urn:ietf:params:xml:schema:keyprov:dskpp:passphrase-wrap
The DSKPP Server and Client MUST support the following:
* The PBES2 password-based encryption scheme defined in [PKCS-5]
(and identified as
http://www.rsasecurity.com/rsalabs/pkcs/schemas/pkcs-5#pbes2 in
[PKCS-5-XML]).
* The PBKDF2 passphrase-based key derivation function also
defined in [PKCS-5] (and identified as
http://www.rsasecurity.com/rsalabs/pkcs/schemas/pkcs-5#pbkdf2
in [PKCS-5-XML]).
* All of the following key wrapping mechanisms:
AES128 KeyWrap
Refer to id-aes128-wrap in [RFC3394] and
http://www.w3.org/2001/04/xmlenc#kw-aes128 in [XMLENC]
AES128 KeyWrap with Padding
Refer to id-aes128-wrap-pad in [RFC5649] and
http://www.w3.org/2001/04/xmlenc#kw-aes128 in [XMLENC]
AES-CBC-128
Refer to [FIPS197-AES] and
http://www.w3.org/2001/04/xmlenc#aes128-cbc in [XMLENC]
5.2. Message Flow
The two-pass protocol flow consists of one exchange:
1: Pass 1 = <KeyProvClientHello>, Pass 2 = <KeyProvServerFinished>
Although there is no exchange of the <ServerHello> message or the
<ClientNonce> message, the DSKPP Client is still able to specify
algorithm preferences and supported key types in the
<KeyProvClientHello> message.
The purpose and content of each message are described below. XML
format and examples are in Section 8 and Appendix B.
5.2.1. KeyProvTrigger
The trigger message is used in exactly the same way for the two-pass
variant as for the four-pass variant; refer to Section 4.2.1.
5.2.2. KeyProvClientHello
DSKPP Client DSKPP Server ------------ ------------ SAL, AD, R_C, [DeviceID], [KeyID], KPML ---> When this message is sent: When a DSKPP Client first connects to a DSKPP Server, it is required to send the <KeyProvClientHello> as its first message. The client can also send <KeyProvClientHello> in response to a <KeyProvTrigger> message. Purpose of this message: With this message, the DSKPP Client specifies its algorithm preferences and supported key types as well as which DSKPP versions, protocol variants (in this case "two-pass"), key package formats, and key protection methods that it supports. Furthermore, the DSKPP Client facilitates user authentication by transmitting the Authentication Data (AD) that was provided by the user before the first DSKPP message was sent. Application note: This message MUST send User Authentication Data (AD) to the DSKPP Server. If this message is preceded by trigger message <KeyProvTrigger>, then the application will already have AD available (see Section 4.2.1). However, if this message was not preceded by <KeyProvTrigger>, then the application MUST retrieve the User Authentication Code, possibly by prompting the user to manually enter their Authentication Code, e.g., on a device with only a numeric keypad. The application MUST also derive Authentication Data (AD) from the Authentication Code, as described in Section 3.4.1, and save it for use in its next message, <KeyProvClientNonce>. What is contained in this message: The Security Attribute List (SAL) included with <KeyProvClientHello> contains the combinations of DSKPP versions, variants, key package formats, key types, and cryptographic algorithms that the DSKPP Client supports in order of the client's preference (favorite choice first). Authentication Data (AD) that was either included with <KeyProvTrigger>, or generated as described in the "Application Note" above.
The DSKPP Client's random nonce (R_C), which was used by the
client when generating AD. By inserting R_C into the DSKPP
session, the DSKPP Client is able to ensure the DSKPP Server is
live before committing the key.
If <KeyProvClientHello> was preceded by a <KeyProvTrigger>, then
this message MUST also include the DeviceID and/or KeyID that was
provided with the trigger. Otherwise, if a trigger message did
not precede <KeyProvClientHello>, then this message MAY include a
DeviceID that was pre-shared with the DSKPP Server, and MAY
contain a key ID associated with a key previously provisioned by
the DSKPP provisioning server.
The list of key protection methods (KPML) that the DSKPP Client
supports. Each item in the list MAY include an encryption key
"payload" for the DSKPP Server to use to protect keying material
that it sends back to the client. The payload MUST be of type
<ds:KeyInfoType> ([XMLDSIG]). For each key protection method, the
allowable choices for <ds:KeyInfoType> are:
* Key Transport
Only those choices of <ds:KeyInfoType> that identify a public
key (i.e., <ds:KeyName>, <ds:KeyValue>, <ds:X509Data>, or <ds:
PGPData>). The <ds:X509Certificate> option of the <ds:
X509Data> alternative is RECOMMENDED when the public key
corresponding to the private key on the cryptographic module
has been certified.
* Key Wrap
Only those choices of <ds:KeyInfoType> that identify a
symmetric key (i.e., <ds:KeyName> and <ds:KeyValue>). The <ds:
KeyName> alternative is RECOMMENDED.
* Passphrase-Based Key Wrap
The <ds:KeyName> option MUST be used and the key name MUST
identify the passphrase that will be used by the server to
generate the key wrapping key. The identifier and passphrase
components of <ds:KeyName> MUST be set to the Client ID and
Authentication Code components of AD (same AD as contained in
this message).
How the DSKPP Server uses this message:
The DSKPP Server will look for an acceptable combination of DSKPP
version, variant (in this case, two-pass), key package format, key
type, and cryptographic algorithms. If the DSKPP Client's SAL
does not match the capabilities of the DSKPP Server, or does not
comply with key provisioning policy, then the DSKPP Server will
set the Status attribute to something other than "Success".
Otherwise, the Status attribute will be set to "Success".
The DSKPP Server will validate the DeviceID and KeyID if included
in <KeyProvClientHello>. The DSKPP Server MUST NOT accept the
DeviceID unless the server sent the DeviceID in a preceding
trigger message. Note that it is also legitimate for a DSKPP
Client to initiate the DSKPP run without having received a
<KeyProvTrigger> message from a server, but in this case any
provided DeviceID MUST NOT be accepted by the DSKPP Server unless
the server has access to a unique key for the identified device
and that key will be used in the protocol.
The DSKPP Server MUST use AD to authenticate the user. If
authentication fails, then the DSKPP Server MUST set the return
code to a failure status, and MUST, in this case, also delete any
nonces, keys, and/or secrets associated with the failed run of the
protocol.
If user authentication passes, the DSKPP Server generates a key
K_PROV. In the two-pass case, wherein the client does not have
access to R_S, K_PROV is randomly generated solely by the DSKPP
Server wherein K_PROV MUST consist of two parts of equal length,
i.e.,
K_PROV = K_MAC || K_TOKEN
The length of K_TOKEN (and hence also the length of K_MAC) is
determined by the type of K_TOKEN, which MUST be one of the key
types supported by the DSKPP Client. In cases where the desired
key length for K_TOKEN is different from the length of K_MAC for
the underlying MAC algorithm, the greater length of the two MUST
be chosen to generate K_PROV. The actual MAC key is truncated
from the resulting K_MAC when it is used in the MAC algorithm when
K_MAC is longer than necessary in order to match the desired
K_TOKEN length. If K_TOKEN is longer than needed in order to
match the K_MAC length, the provisioning server and the receiving
client must determine the actual secret key length from the target
key algorithm and store only the truncated portion of the K_TOKEN.
The truncation MUST take the beginning bytes of the desired length
from K_TOKEN or K_MAC for the actual key. For example, when a
provisioning server provisions an event based HOTP secret key with
length 20 and MAC algorithm DSKPP-PRF-SHA256 (Appendix D), K_PROV
length will be 64. The derived K_TOKEN and K_MAC will each
consist of 32 bytes. The actual HOTP key should be the first 20
bytes of the K_TOKEN.
Once K_PROV is computed, the DSKPP Server selects one of the key
protection methods from the DSKPP Client's KPML, and uses that
method and corresponding payload to encrypt K_PROV. The DSKPP
Server generates a key package to transport the key encryption
method information and the encrypted provisioning key (K_PROV).
The encrypted data format is subject to the choice supported by
the selected key package. The key package MUST specify and use
the selected key protection method and the key information that
was received in <KeyProvClientHello>. The key package also
includes key usage attributes such as expiry date and length. The
server stores the key package and K_TOKEN with a user account on
the cryptographic server.
The server generates a MAC for key confirmation, which the client
will use to avoid a false "Commit" message that would cause the
cryptographic module to end up in state in which the server does
not recognize the stored key.
In addition, if an existing key is being renewed, the server
generates a second MAC that it will return to the client as server
Authentication Data (AD) so that the DSKPP Client can confirm that
the replacement key came from a trusted server.
The method the DSKPP Server MUST use to calculate the key
confirmation MAC:
msg_hash = SHA-256(msg_1, ..., msg_n)
dsLen = len(msg_hash)
MAC = DSKPP-PRF (K_MAC, "MAC 1 computation" || msg_hash ||
ServerID, dsLen)
where
MAC The MAC MUST be calculated using the already
established MAC algorithm and MUST be computed on the
(ASCII) string "MAC 1 computation", msg_hash, and
ServerID using the existing MAC key K_MAC.
K_MAC The key that is derived from K_PROV, which the DSKPP
Server MUST provide to the cryptographic module.
msg_hash The message hash, defined in Section 3.4.3, of
messages msg_1, ..., msg_n.
ServerID The identifier that the DSKPP Server MUST include in
the <KeyPackage> element of <KeyProvServerFinished>.
If DSKPP-PRF (defined in Section 3.4.2) is used as the MAC
algorithm, then the input parameter s MUST consist of the
concatenation of the (ASCII) string "MAC 1 computation", msg_hash,
and ServerID, and the parameter dsLen MUST be set to the length of
msg_hash.
The method the DSKPP Server MUST use to calculate the server
authentication MAC:
The MAC MUST be computed on the (ASCII) string "MAC 2
computation", the server identifier ServerID, and R, using a pre-
existing MAC key K_MAC' (the MAC key that existed before this
protocol run). Note that the implementation may specify K_MAC' to
be the value of the K_TOKEN that is being replaced.
If DSKPP-PRF is used as the MAC algorithm, then the input
parameter s MUST consist of the concatenation of the (ASCII)
string "MAC 2 computation" ServerID, and R. The parameter dsLen
MUST be set to at least 16 (i.e., the length of the MAC MUST be at
least 16 octets):
dsLen >= 16
MAC = DSKPP-PRF (K_MAC', "MAC 2 computation" || ServerID || R,
dsLen)
The MAC algorithm MUST be the same as the algorithm used by the
DSKPP Server to calculate the key confirmation MAC.
5.2.3. KeyProvServerFinished
DSKPP Client DSKPP Server
------------ ------------
<--- KP, MAC, AD
When this message is sent:
The DSKPP Server will send this message after authenticating the
user and, if authentication passed, generating K_TOKEN and a key
package, and associating them with the user's account on the
cryptographic server.
Purpose of this message:
With this message, the DSKPP Server transports a key package
containing the encrypted provisioning key (K_PROV) and key usage
attributes.
What is contained in this message:
A Status attribute equivalent to the server's return code to
<KeyProvClientHello>. If the server found an acceptable set of
attributes from the client's SAL, then it sets Status to
"Success".
The confirmation message MUST include the Key Package (KP) that
holds the DSKPP Server's ID, key ID, key type, encrypted
provisioning key (K_PROV), encryption method, and additional
configuration information. The default symmetric key package
format MUST be based on the Portable Symmetric Key Container
(PSKC) defined in [RFC6030]. Alternative formats MAY include
[RFC6031], PKCS #12 [PKCS-12], or PKCS #5 XML [PKCS-5-XML].
This message MUST include a MAC that the DSKPP Client will use for
key confirmation. This key confirmation MAC is calculated using
the "MAC 1 computation" as described in the previous section.
Finally, if an existing key is being replaced, then this message
MUST also include a server authentication MAC (calculated using
the "MAC 2 computation" as described in the previous section),
which is passed as AD to the DSKPP Client.
How the DSKPP Client uses this message:
After receiving a <KeyProvServerFinished> message with Status =
"Success", the DSKPP Client MUST verify both MACs (MAC and AD).
The DSKPP Client MUST terminate the DSKPP run if either MAC does
not verify, and MUST, in this case, also delete any nonces, keys,
and/or secrets associated with the failed run of the protocol.
If <KeyProvServerFinished> has Status = "Success" and the MACs
were verified, then the DSKPP Client MUST extract K_PROV from the
provided key package, and derive K_TOKEN. Finally, the DSKPP
Client initializes the cryptographic module with K_TOKEN and the
corresponding key usage attributes. After this operation, it MUST
NOT be possible to overwrite the key unless knowledge of an
authorizing key is proven through a MAC on a later
<KeyProvServerFinished> message.
6. Protocol Extensions
DSKPP has been designed to be extensible. The sub-sections below
define two extensions that are included with the DSKPP schema. Since
it is possible that the use of extensions will harm interoperability,
protocol designers are advised to carefully consider the use of
extensions. For example, if a particular implementation relies on
the presence of a proprietary extension, then it may not be able to interoperate with independent implementations that have no knowledge of this extension. Extensions may be sent with any DSKPP message using the ExtensionsType. The ExtensionsType type is a list of Extensions containing type-value pairs that define optional features supported by a DSKPP Client or server. Each extension MAY be marked as Critical by setting the Critical attribute of the Extension to "true". Unless an extension is marked as Critical, a receiving party need not be able to interpret it; a receiving party is always free to disregard any (non-critical) extensions.6.1. The ClientInfoType Extension
The ClientInfoType extension MAY contain any client-specific data required of an application. This extension MAY be present in a <KeyProvClientHello> or <KeyProvClientNonce> message. When present, this extension MUST NOT be marked as Critical. DSKPP Servers MUST support this extension. DSKPP Servers MUST NOT attempt to interpret the data it carries and, if received, MUST include it unmodified in the current protocol run's next server response. DSKPP Servers need not retain the ClientInfoType data.6.2. The ServerInfoType Extension
The ServerInfoType extension MAY contain any server-specific data required of an application, e.g., state information. This extension is only valid in <KeyProvServerHello> messages for which the Status attribute is set to "Continue". When present, this extension MUST NOT be marked as Critical. DSKPP Clients MUST support this extension. DSKPP Clients MUST NOT attempt to interpret the data it carries and, if received, MUST include it unmodified in the current protocol run's next client request (i.e., the <KeyProvClientNonce> message). DSKPP Clients need not retain the ServerInfoType data.7. Protocol Bindings
7.1. General Requirements
DSKPP assumes a reliable transport.
7.2. HTTP/1.1 Binding for DSKPP
This section presents a binding of the previous messages to HTTP/1.1 [RFC2616]. This HTTP binding is mandatory to implement, although newer versions of the specification might define additional bindings in the future. Note that the HTTP client will normally be different from the DSKPP Client (i.e., the HTTP client will "proxy" DSKPP messages from the DSKPP Client to the DSKPP Server). Likewise, on the HTTP server side, the DSKPP Server MAY receive DSKPP message from a "front-end" HTTP server. The DSKPP Server will be identified by a specific URL, which may be pre-configured, or provided to the client during initialization.7.2.1. Identification of DSKPP Messages
The MIME type for all DSKPP messages MUST be application/dskpp+xml7.2.2. HTTP Headers
In order to avoid caching of responses carrying DSKPP messages by proxies, the following holds: o When using HTTP/1.1, requesters SHOULD: * Include a Cache-Control header field set to "no-cache, no- store". * Include a Pragma header field set to "no-cache". o When using HTTP/1.1, responders SHOULD: * Include a Cache-Control header field set to "no-cache, no-must- revalidate, private". * Include a Pragma header field set to "no-cache". * NOT include a Validator, such as a Last-Modified or ETag header. To handle content negotiation, HTTP requests MAY include an HTTP Accept header field. This header field SHOULD should be identified using the MIME type specified in Section 7.2.1. The Accept header MAY include additional content types defined by future versions of this protocol. There are no other restrictions on HTTP headers, besides the requirement to set the Content-Type header value to the MIME type specified in Section 7.2.1.
7.2.3. HTTP Operations
Persistent connections as defined in HTTP/1.1 are OPTIONAL. DSKPP requests are mapped to HTTP requests with the POST method. DSKPP responses are mapped to HTTP responses. For the four-pass DSKPP, messages within the protocol run are bound together. In particular, <KeyProvServerHello> is bound to the preceding <KeyProvClientHello> by being transmitted in the corresponding HTTP response. <KeyProvServerHello> MUST have a SessionID attribute, and the SessionID attribute of the subsequent <KeyProvClientNonce> message MUST be identical. <KeyProvServerFinished> is then once again bound to the rest through HTTP (and possibly through a SessionID).7.2.4. HTTP Status Codes
A DSKPP HTTP responder that refuses to perform a message exchange with a DSKPP HTTP requester SHOULD return a 403 (Forbidden) response. In this case, the content of the HTTP body is not significant. In the case of an HTTP error while processing a DSKPP request, the HTTP server MUST return a 500 (Internal Server Error) response. This type of error SHOULD be returned for HTTP-related errors detected before control is passed to the DSKPP processor, or when the DSKPP processor reports an internal error (for example, the DSKPP XML namespace is incorrect, or the DSKPP schema cannot be located). If a request is received that is not a DSKPP Client message, the DSKPP responder MUST return a 400 (Bad request) response. In these cases (i.e., when the HTTP response code is 4xx or 5xx), the content of the HTTP body is not significant. Redirection status codes (3xx) apply as usual. Whenever the HTTP POST is successfully invoked, the DSKPP HTTP responder MUST use the 200 status code and provide a suitable DSKPP message (possibly with DSKPP error information included) in the HTTP body.7.2.5. HTTP Authentication
No support for HTTP/1.1 authentication is assumed.7.2.6. Initialization of DSKPP
If a user requests key initialization in a browsing session, and if that request has an appropriate Accept header (e.g., to a specific DSKPP Server URL), the DSKPP Server MAY respond by sending a DSKPP
initialization message in an HTTP response with Content-Type set according to Section 7.2.1 and response code set to 200 (OK). The initialization message MAY carry data in its body, such as the URL for the DSKPP Client to use when contacting the DSKPP Server. If the message does carry data, the data MUST be a valid instance of a <KeyProvTrigger> element. Note that if the user's request was directed to some other resource, the DSKPP Server MUST NOT respond by combining the DSKPP content type with response code 200. In that case, the DSKPP Server SHOULD respond by sending a DSKPP initialization message in an HTTP response with Content-Type set according to Section 7.2.1 and response code set to 406 (Not Acceptable).7.2.7. Example Messages
a. Initialization from DSKPP Server: HTTP/1.1 200 OK Cache-Control: no-store Content-Type: application/dskpp+xml Content-Length: <some value> DSKPP initialization data in XML form... b. Initial request from DSKPP Client: POST http://example.com/cgi-bin/DSKPP-server HTTP/1.1 Cache-Control: no-cache, no-store Pragma: no-cache Host: www.example.com Content-Type: application/dskpp+xml Content-Length: <some value> DSKPP data in XML form (supported version, supported algorithms...) c. Initial response from DSKPP Server: HTTP/1.1 200 OK Cache-Control: no-cache, no-must-revalidate, private Pragma: no-cache Content-Type: application/dskpp+xml Content-Length: <some value> DSKPP data in XML form (server random nonce, server public key, ...)
(next page on part 3)
