[MS-KPS]:
Key Protection Service 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
Date / Revision History / Revision Class / Comments3/16/2017 / 1.0 / New / Released new document.
6/1/2017 / 2.0 / Major / Significantly changed the technical content.
9/15/2017 / 3.0 / Major / Significantly changed the technical content.
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 Methods
2.2.1.1RollTransportKey
2.2.1.2GetMetaData
2.2.2Complex Types
2.2.2.1RollTransportKeyRequest
2.2.2.2RollTransportKeyResponse
2.2.2.3Protector
2.2.2.4Wrapping
2.2.2.5Error
2.2.2.6WrappingCollection
2.2.2.7TransportKeySignature
2.2.2.8GuardianSignature
2.2.2.9KeyDerivationMethod
2.2.2.10Signature
2.2.2.11EncryptedData
2.2.2.12SigningCertificateSignature
2.2.2.13EncryptionCertificateSignature
2.2.2.14TransportKey
2.2.2.15Parameters
2.2.3Simple Types
2.2.3.1IngressProtector
2.2.3.2HealthCertificate
2.2.3.3TransferKeyEncryptionAlgorithm
2.2.3.4WrappingKeyEncryptionAlgorithm
2.2.3.5TransportKeyEncryptionAlgorithm
2.2.3.6EgressProtector
2.2.3.7EncryptedTransferKey
2.2.3.8EncryptedWrappingKey
2.2.3.9EncryptedTransportKeys
2.2.3.10Version
2.2.3.11Certificate
2.2.3.12Algorithm
3Protocol Details
3.1Server 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.1Service APIs
3.1.5.1.1RollTransportKey
3.1.5.1.1.1Request Body
3.1.5.1.1.2Response Body
3.1.5.1.1.3Processing Details
3.1.5.1.2GetMetaData
3.1.5.1.2.1Request Body
3.1.5.1.2.2Response Body
3.1.5.1.2.3Processing Details
3.1.6Timer Events
3.1.7Other Local Events
3.2Client Details
3.2.1Abstract Data Model
3.2.2Timers
3.2.3Initialization
3.2.4Higher-Layer Triggered Events
3.2.4.1Application Requests RollTransportKey
3.2.4.2Application Requests GetMetaData
3.2.5Message Processing Events and Sequencing Rules
3.2.5.1RollTransportKey
3.2.5.2GetMetaData
3.2.6Timer Events
3.2.7Other Local Events
4Protocol Examples
5Security
5.1Security Considerations for Implementers
5.2Index of Security Parameters
6Appendix A: Full XML Schema
6.1Protector Schema
6.2RollTransportKey Request Schema
6.3RollTransportKey Response Schema
6.4MetaData Resposne Schema
6.5Crypto Schema
7Appendix B: Product Behavior
8Change Tracking
9Index
1Introduction
This document specifies the Key Protection Service (KPS) Protocol,a component of the Host Guradian service, which provides security assurance for shielded virtual machines.
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:
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].
binary large object (BLOB): A discrete packet of data that is stored in a database and is treated as a sequence of uninterpreted bytes.
HTTP 1.1: Hypertext Transfer Protocol -- HTTP/1.1 [RFC2616]
HTTP method: In an HTTP message, a token that specifies the method to be performed on the resource that is identified by the Request-URI, as described in [RFC2616].
Hypertext Transfer Protocol (HTTP): An application-level protocol for distributed, collaborative, hypermedia information systems (text, graphic images, sound, video, and other multimedia files) on the World Wide Web.
UTF-8: A byte-oriented standard for encoding Unicode characters, defined in the Unicode standard. Unless specified otherwise, this term refers to the UTF-8 encoding form specified in [UNICODE5.0.0/2007] section 3.9.
X.509: An ITU-T standard for public key infrastructure subsequently adapted by the IETF, as specified in [RFC3280].
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.
[MS-HGSA] Microsoft Corporation, "Host Guardian Service: Attestation Protocol".
[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,
1.2.2Informative References
None.
1.3Overview
Host Guardian Service is a server role that provides the security services Attestation Service and Key Protection Service. Together these two services help provide security assurance for Shielded VMs by ensuring that Shielded VMs can be run only on known and trusted fabric hosts that have a legitimate configuration. This specification defines Key Protection Service. The Attestation Service is defined in the [MS-HGSA] specification.
1.4Relationship to Other Protocols
For its attestation service, Key Protection Service uses the Host Guardian Service: Attestation Protocol as specified in [MS-HGSA].
1.5Prerequisites/Preconditions
None.
1.6Applicability Statement
The Host Guardian Service includes Attestation Service and Key Protection Service as critical components that secure virtual machines in a cloud-based environment.
1.7Versioning and Capability Negotiation
None.
1.8Vendor-Extensible Fields
There are no vendor-extensible fields for the Key Protection Service Protocol.
1.9Standards Assignments
None.
2Messages
2.1Transport
The Key Protection Service Protocol uses HTTP or secure HTTP 1.1 as transport, as specified in [RFC2616] and [RFC2818].
2.2Common Data Types
2.2.1HTTP Methods
This protocol defines the following common HTTP methods in addition to the existing set of standard HTTP methods.
Method / Section / DescriptionRollTransportKey / 2.2.1.1 / Extracts the TransportKey from the IngressProtector, generates a new transport key, creates the EgressProtector and returns both transport keys to the caller.
GetMetaData / 2.2.1.2 / Returns the metadata content containing the guardian information to the client.
2.2.1.1RollTransportKey
The RollTransportKey method validates that the IngressProtector defined in section 2.2.3.1 is well-formed, performs Key Protection Service (KPS) checks by using an encryption algorithm in an implementation-specific manner, and generates the EgressProtector.
This method is invoked from the following URI:
2.2.1.2GetMetaData
The GetMetaData method provides the list of KPS-supported certificates, which are used in validating that the KeyProtector was properly signed by KPS or to create a new protector and encrypt the transport keys.
This method is invoked from the following URI with HTTP GET request:
2.2.2Complex Types
The following table summarizes the set of common complex type definitions that are included in this specification and use the XML format.
Complex type / Section / DescriptionRollTransportKeyRequest / 2.2.2.1 / Requests the BLOB from the client with the protector descriptor and Health Certificate received after Attestation Services.
RollTransportKeyResponse / 2.2.2.2 / Response to the RollTransportKeyRequest.
Protector / 2.2.2.3 / Represents a protector.
Wrapping / 2.2.2.4 / Consists of certificates of type base64-encoded strings and a transport key.
Error / 2.2.2.5 / Possible error codes received from methods processed by the KPS RollTransportKeyResponse and GetMetaData.
WrappingCollection / 2.2.2.6 / Defines the list of Wrapping elementsof the transport keys received from the client.
TransportKeySignature / 2.2.2.7 / Denotes the digital signature of the TransportKey.
GuardianSignature / 2.2.2.8 / Denotes the KPS signing certificate specified by WrappingId over the entire Wrappings element.
KeyDerivationMethod / 2.2.2.9 / Denotes the set of cryptographic parameters and algorithms needed to perform the KPS.
Signature / 2.2.2.10 / Denotes a digital signature that provides details about the entity that is used for providing Key Protection Services.
EncryptedData / 2.2.2.11 / Denotes the payload of data used by KeyProtector to perform the Key Protection Services.
SigningCertificateSignature / 2.2.2.12 / Denotes the signing certificate signature of the specified parent wrapping ID.
EncryptionCertificateSignature / 2.2.2.13 / Denotes the signature of the encryption certificate.
TransportKey / 2.2.2.14 / A base64-encoded string of type UTF-8 format, which contains the wrapping key's transfer key encrypted by the health certificate.
Parameters / 2.2.2.15 / Possible namespaces and process contents used to perform Key Protection Services.
2.2.2.1RollTransportKeyRequest
The RollTransportKeyRequest structure is sent by the client to request the encrypted transport keys and to perform Key Protection.
<?xml version="1.0" encoding="utf-8"?>
<xs:schema targetNamespace="
elementFormDefault="qualified"
xmlns="
xmlns:xs="
<xs:element name="RollTransportKeyRequest" type="RollTransportKeyRequest_T"/>
<xs:complexType name="RollTransportKeyRequest_T">
<xs:annotation>
<xs:documentation>RollTransportKey request.</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="IngressProtector">
<xs:annotation>
<xs:documentation>The ingress protector.</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:base64Binary">
<xs:minLength value="1"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="HealthCertificate">
<xs:annotation>
<xs:documentation>The health certificate.</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:base64Binary">
<xs:minLength value="1"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="TransferKeyEncryptionAlgorithm">
<xs:annotation>
<xs:documentation>The algorithm to be used to encrypt the wrapping key's transfer key.</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:anyURI">
<xs:minLength value="1"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="WrappingKeyEncryptionAlgorithm">
<xs:annotation>
<xs:documentation>The algorithm to be used to encrypt the transport keys' wrapping key.</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:anyURI">
<xs:minLength value="1"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="TransportKeysEncryptionAlgorithm">
<xs:annotation>
<xs:documentation>The algorithm to be used to encrypt the transport keys.</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:anyURI">
<xs:minLength value="1"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:schema>
IngressProtector: A base64-encoded string of type UTF-8 format that contains the entire ingress protector as serialized to a file.
HealthCertificate: A base64-encoded binary string of type X.509 format.
TransferKeyEncryptionAlgorithm: The algorithm to be used to encrypt the wrapping key’s transfer key.
WrappingKeyEncryptionAlgorithm: The algorithm to be used to encrypt the transport keys’ wrapping key.
TransportKeyEncryptionAlgorithm: The algorithm to be used to encrypt the transport keys.
2.2.2.2RollTransportKeyResponse
The RollTransportKeyResponse structure is sent by the KPS with encrypted keys, which is useful in allowing the guarded host to run on a VM.
<?xml version="1.0" encoding="utf-8"?>
<xs:schema targetNamespace="
elementFormDefault="qualified"
xmlns="
xmlns:xs="
<xs:element name="RollTransportKeyResponse" type="RollTransportKeyResponse_T"/>
<xs:complexType name="RollTransportKeyResponse_T">
<xs:annotation>
<xs:documentation>RollTransportKey response.</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="EgressProtector">
<xs:annotation>
<xs:documentation>The egress protector containing the new transport key.</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:base64Binary">
<xs:minLength value="1"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="EncryptedTransferKey">
<xs:annotation>
<xs:documentation>The wrapping key's transfer key encrypted by the health certificate.</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:base64Binary">
<xs:minLength value="1"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="EncryptedWrappingKey">
<xs:annotation>
<xs:documentation>The transport keys' wrapping key encrypted by the transfer key.</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:base64Binary">
<xs:minLength value="1"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="EncryptedTransportKeys">
<xs:annotation>
<xs:documentation>The ingress and egress transport keys encrypted by the transport keys' wrapping key.</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:base64Binary">
<xs:minLength value="1"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:schema>
EgressProtector: A base64-encoded string of type UTF-8 format that contains the entire egress protector as serialized to a file.
EncryptedTransferKey: A base64-encoded string of type UTF-8 format that contains the wrapping key's transfer key, which is encrypted by the health certificate as defined in section 2.2.3.7.
EncryptedWrappingKey: A base64-encoded string of type UTF-8 format that contains the transport keys’ wrapping key, which is encrypted by the transfer key as defined section 2.2.3.8.
EncryptedTransportKeys: A base64-encoded string of type UTF-8 format contains the ingress and egress transport keys, which are encrypted by the transport keys' wrapping key as defined in section 2.2.3.9.
2.2.2.3Protector
The Protector structure is the cryptographically authenticated collection of different wrappings of the transport key, signed by the Guardian.
<xs:element name="Protector" type="Protector_T" />
<xs:complexType name="Protector_T">
<xs:annotation>
<xs:documentation>A protector contains a list of wrappings of the transport key.</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="Wrappings" type="WrappingCollection_T" /
<xs:element name="TransportKeySignature" type="TransportKeySignature_T" />
<xs:element name="GuardianSignature" type="GuardianSignature_T" />
</xs:sequence>
</xs:complexType>
Wrappings: A list of wrappings of the transport key to be included in the new protector of the type defined in section 2.2.2.4.
TransportKeySignature: A UTF-8 converted signature computed by using a key derived from the actual transport key over the entire Wrappings element of the type defined in section 2.2.2.7.
GuardianSignature: A UTF-8 converted signature computed by using the signing certificate specified by WrappingId over the entire Wrappings element as defined in section 2.2.2.8.
2.2.2.4Wrapping
The Wrapping structure consists of certificates of type base64-encoded strings and the TransportKey. This wrapping involves the authenticated encryption of concatenation of the ingress and egress keys.
<xs:element name="Wrapping" type="Wrapping_T" />
<xs:complexType name="Wrapping_T">
<xs:sequence>
<xs:element name="Id" type="xs:unsignedInt" />
<xs:element name="SigningCertificate" type="Certificate_T" />
<xs:element name="SigningCertificateSignature" type="SigningCertificateSignature_T" />
<xs:element name="EncryptionCertificate" type="Certificate_T" />
<xs:element name="EncryptionCertificateSignature" type="EncryptionCertificateSignature_T" />
<xs:element name="TransportKey" type="TransportKey_T" />
</xs:sequence>
</xs:complexType>
Id: A 32-bit unsigned integer that contains the wrapping ID.
SigningCertificate: Signing certificate of type Certificate_T as defined in section 2.2.3.11.
SigningCertificateSignature: Signing certificate signature as defined in section 2.2.2.12.
EncryptionCertificate: Encryption certificate of type Certificate_T as defined in section 2.2.2.13.
EncryptionCertificateSignature: Encryption certificate signature as defined in section 2.2.2.13.
TransportKey: Encrypted transport key as defined in section 2.2.2.14.
2.2.2.5Error
The Error structure denotes the possible error codes that are received from methods processed by the Key Protection Service’s RollTransportKey and GetMetaData methods.
<xs:element name="Error" type="Error_T" />
<xs:complexType name="Error_T">
<xs:annotation>
<xs:documentation>Error response.</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="Code" type="xs:string">
<xs:annotation>
<xs:documentation>Error code.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="Message" type="xs:string">
<xs:annotation>
<xs:documentation>Error message.</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
Code: A string that represents the error response received from RollTransportKey or GetMetaData.
Message: A string that represents the error message of the error code received.
2.2.2.6WrappingCollection
The WrappingCollection structure defines the list of wrappings of the transport keysreceived from the client.
<xs:element name="Wrappings" type="WrappingCollection_T" />
<xs:complexType name="WrappingCollection_T">
<xs:sequence>
<xs:element name="Wrapping" type="Wrapping_T" minOccurs="1" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
Wrapping: Wrapping structure as defined in section 2.2.2.4
2.2.2.7TransportKeySignature
The TransportKeySignature structure denotes the digital signature of the transport key.
<xs:element name="TransportKeySignature" type="TransportKeySignature_T" />
<xs:complexType name="TransportKeySignature_T">
<xs:annotation>
<xs:documentation>The transport key signature is computed using a key derived from the actual transport key over the entire Wrappings element after exclusive xml canonicalization ( and conversion to UTF-8.</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="KeyDerivationMethod" type="KeyDerivationMethod_T" />
<xs:element name="Signature" type="Signature_T" />
</xs:sequence>
</xs:complexType>
KeyDerivationMethod: Set of cryptographic parameters and algorithms needed to perform Key Protection Services as defined in section 2.2.2.9.
Signature: Provides details about the entity that is used for providing Key Protection Services as defined in section 2.2.2.10.
2.2.2.8GuardianSignature
The GuardianSignature structure denotes the digital signature using the KPS signing certificate specified by WrappingId over the entire Wrappings element.
<xs:element name="GuardianSignature" type="GuardianSignature_T" />
<xs:complexType name="GuardianSignature_T">
<xs:annotation>
<xs:documentation>The guardian signature is computed using the signing certificate specified by WrappingId over the entire Wrappings element after exclusive xml canonicalization ( and conversion to UTF-8.</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="Signature" type="Signature_T" />
</xs:sequence>
<xs:attribute name="WrappingId" type="xs:unsignedInt" use="required" />
</xs:complexType>
Signature: The guardian signature is computed by using the KPS signing certificate’s private key of the type defined in section 2.2.2.10.
WrappingId: A 32-bit unsigned integer that contains a unique wrapping ID.
2.2.2.9KeyDerivationMethod
The KeyDerivationMethod structure denotes the set of cryptographic parameters and algorithms needed to perform the KPS.
<xs:element name="KeyDerivationMethod" type="KeyDerivationMethod_T" />
<xs:complexType name="KeyDerivationMethod_T">
<xs:sequence>
<xs:element name="Parameters" type="CryptoParameters_T" minOccurs="0" />
</xs:sequence>
<xs:attribute name="Algorithm" type="CryptoAlgorithm_T" use="required" />
</xs:complexType>
Parameters: Set of cryptographic parameters used to perform Key Protection Services of the type defined in section 2.2.2.15
Algorithm: Cryptographic algorithm used to perform Key Protection Services of the type defined in section 2.2.3.12
2.2.2.10Signature
The Signature structure denotes a digital signature that provides the details about the entity that is used for providing Key Protection Services.
<xs:element name="Signature" type="Signature_T" />
<xs:complexType name="Signature_T">
<xs:sequence>
<xs:element name="Parameters" type="CryptoParameters_T" minOccurs="0" />