Key Provisioning Protocol

[MS-KPP]:

Key Provisioning Protocol

Intellectual Property Rights Notice for Open Specifications Documentation

Technical Documentation. Microsoft publishes Open Specifications documentation (“this documentation”) for protocols, file formats, data portability, computer languages, and standards support. Additionally, overview documents cover inter-protocol relationships and interactions.

Copyrights. This documentation is covered by Microsoft copyrights. Regardless of any other terms that are contained in the terms of use for the Microsoft website that hosts this documentation, you can make copies of it in order to develop implementations of the technologies that are described in this documentation and can distribute portions of it in your implementations that use these technologies or in your documentation as necessary to properly document the implementation. You can also distribute in your implementation, with or without modification, any schemas, IDLs, or code samples that are included in the documentation. This permission also applies to any documents that are referenced in the Open Specifications documentation.

No Trade Secrets. Microsoft does not claim any trade secret rights in this documentation.

Patents. Microsoft has patents that might cover your implementations of the technologies described in the Open Specifications documentation. Neither this notice nor Microsoft's delivery of this documentation grants any licenses under those patents or any other Microsoft patents. However, a given Open Specifications document might be covered by the Microsoft Open Specifications Promise or the Microsoft Community Promise. If you would prefer a written license, or if the technologies described in this documentation are not covered by the Open Specifications Promise or Community Promise, as applicable, patent licenses are available by contacting .

License Programs. To see all of the protocols in scope under a specific license program and the associated patents, visit the Patent Map.

Trademarks. The names of companies and products contained in this documentation might be covered by trademarks or similar intellectual property rights. This notice does not grant any licenses under those rights. For a list of Microsoft trademarks, visit

Fictitious Names. The example companies, organizations, products, domain names, email addresses, logos, people, places, and events that are depicted in this documentation are fictitious. No association with any real company, organization, product, domain name, email address, logo, person, place, or event is intended or should be inferred.

Reservation of Rights. All other rights are reserved, and this notice does not grant any rights other than as specifically described above, whether by implication, estoppel, or otherwise.

Tools. The Open Specifications documentation does not require the use of Microsoft programming tools or programming environments in order for you to develop an implementation. If you have access to Microsoft programming tools and environments, you are free to take advantage of them. Certain Open Specifications documents are intended for use in conjunction with publicly available standards specifications and network programming art and, as such, assume that the reader either is familiar with the aforementioned material or has immediate access to it.

Support. For questions and support, please contact .

Revision Summary

Table of Contents

1Introduction

1.1Glossary

1.2References

1.2.1Normative References

1.2.2Informative References

1.3Overview

1.4Relationship to Other Protocols

1.5Prerequisites/Preconditions

1.6Applicability Statement

1.7Versioning and Capability Negotiation

1.8Vendor-Extensible Fields

1.9Standards Assignments

2Messages

2.1Transport

2.2Common Data Types

2.2.1HTTP Headers

2.2.1.1client-request-id

2.2.1.2return-client-request-id

2.2.1.3request-id

2.2.1.4api-version

2.2.1.5authorization

2.2.1.6accept

2.2.2URI Parameters

2.2.2.1api-version

2.2.3Complex Types

2.2.3.1ErrorDetails

2.3Directory Service Schema Elements

2.3.1ms-DS-Key-Credential-Link

3Protocol Details

3.1Key Provisioning Server Details

3.1.1Abstract Data Model

3.1.2Timers

3.1.3Initialization

3.1.4Higher-Layer Triggered Events

3.1.5Message Processing Events and Sequencing Rules

3.1.5.1Key

3.1.5.1.1POST

3.1.5.1.1.1Request Body

3.1.5.1.1.2Response Body

3.1.5.1.1.3Processing Details

3.1.6Timer Events

3.1.7Other Local Events

4Protocol Examples

4.1Provision a Key

5Security

5.1Security Considerations for Implementers

5.2Index of Security Parameters

6Appendix A: Full JSON Schema

7Appendix B: Product Behavior

8Change Tracking

9Index

