Introduction - Microsoft



[MS-KPS]: Key Protection Service ProtocolIntellectual Property Rights Notice for Open Specifications DocumentationTechnical 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 iplg@. 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 trademarks. 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 dochelp@. Revision SummaryDateRevision HistoryRevision ClassComments3/16/20171.0NewReleased new document.6/1/20172.0MajorSignificantly changed the technical content.9/15/20173.0MajorSignificantly changed the technical content.12/1/20173.0NoneNo changes to the meaning, language, or formatting of the technical content.3/16/20184.0MajorSignificantly changed the technical content.9/12/20185.0MajorSignificantly changed the technical content.5/30/20195.0NoneNo changes to the meaning, language, or formatting of the technical content.Table of ContentsTOC \o "1-9" \h \z1Introduction PAGEREF _Toc9550638 \h 51.1Glossary PAGEREF _Toc9550639 \h 51.2References PAGEREF _Toc9550640 \h 51.2.1Normative References PAGEREF _Toc9550641 \h 61.2.2Informative References PAGEREF _Toc9550642 \h 61.3Overview PAGEREF _Toc9550643 \h 61.4Relationship to Other Protocols PAGEREF _Toc9550644 \h 61.5Prerequisites/Preconditions PAGEREF _Toc9550645 \h 61.6Applicability Statement PAGEREF _Toc9550646 \h 61.7Versioning and Capability Negotiation PAGEREF _Toc9550647 \h 61.8Vendor-Extensible Fields PAGEREF _Toc9550648 \h 61.9Standards Assignments PAGEREF _Toc9550649 \h 62Messages PAGEREF _Toc9550650 \h 72.1Transport PAGEREF _Toc9550651 \h 72.2Common Data Types PAGEREF _Toc9550652 \h 72.2.1HTTP Methods PAGEREF _Toc9550653 \h 72.2.1.1RollTransportKey PAGEREF _Toc9550654 \h 72.2.1.2GetMetaData PAGEREF _Toc9550655 \h 72.2.2Complex Types PAGEREF _Toc9550656 \h 82.2.2.1RollTransportKeyRequest PAGEREF _Toc9550657 \h 92.2.2.2RollTransportKeyResponse PAGEREF _Toc9550658 \h 102.2.2.3Protector PAGEREF _Toc9550659 \h 112.2.2.4Wrapping PAGEREF _Toc9550660 \h 122.2.2.5Error PAGEREF _Toc9550661 \h 122.2.2.6WrappingCollection PAGEREF _Toc9550662 \h 132.2.2.7TransportKeySignature PAGEREF _Toc9550663 \h 132.2.2.8GuardianSignature PAGEREF _Toc9550664 \h 142.2.2.9KeyDerivationMethod PAGEREF _Toc9550665 \h 142.2.2.10Signature PAGEREF _Toc9550666 \h 142.2.2.11EncryptedData PAGEREF _Toc9550667 \h 152.2.2.12SigningCertificateSignature PAGEREF _Toc9550668 \h 152.2.2.13EncryptionCertificateSignature PAGEREF _Toc9550669 \h 162.2.2.14TransportKey PAGEREF _Toc9550670 \h 162.2.2.15Parameters PAGEREF _Toc9550671 \h 162.2.3Simple Types PAGEREF _Toc9550672 \h 162.2.3.1IngressProtector PAGEREF _Toc9550673 \h 172.2.3.2HealthCertificate PAGEREF _Toc9550674 \h 182.2.3.3TransferKeyEncryptionAlgorithm PAGEREF _Toc9550675 \h 182.2.3.4WrappingKeyEncryptionAlgorithm PAGEREF _Toc9550676 \h 182.2.3.5TransportKeyEncryptionAlgorithm PAGEREF _Toc9550677 \h 182.2.3.6EgressProtector PAGEREF _Toc9550678 \h 192.2.3.7EncryptedTransferKey PAGEREF _Toc9550679 \h 192.2.3.8EncryptedWrappingKey PAGEREF _Toc9550680 \h 192.2.3.9EncryptedTransportKeys PAGEREF _Toc9550681 \h 202.2.3.10Version PAGEREF _Toc9550682 \h 202.2.3.10.1Payload_V1 structure PAGEREF _Toc9550683 \h 202.2.3.10.2Payload_V2 structure PAGEREF _Toc9550684 \h 212.2.3.10.2.1Policy Data structure PAGEREF _Toc9550685 \h 222.2.3.11Certificate PAGEREF _Toc9550686 \h 222.2.3.12Algorithm PAGEREF _Toc9550687 \h 223Protocol Details PAGEREF _Toc9550688 \h 243.1Server Details PAGEREF _Toc9550689 \h 243.1.1Abstract Data Model PAGEREF _Toc9550690 \h 243.1.2Timers PAGEREF _Toc9550691 \h 243.1.3Initialization PAGEREF _Toc9550692 \h 243.1.4Higher-Layer Triggered Events PAGEREF _Toc9550693 \h 253.1.5Message Processing Events and Sequencing Rules PAGEREF _Toc9550694 \h 253.1.5.1Service APIs PAGEREF _Toc9550695 \h 253.1.5.1.1RollTransportKey PAGEREF _Toc9550696 \h 253.1.5.1.1.1Request Body PAGEREF _Toc9550697 \h 253.1.5.1.1.2Response Body PAGEREF _Toc9550698 \h 263.1.5.1.1.3Processing Details PAGEREF _Toc9550699 \h 263.1.5.1.2GetMetaData PAGEREF _Toc9550700 \h 273.1.5.1.2.1Request Body PAGEREF _Toc9550701 \h 283.1.5.1.2.2Response Body PAGEREF _Toc9550702 \h 283.1.5.1.2.3Processing Details PAGEREF _Toc9550703 \h 283.1.6Timer Events PAGEREF _Toc9550704 \h 293.1.7Other Local Events PAGEREF _Toc9550705 \h 293.2Client Details PAGEREF _Toc9550706 \h 293.2.1Abstract Data Model PAGEREF _Toc9550707 \h 293.2.2Timers PAGEREF _Toc9550708 \h 293.2.3Initialization PAGEREF _Toc9550709 \h 293.2.4Higher-Layer Triggered Events PAGEREF _Toc9550710 \h 293.2.4.1Application Requests RollTransportKey PAGEREF _Toc9550711 \h 293.2.4.2Application Requests GetMetaData PAGEREF _Toc9550712 \h 293.2.5Message Processing Events and Sequencing Rules PAGEREF _Toc9550713 \h 303.2.5.1RollTransportKey PAGEREF _Toc9550714 \h 303.2.5.2GetMetaData PAGEREF _Toc9550715 \h 303.2.6Timer Events PAGEREF _Toc9550716 \h 303.2.7Other Local Events PAGEREF _Toc9550717 \h 304Protocol Examples PAGEREF _Toc9550718 \h 315Security PAGEREF _Toc9550719 \h 325.1Security Considerations for Implementers PAGEREF _Toc9550720 \h 325.2Index of Security Parameters PAGEREF _Toc9550721 \h 326Appendix A: Full XML Schema PAGEREF _Toc9550722 \h 336.1Protector Schema PAGEREF _Toc9550723 \h 336.2RollTransportKey Request Schema PAGEREF _Toc9550724 \h 346.3RollTransportKey Response Schema PAGEREF _Toc9550725 \h 346.4MetaData Resposne Schema PAGEREF _Toc9550726 \h 346.5Crypto Schema PAGEREF _Toc9550727 \h 357Appendix B: Product Behavior PAGEREF _Toc9550728 \h 378Change Tracking PAGEREF _Toc9550729 \h 389Index PAGEREF _Toc9550730 \h 39Introduction XE "Introduction" This document specifies the Key Protection Service (KPS) Protocol, a component of the Host Guardian 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.Glossary XE "Glossary" 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.guardian: An entity that is authorized to receive and decrypt a transport key created by an owner.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.key protector: A data structure used to secure transport keys by cryptographic wrapping for distribution to authorized guardians and/or owners. Every key protector has at least one owner and zero or more guardians.owner: An entity that creates and signs a key protector. An owner can be expressed in a key protector as a self-signed wrapping.transport key: An encryption key used to protect data. Transport keys are secured and distributed by key protectors.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.ReferencesLinks 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. Normative References XE "References:normative" XE "Normative 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 dochelp@. 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, References XE "References:informative" XE "Informative references" None.Overview XE "Overview (synopsis)" 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.Relationship to Other Protocols XE "Relationship to other protocols" For its attestation service, Key Protection Service uses the Host Guardian Service: Attestation Protocol as specified in [MS-HGSA].Prerequisites/Preconditions XE "Prerequisites" XE "Preconditions" None.Applicability Statement XE "Applicability" The Host Guardian Service includes Attestation Service and Key Protection Service as critical components that secure virtual machines in a cloud-based environment.Versioning and Capability Negotiation XE "Versioning" XE "Capability negotiation" None.Vendor-Extensible Fields XE "Vendor-extensible fields" XE "Fields - vendor-extensible" There are no vendor-extensible fields for the Key Protection Service Protocol.Standards Assignments XE "Standards assignments" None.MessagesTransport XE "Messages:transport" XE "Transport" The Key Protection Service Protocol uses HTTP or secure HTTP 1.1 as transport, as specified in [RFC2616] and [RFC2818].Common Data TypesHTTP Methods XE "Messages:HTTP methods" XE "HTTP methods" This protocol defines the following common HTTP methods in addition to the existing set of standard HTTP methods. MethodSectionDescriptionRollTransportKey2.2.1.1Extracts the TransportKey from the IngressProtector, generates a new transport key, creates the EgressProtector and returns both transport keys to the caller.GetMetaData2.2.1.2Returns the metadata content containing the guardian information to the client.RollTransportKeyThe 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:{version}/rolltransportkey GetMetaDataThe 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: Complex Types XE "Messages:complex types" XE "Complex types" The following table summarizes the set of common complex type definitions that are included in this specification and use the XML format. Complex typeSectionDescriptionRollTransportKeyRequest2.2.2.1Contains the BLOB from the client with the protector descriptor and Health Certificate received after Attestation Services.RollTransportKeyResponse2.2.2.2Response to the RollTransportKeyRequest.Protector2.2.2.3Represents a protector.Wrapping2.2.2.4Consists of certificates of type base64-encoded strings and an encrypted transport key.Error2.2.2.5Possible error codes received from methods processed by the KPS, RollTransportKey, and GetMetaData.WrappingCollection2.2.2.6Defines the list of Wrapping elements of the transport key.TransportKeySignature2.2.2.7Denotes the signature computed using a key derived from the TransportKey over the entire Wrappings element.GuardianSignature2.2.2.8Denotes the signature computed using the KPS's signing certificate specified by WrappingId over the entire Wrappings element.KeyDerivationMethod2.2.2.9Contains the Algorithm and a set of cryptographic Parameters used to derive the key from the TransportKey.Signature2.2.2.10Contains the Algorithm, cryptographic Parameters and a signature value in base64-encoded format used to compute the signature.EncryptedData2.2.2.11Contains the Algorithm, cryptographic Parameters, and a cipher value in base64-encoded format used for encryption.SigningCertificateSignature2.2.2.12Denotes the signing certificate signature computed using the signing certificate of the parent wrapping over this wrapping’s signing certificate.EncryptionCertificateSignature2.2.2.13Denotes the signature computed using this wrapping's signing certificate over this wrapping's encryption certificate.TransportKey2.2.2.14A base64-encoded string of type UTF-8 format, which contains the transport key encrypted by the encryption certificate.Parameters2.2.2.15Possible namespaces and process contents used to perform Key Protection Services.RollTransportKeyRequestThe 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, as specified in section 2.2.3.1.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.RollTransportKeyResponseThe 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, as specified in section 2.2.3.6.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.ProtectorThe 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:attribute name="MaxOfflineUnwraps" type="xs:unsignedInt" default="0" /> </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.MaxOfflineUnwraps: A 32-bit unsigned integer when set to a non-zero value indicates that offline unwrapping of the protector is allowed. HYPERLINK \l "Appendix_A_1" \o "Product behavior note 1" \h <1>WrappingThe Wrapping structure consists of X.509 certificates of type base64-encoded strings and an encryption 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.3.11.EncryptionCertificateSignature: Encryption certificate signature as defined in section 2.2.2.13.TransportKey: Encrypted transport key as defined in section 2.2.2.14.ErrorThe 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.WrappingCollectionThe WrappingCollection structure defines the list of wrappings of the transport key.<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.4TransportKeySignatureThe 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. This is computed using the key derived from the TransportKey over the entire Wrappings element.GuardianSignatureThe 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.KeyDerivationMethodThe KeyDerivationMethod structure denotes the set of cryptographic parameters and algorithms used to derive the key from TransportKey.<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 in deriving the key from the TransportKey, of the type defined in section 2.2.2.15Algorithm: Cryptographic algorithm used to derive the key from the TransportKey, of the type defined in section 2.2.3.12SignatureThe Signature structure denotes a digital signature that provides the details about the elements used to compute the signature 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" /> <xs:element name="SignatureValue"> <xs:simpleType> <xs:restriction base="xs:base64Binary" /> </xs:simpleType> </xs:element> </xs:sequence> <xs:attribute name="Algorithm" type="CryptoAlgorithm_T" use="required" /> </xs:complexType>Parameters: Set of cryptographic parameters used in computing the signature, of the type defined in section 2.2.2.15.SignatureValue: A base64-encoded binary string that represents the value of the Signature.Algorithm: Cryptographic algorithm used in computing the signature, of the type defined in section 2.2.3.12.EncryptedDataThe EncryptedData structure contains the Algorithm, cryptographic Parameters and a cipher value in base64-encoded format used for encryption.<xs:element name="EncryptedData" type="EncryptedData_T" /> <xs:complexType name="EncryptedData_T"> <xs:sequence> <xs:element name="Parameters" type="CryptoParameters_T" minOccurs="0" /> <xs:element name="CipherValue"> <xs:simpleType> <xs:restriction base="xs:base64Binary" /> </xs:simpleType> </xs:element> </xs:sequence> <xs:attribute name="Algorithm" type="CryptoAlgorithm_T" use="required" /> </xs:complexType>Parameters: Set of cryptographic parameters used for encryption, of the type defined in section 2.2.2.15.CipherValue: A base64-encoded binary string that holds the cipher value.Algorithm: Cryptographic algorithm used for encryption, of the type defined in section 2.2.3.12.SigningCertificateSignatureThe SigningCertificateSignature structure denotes the digital signature of the wrapping’s signing certificate computed by using the signing certificate of the specified parent wrapping ID.<xs:element name="SigningCertificateSignature" type="SigningCertificateSignature_T" /> <xs:complexType name="SigningCertificateSignature_T"> <xs:annotation> <xs:documentation>The signing certificate signature is computed using the signing certificate of the parent wrapping over this wrapping's signing certificate.</xs:documentation> </xs:annotation> <xs:sequence> <xs:element name="Signature" type="Signature_T" /> </xs:sequence> <xs:attribute name="ParentWrappingId" type="xs:unsignedInt" use="required" /> </xs:complexType>Signature: A digital signature as defined in section 2.2.2.10ParentWrappingId: A 32-bit unsigned integer that contains the wrapping ID of the parent.EncryptionCertificateSignatureThe EncryptionCertificateSignature structure denotes the signature that is computed using this wrapping’s signing certificate over this wrapping’s encryption certificate.<xs:element name="EncryptionCertificateSignature" type="EncryptionCertificateSignature_T" /> <xs:complexType name="EncryptionCertificateSignature_T"> <xs:annotation> <xs:documentation>The encryption certificate signature is computed using this wrapping's signing certificate over this wrapping's encryption certificate.</xs:documentation> </xs:annotation> <xs:sequence> <xs:element name="Signature" type="Signature_T" /> </xs:sequence> </xs:complexType>Signature: A digital signature as defined in section 2.2.2.10TransportKeyThe TransportKey element is used to help protect data secured by the key protectors. This contains the transport key encrypted by the encryption certificate.<xs:element name="TransportKey" type="TransportKey_T" /> <xs:complexType name="TransportKey_T"> <xs:sequence> <xs:element name="EncryptedData" type="EncryptedData_T" /> </xs:sequence> </xs:complexType>ParametersThe Parameters element denotes the cryptographic parameters used to perform Key Protection Services.<xs:element name="Parameters" type="CryptoParameters_T"/> <xs:complexType name="CryptoParameters_T"> <xs:sequence> <xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType>Simple Types XE "Messages:simple types" XE "Simple types" The following table summarizes the set of common simple type definitions that are included in this specification.Simple typeSectionDescriptionIngressProtector2.2.3.1The IngressProtector contains the entire ingress protector as serialized to a file and converted to a base64-encoded string.HealthCertificate2.2.3.2A base64-encoded binary string of type X.509 format received as input from the client for which Key Protection Services needs to be provided.TransferKeyEncryptionAlgorithm2.2.3.3The algorithm to encrypt the wrapping key's transfer key.WrappingKeyEncryptionAlgorithm2.2.3.4The algorithm to encrypt the transport keys’ wrapping key.TransportKeyEncryptionAlgorithm2.2.3.5The algorithm to encrypt the transport keys.EgressProtector2.2.3.6A base64-encoded string of type UTF-8 format, which contains the entire egress protector as serialized to a file.EncryptedTransferKey2.2.3.7A base64-encoded string of type UTF-8 format, which contains the wrapping key's transfer key encrypted by the health certificate.EncryptedWrappingKey2.2.3.8A base64-encoded string of type UTF-8 format, which contains the transport keys’ wrapping key that is encrypted by the transfer key.EncryptedTransportKeys2.2.3.9A base64-encoded string of type UTF-8 format, which contains the ingress and egress transport keys, which are encrypted by the transport keys' wrapping key.Version2.2.3.10Version of the TransportKey BLOB.Certificate2.2.3.11Certificate used to generate the key protectors .Algorithm2.2.3.12Cryptographic algorithm used to perform Key Protection Services.IngressProtectorThe IngressProtector element denotes the entire ingress protector, as defined in section 2.2.2.3, as serialized to a file and converted to a base64-encoded binary string.<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>HealthCertificateThe HealthCertificate element is a base64-encoded binary string of type X.509 format received as input from the client for which Key Protection Services needs to be provided.<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>TransferKeyEncryptionAlgorithmThe TransferKeyEncryptionAlgorithm element denotes the algorithm to encrypt the wrapping key’s transfer key.<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>WrappingKeyEncryptionAlgorithmThe WrappingKeyEncryptionAlgorithm element denotes the algorithm to encrypt the transport keys’ wrapping key.<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>TransportKeyEncryptionAlgorithmThe TransportKeyEncryptionAlgorithm element denotes the algorithm to encrypt the transport keys.<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>EgressProtectorThe EgressProtector element denotes a base64-encoded string of type UTF-8 format, which contains the entire egress protector, as defined in section 2.2.2.3, as serialized to a file.<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>EncryptedTransferKeyThe EncryptedTransferKey element denotes a base64-encoded string of type UTF-8 format, which contains the wrapping key's transfer key encrypted by the health certificate.<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>EncryptedWrappingKeyThe EncryptedWrappingKey element denotes a base64-encoded string of type UTF-8 format, which contains the transport keys’ wrapping key that is encrypted by the transfer key.<xs:element name="EncryptedWrappingKey"> <xs:annotation> <xs:documentation>The transport keys' wrapping 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>EncryptedTransportKeysThe EncryptedTransportKeys element denotes a base64-encoded string of type UTF-8 format, which contains the ingress and egress transport keys encrypted by the transport keys’ wrapping key.<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>VersionThe following table summarizes the list of supported API versions.VersionSectionDescriptionV1.02.2.3.10.1 Original API version.V2.02.2.3.10.2Updated API version including policy information in addition to the payload in version V1.0. HYPERLINK \l "Appendix_A_2" \o "Product behavior note 2" \h <2>Payload_V1 structurePayload_V1 structure represents the payload in API version V1.0.01234567891012345678920123456789301DataSizeVersionNumberOfKeysKeyLengthKeyValue (variable).........DataSize (4 bytes): Total size of the TransportKey BLOB.Version (4 bytes): Version of the TransportKey BLOB set to value 1.NumberOfKeys (4 bytes): Total number of keys contained in the TransportKey BLOB.KeyLength (4 bytes): The size of the key in bytes.KeyValue (variable): A variable-length field containing the key data.Payload_V2 structurePayload_V2 structure represents the payload in API version V2.0. HYPERLINK \l "Appendix_A_3" \o "Product behavior note 3" \h <3>01234567891012345678920123456789301DataSizeVersionNumberOfKeysKeyLengthKeyValue (variable).........NumberOfPoliciesPolicies (variable).........DataSize (4 bytes): Total size of the TransportKey BLOB.Version (4 bytes): Version of the TransportKey BLOB set to value 2.NumberOfKeys (4 bytes): Total number of keys contained in the TransportKey BLOB.KeyLength (4 bytes): The size of the key in bytes.KeyValue (variable): A variable-length field containing the key data.NumberOfPolicies (4 bytes): Total number of key policies contained in the TransportKey BLOB. If this is a non-zero value, Policies field contains the number of key policies indicated by this field.Policies (variable): A variable-length field containing an array of key policy data elements. NumberOfPolicies field indicates the size of this array. Each policy data element of this array takes the form of the structure specified in section 2.2.3.10.2.1.Policy Data structureThis structure contains the key policy data sent by the KPS in the TransportKey BLOB. HYPERLINK \l "Appendix_A_4" \o "Product behavior note 4" \h <4>01234567891012345678920123456789301PolicyIdPolicyTypePolicyDataSizePolicyData (variable).........PolicyId (4 bytes): The ID of the key policy. This MUST be set to 1.PolicyType (4 bytes): The type of the key policy. This MUST be set to 6.PolicyDataSize (4 bytes): The size of the policy data in bytes.PolicyData (variable): A variable-length field containing the policy data.CertificateThe Certificate element is used to generate the key protectors.<xs:element name="Certificate" type="Certificate_T" /> <xs:simpleType name="Certificate_T"> <xs:annotation> <xs:documentation>A certificate in the DER-encoded binary X.509 format.</xs:documentation> </xs:annotation> <xs:restriction base="xs:base64Binary" /> </xs:simpleType>AlgorithmThe Algorithm element denotes the cryptographic algorithm identifier used to perform Key Protection Services. <xs:element name="Algorithm" type="CryptoAlgorithm_T" use="required" /> <xs:simpleType name="CryptoAlgorithm_T"> <xs:restriction base="xs:anyURI" /> </xs:simpleType>Protocol DetailsServer DetailsAbstract Data Model XE "Server:Abstract data model" XE "Abstract data model:server" XE "Data model – abstract:server" This section describes a conceptual model of possible data organization that an implementation maintains to participate in this protocol. The described organization is provided to facilitate the explanation of how the protocol behaves. This document does not mandate that implementations adhere to this model as long as their external behavior is consistent with that described in this document.The server implements the following:IngressProtector: Contains the entire ingress protector as serialized to a file and converted to base64-encoded string as defined in section 2.2.3.1.Protector: A collection of different cryptographic wrappings of the transport key as defined in section 2.2.2.3.Wrapping: Consists of certificates of type base64-encoded strings and the transport key. EgressProtector: A base64-encoded string of type UTF-8 format, which contains the entire egress protector as serialized to a file as defined in section 2.2.3.6.PrimaryEncryptionCertificate: A base64-encoded binary string of type X.509 format as defined in section 2.2.3.11.PrimarySigningCertificate: A base64-encoded binary string of type X.509 format as defined in section 2.2.3.11.Error: A string representing the error response as defined in section 2.2.2.5.IngressTransportKey: Key extracted from the ingress protector.EgressTransportKey: Key generated from the RollTransportKey BLOB after Protector Validation.Timers XE "Server:Timers" XE "Timers:server" None.Initialization XE "Server:Initialization" XE "Initialization:server" IngressProtector: MUST be set to empty.Protector: MUST be set to empty.Wrapping: MUST be set to empty.EgressProtector: MUST be set to empty.PrimaryEncryptionCertificate: MUST be set to empty.PrimarySigningCertificate: MUST be set to NULL.Error: MUST be set to empty.IngressTransportKey: MUST be set to empty.EgressTransportKey: MUST be set to empty.Higher-Layer Triggered Events XE "Server:Higher-layer triggered events" XE "Higher-layer triggered events:server" None.Message Processing Events and Sequencing RulesService APIs XE "Message processing:server - service APIs" XE "Server:message processing" XE "Server:sequencing rules" XE "Sequencing rules:server" The following HTTP methods are allowed to be performed on this resource.HTTP methodSectionDescriptionRollTransportKey3.1.5.1.1Used to protect the keys by KPS.GetMetaData3.1.5.1.2Retrieves the list of valid certificates present in the KPS.RollTransportKeyThe following operations are allowed to be performed on this resource.HTTP methodDescriptionPOSTRequests that a web server accept and store the data enclosed in the body of the request message.This operation is transported by an HTTP POST request.The operation can be invoked through the following URI.{version}/rolltransportkeyVersion: Version of the RollTransportKey request as defined in section 2.2.3.10.Request BodyRollTransportKey handles the unwrapping of a TransportKey from a Protector by this KPS, as well as the generation of a new TransportKey and corresponding Protector for use in subsequent serialization of the object. The resulting new key protector will be owned by the original Owner, and Key Protection Service will be the Guardian. The request body for this method contains the following as defined in section 2.2.2.1.EntryTypeHealthCertificateA certificate in X.509 format that is converted to a base64-encoded string.IngressProtectorEntire ingress protector as serialized to a file (UTF-8 format, for example) and converted into a base64-encoded string.TransferKeyEncryptionAlgorithmThe algorithm used to encrypt the wrapping key's transfer key defined in section 2.2.3.3.WrappingKeyEncryptAlgorithmThe algorithm used to encrypt the wrapping key defined in section 2.2.3.4.TransportKeyEncryptAlgorithmThe algorithm used to encrypt the transport key defined in section 2.2.3.5.Response BodyThe response body of this method contains the following as defined in section 2.2.2.2.EntryTypeEgressProtectorA base64-encoded string of type UTF-8 format, which contains the entire egress protector as serialized to a file as defined in section 2.2.3.6.EncryptedTXBlobThe BLOB containing the EncryptedTransferKey as defined in section 2.2.3.7.EncryptedTWBlobThe BLOB containing the EncryptedWrappingKey as defined in section 2.2.3.8.EncryptedTKBlobThe BLOB containing the EncryptedTransportKeys as defined in section 2.2.3.9.A successful operation returns status code 200 (OK). Otherwise, an error is returned.The response message for this method can result in the following status codes.Status codeDescription200OK204No content.Processing DetailsThe server MUST perform the following steps after receiving RollTransportKey.Validate the HealthCertificate in an implementation-specific manner and return an error “HealthCertificateException” if validation fails.Validate that the IngressProtector is in a valid XML format and return the error “InvalidProtectorException” if validation fails.Validate the following in the IngressProtector in an implementation-specific manner and return the error “InvalidProtectorException” if validation fails:WrappingId in GuardianSignature points to a valid wrapping.Signature fields in GuardianSignature and TransportKeySignature have valid values.Validate that each Wrapping in the Wrappings field of IngressProtector is properly constructed and signed, as follows, and return the error “InvalidWrappingException” if validation fails:SigningCertificate and EncryptionCertificate are valid X.509 certificates.ParentWrappingId in SigningCertificateSignature points to a valid wrapping in the protector, or to the current Wrapping if it is the owner.Current Wrapping chains up to the owner of the protector.Signature in SigningCertificateSignature is created using the SigningCertificate of the parent wrapping.Signature in EncryptionCertificateSignature is created using the SigningCertificate of the current wrapping.Verify that Protector has a wrapping for the KPS, process the IngressProtector and extract the IngressTransportKey, generate EgressTransportKey, and generate an EgressProtector in an implementation-specific manner. Sign the EngressProtector with the private key of the KPS’s SigningCertificate, as specified in section 2.2.2.8.Derive the key from the TransportKey of EgressProtector using the KeyDerivationMethod, as specified in section 2.2.2.9, and sign the EgressProtector with that key.Encrypt and sign the TransportKeys of both the IngressProtector and TransportKey in an implementation-specific manner. The server MUST return the EgressProtector and EncryptedTransportKeys to the calling application.GetMetaDataThe following operations are allowed to be performed on this resource.HTTP methodDescriptionGETRetrieves information from the server.This operation is transported by an HTTP GET request.The operation can be invoked through the following URI: list of possible certificates includes PrimaryEncryptionCertificate, PrimarySigningCertificate as defined in section 2.2.3.11, and non-primary certificates, including OtherSigningCertificates, as defined in section 2.2.3.11.The KPS metadata consists of:Optional metadata about the guardian or owner.The KPS PrimarySigningCertificate.The KPS PrimaryEncryptionCertificate.The signature over the KPS encryption certificate by the KPS signing private key.Request BodyThe following operations are allowed to be performed on this resource.HTTP methodDescriptionGETRetrieves information from the server.This operation is transported by an HTTP GET request.The operation can be invoked through the following URI: list of possible certificates includes PrimaryEncryptionCertificate, PrimarySigningCertificate as defined in section 2.2.3.11, and non-primary certificates, including OtherSigningCertificates, as defined in section 2.2.3.11.The KPS metadata consists of:Optional metadata about the guardian or owner.The KPS PrimarySigningCertificate.The KPS PrimaryEncryptionCertificate.The signature over the KPS encryption certificate by the KPS signing private key.Response BodyThe response body of this method contains the following.GetMetadata computes a new metadata document. A successful operation returns status code 200 (OK). Otherwise, an error is returned. The response message for this method can result in the following status codes.Status codeDescription200OKErrorA string representing the error response as defined in section 2.2.2.5.Processing DetailsThe server MUST perform the following steps after receiving GetMetaData request:Get the PrimaryEncryptionCertificate from the registry. If the PrimaryEncryptionCertificate is not found in the registry, return the error string “Primary Encryption Certificate not found”.Get the PrimarySigningCertificate from the registry. If the PrimarySigningCertificate is not found in the registry, return the error string “Primary Signing Certificate not found”.If the request includes adding OtherSigningCertificates to the metadata, get the non-primary signing certificates from the registry,Create signatures needed to generate the metadata document using the primary certificates retrieved above in an implementation-specific manner,Generate the metadata document and return to the calling application.Timer Events XE "Server:Timer events" XE "Timer events:server" None.Other Local Events XE "Server:Other local events" XE "Local events:server" None.Client DetailsAbstract Data Model XE "Client:Abstract data model" XE "Abstract data model:client" XE "Data model – abstract:client" This section describes a conceptual model of possible data organization that an implementation maintains to participate in this protocol. The described organization is provided to facilitate the explanation of how the protocol behaves. This document does not mandate that implementations adhere to this model as long as their external behavior is consistent with that described in this document.Retries: An integer that indicates the number of retries to send the RollTransportKey request.Timers XE "Client:Timers" XE "Timers:client" None.Initialization XE "Client:Initialization" XE "Initialization:client" Retries: A default value that is equivalent to the number of distinct host addresses available for the server URI.Higher-Layer Triggered Events XE "Client:Higher-layer triggered events" XE "Higher-layer triggered events:client" The following sections describe the operations performed by the client in response to events triggered by higher-layer applications.Application Requests RollTransportKeyThe application provides the following:Health Certificate issued by an Attestation Service as defined in [MS-HGSA] and accredited by the KPS.The client MUST perform the following:Create a valid XML BLOB containing RollTransportKeyRequest as defined in section 2.2.2.1.Perform the steps as specified in section 3.2.5.1.Application Requests GetMetaDataThe application provides the following:A GetMetaData request to retrieve the list of KPS-supported certificates, as defined in section 2.2.1.2, to verify that the Protector was properly signed by the KPS.The client MUST perform the following:Perform the steps as specified in section 3.2.5.2.Message Processing Events and Sequencing Rules XE "Client:Message processing events and sequencing rules" XE "Message processing:client" XE "Sequencing rules:client" XE "Client:message procesing" XE "Client:sequencing rules" The following sections describe the sequence of operations performed by the client in RollTransportKey and GetMetaData scenarios.RollTransportKey XE "Message processing:client:RollTransportKey" The client MUST send a POST request on the RollTransportKey resource as specified in section 3.1.5.1.1 by using the URI specified.If the client receives the RollTransportKeyResponse specified in section 2.2.2.2 with the status code 200(OK), the client’s health certificate is protected and the guarded host is enabled to run securely on a VM.If the client receives an error, the client MAY retry sending the RollTransportKey request based on Retries.GetMetaData XE "Message processing:client:GetMetaData" The client MUST send a POST request on the GetMetaData resource as specified in section 3.1.5.1.2 by using the URI specified.If the operation is successful, the client receives the metadata content with status code 200(OK).Timer Events XE "Client:Timer events" XE "Timer events:client" None.Other Local Events XE "Client:Other local events" XE "Local events:client" None.Protocol Examples XE "Examples" None.SecuritySecurity Considerations for Implementers XE "Security:implementer considerations" XE "Implementer - security considerations" None.Index of Security Parameters XE "Security:parameter index" XE "Index of security parameters" XE "Parameters - security index" None.Appendix A: Full XML Schema XE "XML schema" XE "Full XML schema" For ease of implementation, the following is the full XML schema for this protocol.Schema namePrefixSectionProtector SchemaP6.1RollTransportKey RequestReq6.2RollTransportKey ResponseRes6.3MetaData ResponseM6.4Crypto SchemaNot applicable6.5Protector Schema<?xml version="1.0" encoding="utf-8"?><xs:schema targetNamespace="" elementFormDefault="qualified" xmlns="" xmlns:xs=""> <xs:include schemaLocation="Crypto.xsd" /> <xs:complexType name="SigningCertificateSignature_T"> <xs:annotation> <xs:documentation>The signing certificate signature is computed using the signing certificate of the parent wrapping (specified by ParentWrappingId) over this wrapping's signing certificate.</xs:documentation> </xs:annotation> <xs:sequence> <xs:element name="Signature" type="Signature_T" /> </xs:sequence> <xs:attribute name="ParentWrappingId" type="xs:unsignedInt" use="required" /> </xs:complexType> <xs:complexType name="EncryptionCertificateSignature_T"> <xs:annotation> <xs:documentation>The encryption certificate signature is computed using this wrapping's signing certificate over this wrapping's encryption certificate.</xs:documentation> </xs:annotation> <xs:sequence> <xs:element name="Signature" type="Signature_T" /> </xs:sequence> </xs:complexType> <xs:complexType name="TransportKey_T"> <xs:sequence> <xs:element name="EncryptedData" type="EncryptedData_T" /> </xs:sequence> </xs:complexType> <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> <xs:complexType name="WrappingCollection_T"> <xs:sequence> <xs:element name="Wrapping" type="Wrapping_T" minOccurs="1" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> <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> <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> <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:attribute name="MaxOfflineUnwraps" type="xs:unsignedInt" default="0" /> </xs:complexType></xs:schema>RollTransportKey Request SchemaRollTransportKey request schema is defined in section 2.2.2.1RollTransportKey Response SchemaRollTransportKey response schema is defined in section 2.2.2.2.MetaData Resposne Schema<?xml version="1.0" encoding="utf-8"?><xs:schema targetNamespace="" elementFormDefault="qualified" xmlns="" xmlns:xs="" xmlns:ds=""> <xs:import namespace="" /> <xs:include schemaLocation="Crypto.xsd" /> <xs:complexType name="GuardianInformation_T"> <xs:annotation> <xs:documentation>The guardian information for an entity.</xs:documentation> </xs:annotation> <xs:sequence> <xs:element name="Version" type="xs:unsignedInt" /> <xs:element name="EncryptionCertificate" type="Certificate_T" /> <xs:element name="SigningCertificate" type="Certificate_T" /> <xs:element name="EncryptionCertificateSignature" type="Signature_T" /> <xs:element name="SigningCertificateSelfSignature" type="Signature_T" /> <xs:element name="OtherSigningCertificates" type="CertificateCollection_T" minOccurs="0" /> </xs:sequence> </xs:complexType> <xs:element name="Metadata" type="Metadata_T" /> <xs:complexType name="Metadata_T"> <xs:annotation> <xs:documentation>The metadata document contains information about the entity.</xs:documentation> </xs:annotation> <xs:sequence> <xs:element name="GuardianInformation" type="GuardianInformation_T" /> <xs:element ref="ds:Signature" /> <xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded" /> </xs:sequence> <xs:attribute name="ID" use="optional" type="xs:ID" /> <xs:attribute name="Version" use="required" type="xs:unsignedInt" /> <xs:anyAttribute namespace="##any" processContents="lax" /> </xs:complexType></xs:schema>Crypto Schema<?xml version="1.0" encoding="utf-8"?><xs:schema targetNamespace="" elementFormDefault="qualified" xmlns="" xmlns:xs=""> <xs:complexType name="CryptoParameters_T"> <xs:sequence> <xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> <xs:simpleType name="CryptoAlgorithm_T"> <xs:restriction base="xs:anyURI" /> </xs:simpleType> <xs:complexType name="Signature_T"> <xs:sequence> <xs:element name="Parameters" type="CryptoParameters_T" minOccurs="0" /> <xs:element name="SignatureValue"> <xs:simpleType> <xs:restriction base="xs:base64Binary" /> </xs:simpleType> </xs:element> </xs:sequence> <xs:attribute name="Algorithm" type="CryptoAlgorithm_T" use="required" /> </xs:complexType> <xs:element name="EncryptedData" type="EncryptedData_T" /> <xs:complexType name="EncryptedData_T"> <xs:sequence> <xs:element name="Parameters" type="CryptoParameters_T" minOccurs="0" /> <xs:element name="CipherValue"> <xs:simpleType> <xs:restriction base="xs:base64Binary" /> </xs:simpleType> </xs:element> </xs:sequence> <xs:attribute name="Algorithm" type="CryptoAlgorithm_T" use="required" /> </xs:complexType> <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> <xs:simpleType name="Certificate_T"> <xs:annotation> <xs:documentation>A certificate in the DER-encoded binary X.509 format.</xs:documentation> </xs:annotation> <xs:restriction base="xs:base64Binary" /> </xs:simpleType> <xs:complexType name="CertificateCollection_T"> <xs:sequence> <xs:element name="Certificate" type="Certificate_T" minOccurs="0" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType></xs:schema>Appendix B: Product Behavior XE "Product behavior" The information in this specification is applicable to the following Microsoft products or supplemental software. References to product versions include updates to those products.The terms "earlier" and "later", when used with a product version, refer to either all preceding versions or all subsequent versions, respectively. The term "through" refers to the inclusive range of versions. Applicable Microsoft products are listed chronologically in this section. Windows ClientWindows 10 v1703 operating system Windows ServerWindows Server 2016 operating systemWindows Server operating systemWindows Server 2019 operating systemExceptions, if any, are noted in this section. If an update version, service pack or Knowledge Base (KB) number appears with a product name, the behavior changed in that update. The new behavior also applies to subsequent updates unless otherwise specified. If a product edition appears with the product version, behavior is different in that product edition.Unless otherwise specified, any statement of optional behavior in this specification that is prescribed using the terms "SHOULD" or "SHOULD NOT" implies product behavior in accordance with the SHOULD or SHOULD NOT prescription. Unless otherwise specified, the term "MAY" implies that the product does not follow the prescription. HYPERLINK \l "Appendix_A_Target_1" \h <1> Section 2.2.2.3: Not supported in client releases earlier than Windows 10 v1803 operating system or server releases earlier than Windows Server v1803 operating system. HYPERLINK \l "Appendix_A_Target_2" \h <2> Section 2.2.3.10: Not supported in client releases earlier than Windows 10 v1803 or server releases earlier than Windows Server v1803. HYPERLINK \l "Appendix_A_Target_3" \h <3> Section 2.2.3.10.2: Not supported in client releases earlier than Windows 10 v1803 or server releases earlier than Windows Server v1803. HYPERLINK \l "Appendix_A_Target_4" \h <4> Section 2.2.3.10.2.1: Policy Data is not supported in client releases earlier than Windows 10 v1803 or server releases earlier than Windows Server v1803.Change Tracking XE "Change tracking" XE "Tracking changes" No table of changes is available. The document is either new or has had no changes since its last release.IndexAAbstract data model client PAGEREF section_279cba0626ce487da26c6d4272aa756329 server PAGEREF section_58346cef5bfe4a6c9901651a166e492624Applicability PAGEREF section_dd1cc2001bcc4d969d5e28d4f7675bf56CCapability negotiation PAGEREF section_6d8009d9f9ee46b1981701f14cb513936Change tracking PAGEREF section_d1b8a1cb72cf4c9e83c27c79feff859a38Client Abstract data model PAGEREF section_279cba0626ce487da26c6d4272aa756329 Higher-layer triggered events PAGEREF section_c3b0567022c14542a203bb7228f81e5229 Initialization PAGEREF section_6bedaeb9f0eb4ab2879ef80caef16a0e29 message procesing PAGEREF section_7ed7e0ce3b0b4bbb8ef5c2804eede8c630 Message processing events and sequencing rules PAGEREF section_7ed7e0ce3b0b4bbb8ef5c2804eede8c630 Other local events PAGEREF section_0786922fb8a24d6c82492a0d56deb4ba30 sequencing rules PAGEREF section_7ed7e0ce3b0b4bbb8ef5c2804eede8c630 Timer events PAGEREF section_64d6e02fe46145e899df9da3cc9b4a6630 Timers PAGEREF section_08a2176f603d4bc88dad0c26a9101bc429Complex types PAGEREF section_e11c16ac84b44cd08c27c028fe269bc88DData model – abstract client PAGEREF section_279cba0626ce487da26c6d4272aa756329 server PAGEREF section_58346cef5bfe4a6c9901651a166e492624EExamples PAGEREF section_57dc5dba5ee14a458ec8852be9ef8cce31FFields - vendor-extensible PAGEREF section_7e59ab0093354d27b920897d40295db76Full XML schema PAGEREF section_68eab90c09fb4856b30e367f948a0f3933GGlossary PAGEREF section_55bbdbcc46804e3c9e38dbf705e9bcce5HHigher-layer triggered events client PAGEREF section_c3b0567022c14542a203bb7228f81e5229 server PAGEREF section_0cbfddab8ee94650adba3d5fc7e5238225HTTP methods PAGEREF section_c463edb4c0184496b09e0d809bbffc447IImplementer - security considerations PAGEREF section_7b8db2a21a5847c89ec2b85f59c0817832Index of security parameters PAGEREF section_155aded70a8049d0bd3648c28d0fcde932Informative references PAGEREF section_bb8eb1e548324f5bada303e2cbf690446Initialization client PAGEREF section_6bedaeb9f0eb4ab2879ef80caef16a0e29 server PAGEREF section_81e6e4ab8f2244348e30e327c8b13bb224Introduction PAGEREF section_1554b23267814bcd87ac3ef11a40a85d5LLocal events client PAGEREF section_0786922fb8a24d6c82492a0d56deb4ba30 server PAGEREF section_94ee8f76b47e4b2b9e8eae65405e7d5229MMessage processing client PAGEREF section_7ed7e0ce3b0b4bbb8ef5c2804eede8c630 GetMetaData PAGEREF section_8322356500b14c858266928db821938b30 RollTransportKey PAGEREF section_8062476d0fa04bc2be2af4436dd5e22830 server - service APIs PAGEREF section_cbf28c960ba1442e8c82d4b5863e3b9b25Messages complex types PAGEREF section_e11c16ac84b44cd08c27c028fe269bc88 HTTP methods PAGEREF section_c463edb4c0184496b09e0d809bbffc447 simple types PAGEREF section_87ed294b8dc44aef8de965fb5983788716 transport PAGEREF section_037d9e9dbafe41619ff64b9f0a73ce997NNormative references PAGEREF section_5a60d9576171414d8e97eb9e8f8933916OOverview (synopsis) PAGEREF section_ca6c486555014d01b2c55a12f59fd8746PParameters - security index PAGEREF section_155aded70a8049d0bd3648c28d0fcde932Preconditions PAGEREF section_b794e3cb34bb4685a718428c0c2e23ff6Prerequisites PAGEREF section_b794e3cb34bb4685a718428c0c2e23ff6Product behavior PAGEREF section_57295f88f2a94f5f918bc51ba6261f1a37RReferences informative PAGEREF section_bb8eb1e548324f5bada303e2cbf690446 normative PAGEREF section_5a60d9576171414d8e97eb9e8f8933916Relationship to other protocols PAGEREF section_a8f0c9da574a466bbc605c3890f889846SSecurity implementer considerations PAGEREF section_7b8db2a21a5847c89ec2b85f59c0817832 parameter index PAGEREF section_155aded70a8049d0bd3648c28d0fcde932Sequencing rules client PAGEREF section_7ed7e0ce3b0b4bbb8ef5c2804eede8c630 server PAGEREF section_cbf28c960ba1442e8c82d4b5863e3b9b25Server Abstract data model PAGEREF section_58346cef5bfe4a6c9901651a166e492624 Higher-layer triggered events PAGEREF section_0cbfddab8ee94650adba3d5fc7e5238225 Initialization PAGEREF section_81e6e4ab8f2244348e30e327c8b13bb224 message processing PAGEREF section_cbf28c960ba1442e8c82d4b5863e3b9b25 Other local events PAGEREF section_94ee8f76b47e4b2b9e8eae65405e7d5229 sequencing rules PAGEREF section_cbf28c960ba1442e8c82d4b5863e3b9b25 Timer events PAGEREF section_942f248d472e4abab7e87b003853d33f29 Timers PAGEREF section_93a3928977e649b6b65763610761be0624Simple types PAGEREF section_87ed294b8dc44aef8de965fb5983788716Standards assignments PAGEREF section_bc5dcd6ceeff4178a088657f40e2a5136TTimer events client PAGEREF section_64d6e02fe46145e899df9da3cc9b4a6630 server PAGEREF section_942f248d472e4abab7e87b003853d33f29Timers client PAGEREF section_08a2176f603d4bc88dad0c26a9101bc429 server PAGEREF section_93a3928977e649b6b65763610761be0624Tracking changes PAGEREF section_d1b8a1cb72cf4c9e83c27c79feff859a38Transport PAGEREF section_037d9e9dbafe41619ff64b9f0a73ce997VVendor-extensible fields PAGEREF section_7e59ab0093354d27b920897d40295db76Versioning PAGEREF section_6d8009d9f9ee46b1981701f14cb513936XXML schema PAGEREF section_68eab90c09fb4856b30e367f948a0f3933 ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download