This document is intended for developers and architects who wish to design systems and applications that interoperate using the Key Management Interoperability Protocol specification.

Status:

This document was last revised or approved by the Key Management Interoperability Protocol TC on the above date. The level of approval is also listed above. Check the “Latest Version” or “Latest Approved Version” location noted above for possible later revisions of this document.

Technical Committee members should send comments on this specification to the Technical Committee’s email list. Others should send comments to the Technical Committee by using the “Send A Comment” button on the Technical Committee’s web page at http://www.oasis-open.org/committees/kmip/.

For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the Technical Committee web page (http://www.oasis-open.org/committees/kmip/ipr.php).

The non-normative errata page for this specification is located at http://www.oasis-open.org/committees/kmip/.

Notices

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.

OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.

OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.

The names "OASIS", “KMIP” are trademarks of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see http://www.oasis-open.org/who/trademark.php for above guidance.

Table of Contents

1 Introduction. 8

1.1 Terminology. 8

1.2 Normative References. 11

1.3 Non-normative References. 13

2.1.5 Key Wrapping Data. 18

2.1.6 Key Wrapping Specification. 19

2.1.7 Transparent Key Structures. 20

2.1.8 Template-Attribute Structures. 25

2.2 Managed Objects. 25

2.2.1 Certificate. 25

2.2.2 Symmetric Key. 26

2.2.3 Public Key. 26

2.2.4 Private Key. 26

2.2.5 Split Key. 26

2.2.6 Template. 28

2.2.7 Secret Data. 29

2.2.8 Opaque Object 29

3 Attributes. 30

3.1 Unique Identifier 31

3.2 Name. 32

3.3 Object Type. 32

3.4 Cryptographic Algorithm.. 33

3.5 Cryptographic Length. 33

3.6 Cryptographic Parameters. 34

3.7 Cryptographic Domain Parameters. 35

3.8 Certificate Type. 36

3.9 Certificate Identifier 36

3.10 Certificate Subject 37

3.11 Certificate Issuer 38

3.12 Digest 38

3.13 Operation Policy Name. 39

3.13.1 Operations outside of operation policy control 40

3.13.2 Default Operation Policy. 40

3.14 Cryptographic Usage Mask. 43

3.15 Lease Time. 44

3.16 Usage Limits. 45

3.17 State. 46

3.18 Initial Date. 48

3.19 Activation Date. 48

3.20 Process Start Date. 49

3.21 Protect Stop Date. 50

3.22 Deactivation Date. 51

3.23 Destroy Date. 51

3.24 Compromise Occurrence Date. 52

3.25 Compromise Date. 52

3.26 Revocation Reason. 53

3.27 Archive Date. 53

3.28 Object Group. 54

3.29 Link. 54

3.30 Application Specific Information. 56

3.31 Contact Information. 56

3.32 Last Change Date. 57

3.33 Custom Attribute. 57

4 Client-to-Server Operations. 59

4.1 Create. 59

4.2 Create Key Pair 60

4.11 Get Attributes. 74

4.12 Get Attribute List 75

4.13 Add Attribute. 75

4.14 Modify Attribute. 76

4.15 Delete Attribute. 76

4.16 Obtain Lease. 77

4.17 Get Usage Allocation. 78

5 Server-to-Client Operations. 84

5.1 Notify. 84

5.2 Put 84

6 Message Contents. 86

6.1 Protocol Version. 86

6.2 Operation. 86

6.3 Maximum Response Size. 86

6.4 Unique Batch Item ID.. 86

6.5 Time Stamp. 87

6.6 Authentication. 87

6.7 Asynchronous Indicator 87

6.8 Asynchronous Correlation Value. 87

6.9 Result Status. 88

6.10 Result Reason. 88

6.11 Result Message. 89

6.12 Batch Order Option. 89

6.13 Batch Error Continuation Option. 89

6.14 Batch Count 90

6.15 Batch Item.. 90

6.16 Message Extension. 90

7 Message Format 91

7.1 Message Structure. 91

7.2 Operations. 91

8 Authentication. 93

9 Message Encoding. 94

9.1 TTLV Encoding. 94

9.1.1 TTLV Encoding Fields. 94

9.1.2 Examples. 96

9.1.3 Defined Values. 97

9.2 XML Encoding. 117

10 Transport 118

11 Error Handling. 119

11.1 General 119

11.2 Create. 120

11.3 Create Key Pair 120

11.12 Get Attributes. 125

11.13 Get Attribute List 125

11.14 Add Attribute. 125

11.15 Modify Attribute. 126

11.16 Delete Attribute. 126

11.17 Obtain Lease. 127

11.18 Get Usage Allocation. 127

11.28 Batch Items. 129

12 Server Baseline Implementation Conformance Profile. 130

12.1 Conformance clauses for a KMIP Server 130

A. Attribute Cross-reference. 132

B. Tag Cross-reference. 134

C. Operation and Object Cross-reference. 139

D. Acronyms. 140

E. List of Figures and Tables. 143

F. Acknowledgements. 150

G. Revision History. 152

1 Introduction

This document is intended as a specification of the protocol used for the communication between clients and servers to perform certain management operations on objects stored and maintained by a key management system. These objects are referred to as Managed Objects in this specification. They include symmetric and asymmetric cryptographic keys, digital certificates, and templates used to simplify the creation of objects and control their use. Managed Objects are managed with operations that include the ability to generate cryptographic keys, register objects with the key management system, obtain objects from the system, destroy objects from the system, and search for objects maintained by the system. Managed Objects also have associated attributes, which are named values stored by the key management system and are obtained from the system via operations. Certain attributes are added, modified, or deleted by operations.

The protocol specified in this document includes several certificate-related functions for which there are a number of existing protocols – namely Validate (e.g., SCVP or XKMS), Certify (e.g. CMP, CMC, SCEP) and Re-certify (e.g. CMP, CMC, SCEP). The protocol does not attempt to define a comprehensive certificate management protocol, such as would be needed for a certification authority. However, it does include functions that are needed to allow a key server to provide a proxy for certificate management functions.

In addition to the normative definitions for managed objects, operations and attributes, this specification also includes normative definitions for the following aspects of the protocol:

· The expected behavior of the server and client as a result of operations,

· Message contents and formats,

· Message encoding (including enumerations), and

· Error handling.

This specification is complemented by three other documents. The Usage Guide [KMIP-UG] provides illustrative information on using the protocol. The KMIP Profiles Specification [KMIP-Prof] provides a selected set of conformance profiles and authentication suites. The Test Specification [KMIP-UC] provides samples of protocol messages corresponding to a set of defined test cases.

This specification defines the KMIP protocol version major 1 and minor 0 (see 6.1).

1.1 Terminology

The key words "SHALL", "SHALL NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. The words ‘must’, ‘can’, and ‘will’ are forbidden.

For definitions not found in this document, see [SP800-57-1].

Archive	To place information not accessed frequently into long-term storage.
Asymmetric key pair (key pair)	A public key and its corresponding private key; a key pair is used with a public key algorithm.
Authentication	A process that establishes the origin of information, or determines an entity’s identity.
Authentication code	A cryptographic checksum based on a security function (also known as a Message Authentication Code).
Authorization	Access privileges that are granted to an entity; conveying an “official” sanction to perform a security function or activity.
Certification authority	The entity in a Public Key Infrastructure (PKI) that is responsible for issuing certificates, and exacting compliance to a PKI policy.
Ciphertext	Data in its encrypted form.
Compromise	The unauthorized disclosure, modification, substitution or use of sensitive data (e.g., keying material and other security-related information).
Confidentiality	The property that sensitive information is not disclosed to unauthorized entities.
Cryptographic algorithm	A well-defined computational procedure that takes variable inputs, including a cryptographic key and produces an output.
Cryptographic key (key)	A parameter used in conjunction with a cryptographic algorithm that determines its operation in such a way that an entity with knowledge of the key can reproduce or reverse the operation, while an entity without knowledge of the key cannot. Examples include: 1. The transformation of plaintext data into ciphertext data, 2. The transformation of ciphertext data into plaintext data, 3. The computation of a digital signature from data, 4. The verification of a digital signature, 5. The computation of an authentication code from data, 6. The verification of an authentication code from data and a received authentication code.
Decryption	The process of changing ciphertext into plaintext using a cryptographic algorithm and key.
Digest (or hash)	The result of applying a hash function to information.
Digital signature (signature)	The result of a cryptographic transformation of data that, when properly implemented with supporting infrastructure and policy, provides the services of: 1. origin authentication 2. data integrity, and 3. signer non-repudiation.
Encryption	The process of changing plaintext into ciphertext using a cryptographic algorithm and key.
Hashing algorithm	An algorithm that maps a bit string of arbitrary length to a fixed length bit string. Approved hashing algorithms satisfy the following properties: 1. (One-way) It is computationally infeasible to find any input that maps to any pre-specified output, and 2. (Collision resistant) It is computationally infeasible to find any two distinct inputs that map to the same output.
Integrity	The property that sensitive data has not been modified or deleted in an unauthorized and undetected manner.
Key derivation (derivation)	A function in the lifecycle of keying material; the process by which one or more keys are derived from 1) either a shared secret from a key agreement computation or a pre-shared cryptographic key, and 2) other information.
Key management	The activities involving the handling of cryptographic keys and other related security parameters (e.g., IVs and passwords) during the entire life cycle of the keys, including their generation, storage, establishment, entry and output, and destruction.
Key wrapping (wrapping)	A method of encrypting and/or MACing/signing keys using cryptographic keys.
Message authentication code (MAC)	A cryptographic checksum on data that uses a symmetric key to detect both accidental and intentional modifications of data.
Private key	A cryptographic key, used with a public key cryptographic algorithm, that is uniquely associated with an entity and is not made public. The private key is associated with a public key. Depending on the algorithm, the private key may be used to: 1. Compute the corresponding public key, 2. Compute a digital signature that may be verified by the corresponding public key, 3. Decrypt data that was encrypted by the corresponding public key, or 4. Compute a piece of common shared data, together with other information.
Profile	A specification of objects, attributes, operations, message elements and authentication methods to be used in specific contexts of key management server and client interactions (see [KMIP-Prof]).
Public key	A cryptographic key used with a public key cryptographic algorithm that is uniquely associated with an entity and that may be made public. The public key is associated with a private key. The public key may be known by anyone and, depending on the algorithm, may be used to: 1. Verify a digital signature that is signed by the corresponding private key, 2. Encrypt data that can be decrypted by the corresponding private key, or 3. Compute a piece of shared data.
Public key certificate (certificate)	A set of data that uniquely identifies an entity, contains the entity's public key and possibly other information, and is digitally signed by a trusted party, thereby binding the public key to the entity.
Public key cryptographic algorithm	A cryptographic algorithm that uses two related keys, a public key and a private key. The two keys have the property that determining the private key from the public key is computationally infeasible.
Public Key Infrastructure	A framework that is established to issue, maintain and revoke public key certificates.
Recover	To retrieve information that was archived to long-term storage.
Split knowledge	A process by which a cryptographic key is split into n multiple key components, individually providing no knowledge of the original key, which can be subsequently combined to recreate the original cryptographic key. If knowledge of k (where k is less than or equal to n) components is required to construct the original key, then knowledge of any k-1 key components provides no information about the original key other than, possibly, its length.
Symmetric key	A single cryptographic key that is used with a secret (symmetric) key algorithm.
Symmetric key algorithm	A cryptographic algorithm that uses the same secret (symmetric) key for an operation and its complement (e.g., encryption and decryption).
X.509 certificate	The ISO/ITU-T X.509 standard defined two types of certificates – the X.509 public key certificate, and the X.509 attribute certificate. Most commonly (including this document), an X.509 certificate refers to the X.509 public key certificate.
X.509 public key certificate	The public key for a user (or device) and a name for the user (or device), together with some other information, rendered un-forgeable by the digital signature of the certification authority that issued the certificate, encoded in the format defined in the ISO/ITU-T X.509 standard.