1Introduction

The Key Provisioning Protocol provides a mechanism for registering a set of cryptographic keys on a user and device pair.

Sections 1.5, 1.8, 1.9, 2, and 3 of this specification are normative. All other sections and examples in this specification are informative.

1.1Glossary

This document uses the following terms:

access control list (ACL): A list of access control entries (ACEs) that collectively describe the security rules for authorizing access to some resource; for example, an object or set of objects.

Active Directory: A general-purpose network directory service. Active Directory also refers to the Windows implementation of a directory service. Active Directory stores information about a variety of objects in the network. Importantly, user accounts, computer accounts, groups, and all related credential information used by the Windows implementation of Kerberos are stored in Active Directory. Active Directory is either deployed as Active Directory Domain Services (AD DS) or Active Directory Lightweight Directory Services (AD LDS). [MS-ADTS] describes both forms. For more information, see [MS-AUTHSOD] section 1.1.1.5.2, Lightweight Directory Access Protocol (LDAP) versions 2 and 3, Kerberos, and DNS.

application programming interface (API): A set of routines used by an application program to direct the performance of procedures used by the computer's operating system. Also called application program interface.

Augmented Backus-Naur Form (ABNF): A modified version of Backus-Naur Form (BNF), commonly used by Internet specifications. ABNF notation balances compactness and simplicity with reasonable representational power. ABNF differs from standard BNF in its definitions and uses of naming rules, repetition, alternatives, order-independence, and value ranges. For more information, see [RFC5234].

base64 encoding: A binary-to-text encoding scheme whereby an arbitrary sequence of bytes is converted to a sequence of printable ASCII characters, as described in [RFC4648].

directory: The database that stores information about objects such as users, groups, computers, printers, and the directory service that makes this information available to users and applications.

distinguished name (DN): A name that uniquely identifies an object by using the relative distinguished name (RDN) for the object, and the names of container objects and domains that contain the object. The distinguished name (DN) identifies the object and its location in a tree.

globally unique identifier (GUID): A term used interchangeably with universally unique identifier (UUID) in Microsoft protocol technical documents (TDs). Interchanging the usage of these terms does not imply or require a specific algorithm or mechanism to generate the value. Specifically, the use of this term does not imply or require that the algorithms described in [RFC4122] or [C706] must be used for generating the GUID. See also universally unique identifier (UUID).

JavaScript Object Notation (JSON): A text-based, data interchange format that is used to transmit structured data, typically in Asynchronous JavaScript + XML (AJAX) web applications, as described in [RFC7159]. The JSON format is based on the structure of ECMAScript (Jscript, JavaScript) objects.

JSON Web Token (JWT): A type of token that includes a set of claims encoded as a JSON object. For more information, see [IETFDRAFT-JWT].

key: In cryptography, a generic term used to refer to cryptographic data that is used to initialize a cryptographic algorithm. Keys are also sometimes referred to as keying material.

object: A set of attributes, each with its associated values. For more information on objects, see [MS-ADTS] section 1 or [MS-DRSR] section 1.

Representational State Transfer (REST): A class of web services that is used to transfer domain-specific data by using HTTP, without additional messaging layers or session tracking, and returns textual data, such as XML.

Transport Layer Security (TLS): A security protocol that supports confidentiality and integrity of messages in client and server applications communicating over open networks. TLS supports server and, optionally, client authentication by using X.509 certificates (as specified in [X509]). TLS is standardized in the IETF TLS working group.

MAY, SHOULD, MUST, SHOULD NOT, MUST NOT: These terms (in all caps) are used as defined in [RFC2119]. All statements of optional behavior use either MAY, SHOULD, or SHOULD NOT.

1.2References

Links to a document in the Microsoft Open Specifications library point to the correct section in the most recently published version of the referenced document. However, because individual documents in the library are not updated at the same time, the section numbers in the documents may not match. You can confirm the correct section numbering by checking the Errata.

1.2.1Normative References

We conduct frequent surveys of the normative references to assure their continued availability. If you have any issue with finding a normative reference, please contact . We will assist you in finding the relevant information.

[ISO8601] ISO, "Data elements and interchange formats - Information interchange - Representation of dates and times", ISO 8601:2004, December 2004,

Note There is a charge to download the specification.

[MS-ADA2] Microsoft Corporation, "Active Directory Schema Attributes M".

[MS-ADA3] Microsoft Corporation, "Active Directory Schema Attributes N-Z".

[MS-ADSC] Microsoft Corporation, "Active Directory Schema Classes".

[MS-ADTS] Microsoft Corporation, "Active Directory Technical Specification".

[MS-DTYP] Microsoft Corporation, "Windows Data Types".

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997,

[RFC2616] Fielding, R., Gettys, J., Mogul, J., et al., "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999,

[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000,

[RFC4122] Leach, P., Mealling, M., and Salz, R., "A Universally Unique Identifier (UUID) URN Namespace", RFC 4122, July 2005,

[RFC4346] Dierks, T., and Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.1", RFC 4346, April 2006,

[RFC4514] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names", RFC 4514, June 2006,

1.2.2Informative References

None.

1.3Overview

The Key Provisioning Protocol provides for registration of cryptographic keys on a user and device pair.

The Key Provisioning Protocol provides a single REST-based endpoint that returns JavaScript Object Notation (JSON)–formatted data in the response message.

This document defines and uses the following terms:

client: The entity that creates and sends the key provisioning request to the key provisioning server using the Key Provisioning Protocol.

key provisioning server: The server that implements the REST Web service that accepts and responds to key provisioning requests using the Key Provisioning Protocol.

1.4Relationship to Other Protocols

The following figure illustrates the relationship of this protocol to other protocols.

Figure 1: Protocols related to the Key Provisioning Protocol

1.5Prerequisites/Preconditions

The Key Provisioning Protocol registers keys with User objects ([MS-ADSC] section 2.268) represented in a directory server. A server implementation of the Key Provisioning Protocol, or key provisioning server, requires a directory server.

This protocol requires that the following state changes be made to Active Directory.

1. Create an instance of the ms-DS-Device-Registration-Service-Container class ([MS-ADSC] section 2.138) in the directory.
2. Set the following directory access control list (ACL) entries:
3. Grant the key provisioning server read access to the ms-DS-Device-Registration-Service object ([MS-ADSC] section 2.137).
4. Grant the key provisioning server read/write access to ms-DS-Device objects ([MS-ADSC] section 2.135).
5. Grant the key provisioning server read/write access to the ms-DS-Key-Credential-Link attribute ([MS-ADA2] section 2.347) on User objects.

1.6Applicability Statement

The Key Provisioning Protocol is applicable only for requests for key provisioning.

1.7Versioning and Capability Negotiation

None.

1.8Vendor-Extensible Fields

None.

1.9Standards Assignments

None.

2Messages

2.1Transport

The Key Provisioning Protocol consists of a single RESTful Web service.

HTTPS [RFC2818] over TCP/IP [RFC2616]

The protocol operates on the following URI endpoint.

All client messages to the key provisioning server MUST use Hypertext Transfer Protocol over Secure Sockets Layer (HTTPS) and provide server authentication, which MUST use Transport Layer Security (TLS) 1.1 [RFC4346] or greater.

2.2Common Data Types

2.2.1HTTP Headers

This protocol accesses the HTTP headers listed in the following table.

2.2.1.1client-request-id

The client-request-id HTTP header is optional and can appear in either the request or the response. This header is used to provide the key provisioning server with a unique request identifier, which is then used by the server to log error messages that were encountered while processing the lookup request. If present, the value of the client-request-id header MUST be a globally unique identifier (GUID) in standard string representation (see [RFC4122] section 3 for the format).

The format of the client-request-id header, in Augmented Backus-Naur Form (ABNF), is as follows.

String = *(%x20-7E)

client-request-id = String

2.2.1.2return-client-request-id

The return-client-request-id HTTP header is optional. This header is sent in the request and is used by the key provisioning server to determine whether to return the client-specified client-request-id in the server response. If present, the value of the return-client-request-id header MUST be "true".

The format of the return-client-request-id header, in ABNF, is as follows.

return-client-request-id = "true"

2.2.1.3request-id

The request-id HTTP header is a server-generated GUID in standard string representation (see [RFC4122] section 3 for the format). The key provisioning server SHOULD include this header in all server responses.

The format of the request-id header, in ABNF, is as follows.

String = *(%x20-7E)

request-id = String

2.2.1.4api-version

The api-version header is an integer that indicates the API version that is expected by the client. Either this header or the api-version query parameter (section 2.2.2.1) MUST be included in all client requests.

Note The api-version header and the api-version query parameter defined in section 2.2.2.1 are mutually exclusive. The client is expected to specify an API version by using either one of these mechanisms, but not both.

The format of the api-version header, in ABNF, is as follows.

String = *(%x20-7E)

api-version = String

2.2.1.5authorization

The authorization HTTP header is required in the request and contains a JSON Web Token (JWT) that the client passes to the key provisioning server. The JWT contains claims that the key provisioning server uses to authorize access to the relevant User object on the directory server.

The format of the authorization header, in ABNF, is as follows.

String = *(%x20-7E)

authorization =String

2.2.1.6accept

The accept HTTP header is required in the request and specifies which media types ([RFC2616] section 3.7) are acceptable for the response. "application/json" is the only acceptable media type for the Key Provisioning Protocol.

The format of the accept header, in ABNF, is as follows.

accept = "application/json"

2.2.2URI Parameters

The following table summarizes the set of common URI parameters defined by this protocol.

2.2.2.1api-version

The api-version parameter is an integer that indicates the API version that is expected by the client. Either this header or the api-version HTTP header (section 2.2.1.4) MUST be included in all client requests.

The format of the api-version parameter, in ABNF, is as follows.

String = *(%x20-7E)

api-version = String

2.2.3Complex Types

The following table summarizes the set of complex type definitions included in this specification.

2.2.3.1ErrorDetails

This object contains a collection of human-readable details that describe an error encountered by the key provisioning server. It can be used by the client role of the Key Provisioning Protocol for logging purposes or for providing information to an administrator.

{

"description": "error details",

"type": "object",

"properties": {

"code": { "type": "string", "optional": false },

"message": { "type": "string", "optional": false },

"response": { "type": "string", "optional": false },

"target": { "type": "string", "optional": false },

"clientrequestid": { "type": "string", "optional": true },

"time": { "type": "string", "optional": false },

"innererror": {

"description": "error details",

"type": "object",

"optional": true,

"properties": {

"trace": { "type": "string", "optional": false },

"context": { "type": "string", "optional": false },

}

}

}

}

code: A server-generated string representing a machine readable error.

message: A human-readable string explaining the error.

response: The client action to be taken when this error is received. This value MUST be set to "ERROR_FAIL".

target: A string representing the resource being acted upon.

clientrequestid: A GUID in standard string representation (see [RFC4122] section 3 for the format).

time: The [ISO8601]-formatted time that is assigned by the key provisioning server.

trace: MUST be "null".

context: MUST be "null".

2.3Directory Service Schema Elements

This protocol makes use of the Directory Service schema classes and attributes that are listed in the following table.

For the syntax of <Class> or <Class<Attribute> pairs, refer to [MS-ADA2], [MS-ADA3], and [MS-ADSC].

2.3.1ms-DS-Key-Credential-Link

The ms-DS-Key-Credential-Link attribute is a multi-valued DN-Binary attribute (see [MS-ADTS] section 3.1.1.2.2.2, the Object(DN-Binary) syntax). Each value is formatted as follows:

B:[keylen]:[key]:[objectDN]

Where [keylen] is the length of [key]. [key] is a KEYCREDENTIALLINK_BLOB ([MS-ADTS] section 2.2.20.2). [objectDN] is an [RFC4514]-formatted distinguished name for the directory object that contains the ms-DS-Key-Credential-Link attribute.