Table 1: Terminology

1.2 Normative References

[FIPS186-3] Digital Signature Standard (DSS), FIPS PUB 186-3, Jun 2009, http://csrc.nist.gov/publications/fips/fips186-3/fips_186-3.pdf

[FIPS197] Advanced Encryption Standard, FIPS PUB 197, Nov 2001, http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf

[FIPS198-1] The Keyed-Hash Message Authentication Code (HMAC), FIPS PUB 198-1, Jul 2008, http://csrc.nist.gov/publications/fips/fips198-1/FIPS-198-1_final.pdf

[IEEE1003-1] IEEE Std 1003.1, Standard for information technology - portable operating system interface (POSIX). Shell and utilities, 2004.

[ISO16609] ISO, Banking -- Requirements for message authentication using symmetric techniques, ISO 16609, 1991

[ISO9797-1] ISO/IEC, Information technology -- Security techniques -- Message Authentication Codes (MACs) -- Part 1: Mechanisms using a block cipher, ISO/IEC 9797-1, 1999

[KMIP-Prof] OASIS Committee Draft 05, Key Management Interoperability Protocol Profiles Version 1.0, Mar 2010, http://docs.oasis-open.org/kmip/profiles/v1.0/cd05/kmip-profiles-1.0-cd-05.doc

[PKCS#1] RSA Laboratories, PKCS #1 v2.1: RSA Cryptography Standard, Jun 14, 2002, http://www.rsa.com/rsalabs/node.asp?id=2125

[PKCS#5] RSA Laboratories, PKCS #5 v2.1: Password-Based Cryptography Standard, Oct 5, 2006, http://www.rsa.com/rsalabs/node.asp?id=2127

[PKCS#7] RSA Laboratories, PKCS#7 v1.5: Cryptographic Message Syntax Standard, Nov 1, 1993, http://www.rsa.com/rsalabs/node.asp?id=2129

[PKCS#8] RSA Laboratories, PKCS#8 v1.2: Private-Key Information Syntax Standard, Nov 1, 1993, http://www.rsa.com/rsalabs/node.asp?id=2130

[PKCS#10] RSA Laboratories, PKCS #10 v1.7: Certification Request Syntax Standard, May 26, 2000, http://www.rsa.com/rsalabs/node.asp?id=2132

[RFC1319] B. Kaliski, The MD2 Message-Digest Algorithm, IETF RFC 1319, Apr 1992, http://www.ietf.org/rfc/rfc1319.txt

[RFC1320] R. Rivest, The MD4 Message-Digest Algorithm, IETF RFC 1320, Apr 1992, http://www.ietf.org/rfc/rfc1320.txt

[RFC1321] R. Rivest, The MD5 Message-Digest Algorithm, IETF RFC 1321, Apr 1992, http://www.ietf.org/rfc/rfc1321.txt

[RFC1421] J. Linn, Privacy Enhancement for Internet Electronic Mail: Part I: Message Encryption and Authentication Procedures, IETF RFC 1421, Feb 1993, http://www.ietf.org/rfc/rfc1421.txt

[RFC1424] B. Kaliski, Privacy Enhancement for Internet Electronic Mail: Part IV: Key Certification and Related Services, IETF RFC 1424, Feb 1993, http://www.ietf.org/rfc/rfc1424.txt

[RFC2104] H. Krawczyk, M. Bellare, R. Canetti, HMAC: Keyed-Hashing for Message Authentication, IETF RFC 2104, Feb 1997, http://www.ietf.org/rfc/rfc2104.txt

[RFC2119] S. Bradner, Key words for use in RFCs to Indicate Requirement Levels, IETF RFC 2119, Mar 1997, http://www.ietf.org/rfc/rfc2119.txt

[RFC 2246] T. Dierks and C. Allen, The TLS Protocol, Version 1.0, IETF RFC 2246, Jan 1999, http://www.ietf.org/rfc/rfc2246.txt

[RFC2898] B. Kaliski, PKCS #5: Password-Based Cryptography Specification Version 2.0, IETF RFC 2898, Sep 2000, http://www.ietf.org/rfc/rfc2898.txt

[RFC 3394] J. Schaad, R. Housley, Advanced Encryption Standard (AES) Key Wrap Algorithm, IETF RFC 3394, Sep 2002, http://www.ietf.org/rfc/rfc3394.txt

[RFC3447] J. Jonsson, B. Kaliski, Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography Specifications Version 2.1, IETF RFC 3447, Feb 2003, http://www.ietf.org/rfc/rfc3447.txt

[RFC3629] F. Yergeau, UTF-8, a transformation format of ISO 10646, IETF RFC 3629, Nov 2003, http://www.ietf.org/rfc/rfc3629.txt

[RFC3647] S. Chokhani, W. Ford, R. Sabett, C. Merrill, and S. Wu, Internet X.509 Public Key Infrastructure Certificate Policy and Certification Practices Framework, IETF RFC 3647, Nov 2003, http://www.ietf.org/rfc/rfc3647.txt

[RFC4210] C. Adams, S. Farrell, T. Kause and T. Mononen, Internet X.509 Public Key Infrastructure Certificate Management Protocol (CMP), IETF RFC 2510, Sep 2005, http://www.ietf.org/rfc/rfc4210.txt

[RFC4211] J. Schaad, Internet X.509 Public Key Infrastructure Certificate Request Message Format (CRMF), IETF RFC 4211, Sep 2005, http://www.ietf.org/rfc/rfc4211.txt

[RFC4868] S. Kelly, S. Frankel, Using HMAC-SHA-256, HMAC-SHA-384, and HMAC-SHA-512 with IPsec, IETF RFC 4868, May 2007, http://www.ietf.org/rfc/rfc4868.txt

[RFC4949] R. Shirey, Internet Security Glossary, Version 2, IETF RFC 4949, Aug 2007, http://www.ietf.org/rfc/rfc4949.txt

[RFC5272] J. Schaad and M. Meyers, Certificate Management over CMS (CMC), IETF RFC 5272, Jun 2008, http://www.ietf.org/rfc/rfc5272.txt

[RFC5280] D. Cooper, S. Santesson, S. Farrell, S. Boeyen, R. Housley, W. Polk, Internet X.509 Public Key Infrastructure Certificate, IETF RFC 5280, May 2008, http://www.ietf.org/rfc/rfc5280.txt

[RFC5649] R. Housley, Advanced Encryption Standard (AES) Key Wrap with Padding Algorithm, IETF RFC 5649, Aug 2009, http://www.ietf.org/rfc/rfc5649.txt

[SHAMIR1979] A. Shamir, How to share a secret, Communications of the ACM, vol. 22, no. 11, pp. 612-613, Nov 1979

[SP800-38A] M. Dworkin, Recommendation for Block Cipher Modes of Operation – Methods and Techniques, NIST Special Publication 800-38A, Dec 2001, http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf

[SP800-38B] M. Dworkin, Recommendation for Block Cipher Modes of Operation: The CMAC Mode for Authentication, NIST Special Publication 800-38B, May 2005, http://csrc.nist.gov/publications/nistpubs/800-38B/SP_800-38B.pdf

[SP800-38C] M. Dworkin, Recommendation for Block Cipher Modes of Operation: the CCM Mode for Authentication and Confidentiality, NIST Special Publication 800-38C, May 2004, http://csrc.nist.gov/publications/nistpubs/800-38C/SP800-38C_updated-July20_2007.pdf

[SP800-38D] M. Dworkin, Recommendation for Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC, NIST Special Publication 800-38D, Nov 2007, http://csrc.nist.gov/publications/nistpubs/800-38D/SP-800-38D.pdf

[SP800-38E] M. Dworkin, Recommendation for Block Cipher Modes of Operation: The XTS-AES Mode for Confidentiality on Block-Oriented Storage Devices, NIST Special Publication 800-38E, Jan 2010, http://csrc.nist.gov/publications/nistpubs/800-38E/nist-sp-800-38E.pdf

[SP800-56A] E. Barker, D. Johnson, and M. Smid, Recommendation for Pair-Wise Key Establishment Schemes Using Discrete Logarithm Cryptography (Revised), NIST Special Publication 800-56A, Mar 2007, http://csrc.nist.gov/publications/nistpubs/800-56A/SP800-56A_Revision1_Mar08-2007.pdf

[SP800-56B] E. Barker, L. Chen, A. Regenscheid, and M. Smid, Recommendation for Pair-Wise Key Establishment Schemes Using Integer Factorization Cryptography, NIST Special Publication 800-56B, Aug 2009, http://csrc.nist.gov/publications/nistpubs/800-56B/sp800-56B.pdf

[SP800-57-1] E. Barker, W. Barker, W. Burr, W. Polk, and M. Smid, Recommendations for Key Management - Part 1: General (Revised), NIST Special Publication 800-57 part 1, Mar 2007, http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57-Part1-revised2_Mar08-2007.pdf

[SP800-67] W. Barker, Recommendation for the Triple Data Encryption Algorithm (TDEA) Block Cipher, NIST Special Publication 800-67, Version 1.1, Revised 19 May 2008, http://csrc.nist.gov/publications/nistpubs/800-67/SP800-67.pdf

[SP800-108] L. Chen, Recommendation for Key Derivation Using Pseudorandom Functions (Revised), NIST Special Publication 800-108, Oct 2009, http://csrc.nist.gov/publications/nistpubs/800-108/sp800-108.pdf

[X.509] International Telecommunication Union (ITU)–T, X.509: Information technology – Open systems interconnection – The Directory: Public-key and attribute certificate frameworks, Aug 2005, http://www.itu.int/rec/T-REC-X.509-200508-I/en

[X9.24-1] ANSI, X9.24 - Retail Financial Services Symmetric Key Management - Part 1: Using Symmetric Techniques, 2004.

[X9.31] ANSI, X9.31:Digital Signatures Using Reversible Public Key Cryptography for the Financial Services Industry (rDSA), Sep 1998.

[X9.42] ANSI, X9-42: Public Key Cryptography for the Financial Services Industry: Agreement of Symmetric Keys Using Discrete Logarithm Cryptography, 2003.

[X9-57] ANSI, X9-57: Public Key Cryptography for the Financial Services Industry: Certificate Management, 1997.

[X9.62] ANSI, X9-62: Public Key Cryptography for the Financial Services Industry, The Elliptic Curve Digital Signature Algorithm (ECDSA), 2005.

[X9-63] ANSI, X9-63: Public Key Cryptography for the Financial Services Industry, Key Agreement and Key Transport Using Elliptic Curve Cryptography, 2001.

[X9-102] ANSI, X9-102: Symmetric Key Cryptography for the Financial Services Industry - Wrapping of Keys and Associated Data, 2008.

[X9 TR-31] ANSI, X9 TR-31: Interoperable Secure Key Exchange Key Block Specification for Symmetric Algorithms, 2005.

1.3 Non-normative References

[KMIP-UG] OASIS Committee Draft 09, Key Management Interoperability Protocol Usage Guide Version 1.0, Mar 2010, http://docs.oasis-open.org/kmip/ug/v1.0/cd09/kmip-ug-1.0-cd-09.doc

[KMIP-UC] OASIS Committee Draft 09, Key Management Interoperability Protocol Use Cases Version 1.0, Mar 2010, http://docs.oasis-open.org/kmip/usecases/v1.0/cd09/kmip-usecases-1.0-cd-09.doc

[ISO/IEC 9945-2] The Open Group, Regular Expressions, The Single UNIX Specification version 2, 1997, ISO/IEC 9945-2:1993, http://www.opengroup.org/onlinepubs/007908799/xbd/re.html

2 Objects

The following subsections describe the objects that are passed between the clients and servers of the key management system. Some of these object types, called Base Objects, are used only in the protocol itself, and are not considered Managed Objects. Key management systems MAY choose to support a subset of the Managed Objects. The object descriptions refer to the primitive data types of which they are composed. These primitive data types are

· Integer

· Long Integer

· Big Integer

· Enumeration – choices from a predefined list of values

· Boolean

· Text String – string of characters representing human-readable text

· Byte String – sequence of unencoded byte values

· Date-Time – date and time, with a granularity of one second

· Interval – a length of time expressed in seconds

Structures are composed of ordered lists of primitive data types or sub-structures.

2.1 Base Objects

These objects are used within the messages of the protocol, but are not objects managed by the key management system. They are components of Managed Objects.

2.1.1 Attribute

An Attribute object is a structure (see Table 2) used for sending and receiving Managed Object attributes. The Attribute Name is a text-string that is used to identify the attribute. The Attribute Index is an index number assigned by the key management server when a specified named attribute is allowed to have multiple instances. The Attribute Index is used to identify the particular instance. Attribute Indices SHALL start with 0. The Attribute Index of an attribute SHALL NOT change when other instances are added or deleted. For example, if a particular attribute has 4 instances with Attribute Indices 0, 1, 2 and 3, and the instance with Attribute Index 2 is deleted, then the Attribute Index of instance 3 is not changed. Attributes that have a single instance have an Attribute Index of 0, which is assumed if the Attribute Index is not specified. The Attribute Value is either a primitive data type or structured object, depending on the attribute.

Object	Encoding	REQUIRED
Attribute	Structure
Attribute Name	Text String	Yes
Attribute Index	Integer	No
Attribute Value	Varies, depending on attribute. See Section 3	Yes, except for the Notify operation (see Section 5.1)

Table 2: Attribute Object Structure

2.1.2 Credential

A Credential is a structure (see Table 3) used for client identification purposes and is not managed by the key management system (e.g., user id/password pairs, Kerberos tokens, etc). It MAY be used for authentication purposes as indicated in [KMIP-Prof].

Object	Encoding	REQUIRED
Credential	Structure
Credential Type	Enumeration, see 9.1.3.2.1	Yes
Credential Value	Varies. Structure for Username and Password Credential Type.	Yes

Table 3: Credential Object Structure

If the Credential Type in the Credential is Username and Password, then Credential Value is a structure as shown in Table 4. The Username field identifies the client, and the Password field is a secret that authenticates the client.

Object	Encoding	REQUIRED
Credential Value	Structure
Username	Text String	Yes
Password	Text String	No

Table 4: Credential Value Structure for the Username and Password Credential

2.1.3 Key Block

A Key Block object is a structure (see Table 5) used to encapsulate all of the information that is closely associated with a cryptographic key. It contains a Key Value of one of the following Key Format Types:

· Raw – This is a key that contains only cryptographic key material, encoded as a string of bytes.

· Opaque – This is an encoded key for which the encoding is unknown to the key management system. It is encoded as a string of bytes.

· PKCS1 – This is an encoded private key, expressed as a DER-encoded ASN.1 PKCS#1 object.

· PKCS8 – This is an encoded private key, expressed as a DER-encoded ASN.1 PKCS#8 object, supporting both the RSAPrivateKey syntax and EncryptedPrivateKey.

· X.509 – This is an encoded object, expressed as a DER-encoded ASN.1 X.509 object.

· ECPrivateKey – This is an ASN.1 encoded elliptic curve private key.

· Several Transparent Key types – These are algorithm-specific structures containing defined values for the various key types, as defined in Section 2.1.7

· Extensions – These are vendor-specific extensions to allow for proprietary or legacy key formats.

The Key Block MAY contain the Key Compression Type, which indicates the format of the elliptic curve public key. By default, the public key is uncompressed.

The Key Block also has the Cryptographic Algorithm and the Cryptographic Length of the key contained in the Key Value field. Some example values are:

· RSA keys are typically 1024, 2048 or 3072 bits in length

· 3DES keys are typically 168 bits in length

· AES keys are typically 128 or 256 bits in length

The Key Block SHALL contain a Key Wrapping Data structure if the key in the Key Value field is wrapped (i.e., encrypted, or MACed/signed, or both).

Object	Encoding	REQUIRED
Key Block	Structure
Key Format Type	Enumeration, see 9.1.3.2.3	Yes
Key Compression Type	Enumeration, see 9.1.3.2.2	No
Key Value	Byte String: for wrapped Key Value; Structure: for plaintext Key Value, see 2.1.4	Yes
Cryptographic Algorithm	Enumeration, see 9.1.3.2.12	Yes, MAY be omitted only if this information is available from the Key Value. Does not apply to Secret Data or Opaque Objects. If present, the Cryptographic Length SHALL also be present.
Cryptographic Length	Integer	Yes, MAY be omitted only if this information is available from the Key Value. Does not apply to Secret Data or Opaque Objects. If present, the Cryptographic Algorithm SHALL also be present.
Key Wrapping Data	Structure, see 2.1.5	No, SHALL only be present if the key is wrapped.

Table 5: Key Block Object Structure

2.1.4 Key Value

The Key Value is used only inside a Key Block and is either a Byte String or a structure (see Table 6):

· The Key Value structure contains the key material, either as a byte string or as a Transparent Key structure (see Section 2.1.7), and OPTIONAL attribute information that is associated and encapsulated with the key material. This attribute information differs from the attributes associated with Managed Objects, and which is obtained via the Get Attributes operation, only by the fact that it is encapsulated with (and possibly wrapped with) the key material itself.

· The Key Value Byte String is the wrapped TTLV-encoded (see Section 9.1) Key Value structure.

Object	Encoding	REQUIRED
Key Value	Structure
Key Material	Byte String: for Raw, Opaque, PKCS1, PKCS8, ECPrivateKey, or Extension Key Format types; Structure: for Transparent, or Extension Key Format Types	Yes
Attribute	Attribute Object, see Section 2.1.1	No. MAY be repeated

Table 6: Key Value Object Structure

2.1.5 Key Wrapping Data

The Key Block MAY also supply OPTIONAL information about a cryptographic key wrapping mechanism used to wrap the Key Value. This consists of a Key Wrapping Data structure (see Table 7). It is only used inside a Key Block.

This structure contains fields for:

· A Wrapping Method, which indicates the method used to wrap the Key Value.

· Encryption Key Information, which contains the Unique Identifier (see 3.1) value of the encryption key and associated cryptographic parameters.

· MAC/Signature Key Information, which contains the Unique Identifier value of the MAC/signature key and associated cryptographic parameters.

· A MAC/Signature, which contains a MAC or signature of the Key Value.

· An IV/Counter/Nonce, if REQUIRED by the wrapping method.

If wrapping is used, then the whole Key Value structure is wrapped unless otherwise specified by the Wrapping Method. The algorithms used for wrapping are given by the Cryptographic Algorithm attributes of the encryption key and/or MAC/signature key; the block-cipher mode, padding method, and hashing algorithm used for wrapping are given by the Cryptographic Parameters in the Encryption Key Information and/or MAC/Signature Key Information, or, if not present, from the Cryptographic Parameters attribute of the respective key(s). At least one of the Encryption Key Information and the MAC/Signature Key Information SHALL be specified.

The following wrapping methods are currently defined:

· Encrypt only (i.e., encryption using a symmetric key or public key, or authenticated encryption algorithms that use a single key)

· MAC/sign only (i.e., either MACing the Key Value with a symmetric key, or signing the Key Value with a private key)

· Encrypt then MAC/sign

· MAC/sign then encrypt

· TR-31

· Extensions

Object	Encoding	REQUIRED
Key Wrapping Data	Structure
Wrapping Method	Enumeration, see 9.1.3.2.4	Yes
Encryption Key Information	Structure, see below	No. Corresponds to the key that was used to encrypt the Key Value.
MAC/Signature Key Information	Structure, see below	No. Corresponds to the symmetric key used to MAC the Key Value or the private key used to sign the Key Value
MAC/Signature	Byte String	No
IV/Counter/Nonce	Byte String	No

Table 7: Key Wrapping Data Object Structure

The structures of the Encryption Key Information (see Table 8) and the MAC/Signature Key Information (see Table 9) are as follows:

Object	Encoding	REQUIRED
Encryption Key Information	Structure
Unique Identifier	Text string, see 3.1	Yes
Cryptographic Parameters	Structure, see 3.6	No

Table 8: Encryption Key Information Object Structure

Object	Encoding	REQUIRED
MAC/Signature Key Information	Structure
Unique Identifier	Text string, see 3.1	Yes. It SHALL be either the Unique Identifier of the Symmetric Key used to MAC, or of the Private Key (or its corresponding Public Key) used to sign.
Cryptographic Parameters	Structure, see 3.6	No

Table 9: MAC/Signature Key Information Object Structure

2.1.6 Key Wrapping Specification

This is a separate structure (see Table 10) that is defined for operations that provide the option to return wrapped keys. The Key Wrapping Specification SHALL be included inside the operation request if clients request the server to return a wrapped key. If Cryptographic Parameters are specified in the Encryption Key Information and/or the MAC/Signature Key Information of the Key Wrapping Specification, then the server SHALL verify that they match one of the instances of the Cryptographic Parameters attribute of the corresponding key. If Cryptographic Parameters are omitted, then the server SHALL use the Cryptographic Parameters attribute with the lowest Attribute Index of the corresponding key. If the corresponding key does not have any Cryptographic Parameters attribute, or if no match is found, then an error is returned.

This structure contains:

· A Wrapping Method that indicates the method used to wrap the Key Value.

· Encryption Key Information with the Unique Identifier value of the encryption key and associated cryptographic parameters.

· MAC/Signature Key Information with the Unique Identifier value of the MAC/signature key and associated cryptographic parameters.

· Zero or more Attribute Names to indicate the attributes to be wrapped with the key material.

Object	Encoding	REQUIRED
Key Wrapping Specification	Structure
Wrapping Method	Enumeration, see 9.1.3.2.4	Yes
Encryption Key Information	Structure, see 2.1.5	No, SHALL be present if MAC/Signature Key Information is omitted
MAC/Signature Key Information	Structure, see 2.1.5	No, SHALL be present if Encryption Key Information is omitted
Attribute Name	Text String	No, MAY be repeated

Table 10: Key Wrapping Specification Object Structure

2.1.7 Transparent Key Structures

Transparent Key structures describe the necessary parameters to obtain the key material. They are used in the Key Value structure. The mapping to the parameters specified in other standards is shown in Table 11.

Object	Description	Mapping
P	For DSA and DH, the (large) prime field order. For RSA, a prime factor of the modulus.	p in [FIPS186-3], [X9.42], [SP800-56A] p in [PKCS#1], [SP800-56B]
Q	For DSA and DH, the (small) prime multiplicative subgroup order. For RSA, a prime factor of the modulus.	q in [FIPS186-3], [X9.42], [SP800-56A] q in [PKCS#1], [SP800-56B]
G	The generator of the subgroup of order Q.	g in [FIPS186-3], [X9.42], [SP800-56A]
X	DSA or DH private key.	x in [FIPS186-3] x, x_u,x_v in [X9.42], [SP800-56A] for static private keys r, r_u,r_v in [X9.42], [SP800-56A] for ephemeral private keys
Y	DSA or DH public key.	y in [FIPS186-3] y, y_u,y_v in [X9.42], [SP800-56A] for static public keys t, t_u,t_v in [X9.42], [SP800-56A] for ephemeral public keys
J	DH cofactor integer, where P = JQ + 1.	j in [X9.42]
Modulus	RSA modulus PQ, where P and Q are distinct primes.	n in [PKCS#1], [SP800-56B]
Private Exponent	RSA private exponent.	d in [PKCS#1], [SP800-56B]
Public Exponent	RSA public exponent.	e in [PKCS#1], [SP800-56B]
Prime Exponent P	RSA private exponent for the prime factor P in the CRT format, i.e., Private Exponent (mod (P-1)).	dP in [PKCS#1], [SP800-56B]
Prime Exponent Q	RSA private exponent for the prime factor Q in the CRT format, i.e., Private Exponent (mod (Q-1)).	dQ in [PKCS#1], [SP800-56B]
CRT Coefficient	The (first) CRT coefficient, i.e., Q^-1 mod P.	qInv in [PKCS#1], [SP800-56B]
Recommended Curve	NIST Recommended Curves (e.g., P-192).	See Appendix D of [FIPS186-3]
D	Elliptic curve private key.	d; d_e,U,d_e,V(ephemeral private keys); d_s,U,d_s,V (static private keys) in [X9-63], [SP800-56A]
Q String	Elliptic curve public key.	Q; Q_e,U,Q_e,V (ephemeral public keys); Q_s,U,Q_s,V(static public keys) in [X9-63], [SP800-56A]

Table 11: Parameter mapping.

2.1.7.1 Transparent Symmetric Key

If the Key Format Type in the Key Block is Transparent Symmetric Key, then Key Material is a structure as shown in Table 12.

Object	Encoding	REQUIRED
Key Material	Structure
Key	Byte String	Yes

Table 12: Key Material Object Structure for Transparent Symmetric Keys

2.1.7.2 Transparent DSA Private Key

If the Key Format Type in the Key Block is Transparent DSA Private Key, then Key Material is a structure as shown in Table 13.

Object	Encoding	REQUIRED
Key Material	Structure
P	Big Integer	Yes
Q	Big Integer	Yes
G	Big Integer	Yes
X	Big Integer	Yes

Table 13: Key Material Object Structure for Transparent DSA Private Keys

2.1.7.3 Transparent DSA Public Key

If the Key Format Type in the Key Block is Transparent DSA Public Key, then Key Material is a structure as shown in Table 14.

Object	Encoding	REQUIRED
Key Material	Structure
P	Big Integer	Yes
Q	Big Integer	Yes
G	Big Integer	Yes
Y	Big Integer	Yes

Table 14: Key Material Object Structure for Transparent DSA Public Keys

2.1.7.4 Transparent RSA Private Key

If the Key Format Type in the Key Block is Transparent RSA Private Key, then Key Material is a structure as shown in Table 15.

Object	Encoding	REQUIRED
Key Material	Structure
Modulus	Big Integer	Yes
Private Exponent	Big Integer	No
Public Exponent	Big Integer	No
P	Big Integer	No
Q	Big Integer	No
Prime Exponent P	Big Integer	No
Prime Exponent Q	Big Integer	No
CRT Coefficient	Big Integer	No

Table 15: Key Material Object Structure for Transparent RSA Private Keys

One of the following SHALL be present (refer to [PKCS#1]):

· Private Exponent

· P and Q (the first two prime factors of Modulus)

· Prime Exponent P and Prime Exponent Q.

2.1.7.5 Transparent RSA Public Key

If the Key Format Type in the Key Block is Transparent RSA Public Key, then Key Material is a structure as shown in Table 16.

Object	Encoding	REQUIRED
Key Material	Structure
Modulus	Big Integer	Yes
Public Exponent	Big Integer	Yes

Table 16: Key Material Object Structure for Transparent RSA Public Keys

2.1.7.6 Transparent DH Private Key

If the Key Format Type in the Key Block is Transparent DH Private Key, then Key Material is a structure as shown in Table 17.

Object	Encoding	REQUIRED
Key Material	Structure
P	Big Integer	Yes
Q	Big Integer	No
G	Big Integer	Yes
J	Big Integer	No
X	Big Integer	Yes

Table 17: Key Material Object Structure for Transparent DH Private Keys

2.1.7.7 Transparent DH Public Key

If the Key Format Type in the Key Block is Transparent DH Public Key, then Key Material is a structure as shown in Table 18.

Object	Encoding	REQUIRED
Key Material	Structure
P	Big Integer	Yes
Q	Big Integer	No
G	Big Integer	Yes
J	Big Integer	No
Y	Big Integer	Yes

Table 18: Key Material Object Structure for Transparent DH Public Keys

2.1.7.8 Transparent ECDSA Private Key

If the Key Format Type in the Key Block is Transparent ECDSA Private Key, then Key Material is a structure as shown in Table 19.

Object	Encoding	REQUIRED
Key Material	Structure
Recommended Curve	Enumeration, see 9.1.3.2.5	Yes
D	Big Integer	Yes

Table 19: Key Material Object Structure for Transparent ECDSA Private Keys

2.1.7.9 Transparent ECDSA Public Key

If the Key Format Type in the Key Block is Transparent ECDSA Public Key, then Key Material is a structure as shown in Table 20.

Object	Encoding	REQUIRED
Key Material	Structure
Recommended Curve	Enumeration, see 9.1.3.2.5	Yes
Q String	Byte String	Yes

Table 20: Key Material Object Structure for Transparent ECDSA Public Keys

2.1.7.10 Transparent ECDH Private Key

If the Key Format Type in the Key Block is Transparent ECDH Private Key, then Key Material is a structure as shown in Table 21.

Object	Encoding	REQUIRED
Key Material	Structure
Recommended Curve	Enumeration, see 9.1.3.2.5	Yes
D	Big Integer	Yes

Table 21: Key Material Object Structure for Transparent ECDH Private Keys

2.1.7.11 Transparent ECDH Public Key

If the Key Format Type in the Key Block is Transparent ECDH Public Key, then Key Material is a structure as shown in Table 22.

Object	Encoding	REQUIRED
Key Material	Structure
Recommended Curve	Enumeration, see 9.1.3.2.5	Yes
Q String	Byte String	Yes

Table 22: Key Material Object Structure for Transparent ECDH Public Keys

2.1.7.12 Transparent ECMQV Private Key

If the Key Format Type in the Key Block is Transparent ECMQV Private Key, then Key Material is a structure as shown in Table 23.

Object	Encoding	REQUIRED
Key Material	Structure
Recommended Curve	Enumeration, see 9.1.3.2.5	Yes
D	Big Integer	Yes

Table 23: Key Material Object Structure for Transparent ECMQV Private Keys

2.1.7.13 Transparent ECMQV Public Key

If the Key Format Type in the Key Block is Transparent ECMQV Public Key, then Key Material is a structure as shown in Table 24.

Object	Encoding	REQUIRED
Key Material	Structure
Recommended Curve	Enumeration, see 9.1.3.2.5	Yes
Q String	Byte String	Yes

Table 24: Key Material Object Structure for Transparent ECMQV Public Keys

2.1.8 Template-Attribute Structures

These structures are used in various operations to provide the desired attribute values and/or template names in the request and to return the actual attribute values in the response.

The Template-Attribute, Common Template-Attribute, Private Key Template-Attribute, and Public Key Template-Attribute structures are defined identically as follows:

Object	Encoding	REQUIRED
Template-Attribute, Common Template-Attribute, Private Key Template-Attribute, Public Key Template-Attribute	Structure
Name	Structure, see 3.2	No, MAY be repeated.
Attribute	Attribute Object, see 2.1.1	No, MAY be repeated

Table 25: Template-Attribute Object Structure

Name is the Name attribute of the Template object defined in Section 2.2.6.

2.2 Managed Objects

Managed Objects are objects that are the subjects of key management operations, which are described in Sections 4and 5. Managed Cryptographic Objects are the subset of Managed Objects that contain cryptographic material (e.g. certificates, keys, and secret data).

2.2.1 Certificate

A Managed Cryptographic Object that is a digital certificate (e.g., an encoded X.509 certificate).

Object	Encoding	REQUIRED
Certificate	Structure
Certificate Type	Enumeration, see 9.1.3.2.6	Yes
Certificate Value	Byte String	Yes

Table 26: Certificate Object Structure

2.2.2 Symmetric Key

A Managed Cryptographic Object that is a symmetric key.

Object	Encoding	REQUIRED
Symmetric Key	Structure
Key Block	Structure, see 2.1.3	Yes

Table 27: Symmetric Key Object Structure

2.2.3 Public Key

A Managed Cryptographic Object that is the public portion of an asymmetric key pair. This is only a public key, not a certificate.

Object	Encoding	REQUIRED
Public Key	Structure
Key Block	Structure, see 2.1.3	Yes

Table 28: Public Key Object Structure

2.2.4 Private Key

A Managed Cryptographic Object that is the private portion of an asymmetric key pair.

Object	Encoding	REQUIRED
Private Key	Structure
Key Block	Structure, see 2.1.3	Yes

Table 29: Private Key Object Structure

2.2.5 Split Key

A Managed Cryptographic Object that is a Split Key. A split key is a secret, usually a symmetric key or a private key that has been split into a number of parts, each of which MAY then be distributed to several key holders, for additional security. The Split Key Parts field indicates the total number of parts, and the Split Key Threshold field indicates the minimum number of parts needed to reconstruct the entire key. The Key Part Identifier indicates which key part is contained in the cryptographic object, and SHALL be at least 1 and SHALL be less than or equal to Split Key Parts.

Object	Encoding	REQUIRED
Split Key	Structure
Split Key Parts	Integer	Yes
Key Part Identifier	Integer	Yes
Split Key Threshold	Integer	Yes
Split Key Method	Enumeration, see 9.1.3.2.7	Yes
Prime Field Size	Big Integer	No, REQUIRED only if Split Key Method is Polynomial Sharing Prime Field.