Key Management Interoperability Protocol Specification Version 2.0

Committee Specification 01

12 June 2019

This version:

https://docs.oasis-open.org/kmip/kmip-spec/v2.0/cs01/kmip-spec-v2.0-cs01.docx (Authoritative)

https://docs.oasis-open.org/kmip/kmip-spec/v2.0/cs01/kmip-spec-v2.0-cs01.html

https://docs.oasis-open.org/kmip/kmip-spec/v2.0/cs01/kmip-spec-v2.0-cs01.pdf

Previous version:

https://docs.oasis-open.org/kmip/kmip-spec/v2.0/csd01/kmip-spec-v2.0-csd01.docx (Authoritative)

https://docs.oasis-open.org/kmip/kmip-spec/v2.0/csd01/kmip-spec-v2.0-csd01.html

https://docs.oasis-open.org/kmip/kmip-spec/v2.0/csd01/kmip-spec-v2.0-csd01.pdf

Latest version:

https://docs.oasis-open.org/kmip/kmip-spec/v2.0/kmip-spec-v2.0.docx (Authoritative)

https://docs.oasis-open.org/kmip/kmip-spec/v2.0/kmip-spec-v2.0.html

https://docs.oasis-open.org/kmip/kmip-spec/v2.0/kmip-spec-v2.0.pdf

Technical Committee:

OASIS Key Management Interoperability Protocol (KMIP) TC

Chairs:

Tony Cox (tony.cox@cryptsoft.com), Cryptsoft Pty Ltd.

Judith Furlong (Judith.Furlong@dell.com), Dell

Editors:

Tony Cox (tony.cox@cryptsoft.com), Cryptsoft Pty Ltd.

Charles White (chuck@fornetix.com), Fornetix

Related work:

This specification replaces or supersedes:

·         Key Management Interoperability Protocol Specification Version 1.4. Edited by Tony Cox. OASIS Standard. Latest version: http://docs.oasis-open.org/kmip/spec/v1.4/kmip-spec-v1.4.html.

This specification is related to:

·         Key Management Interoperability Protocol Profiles Version 2.0. Edited by Tim Hudson and Robert Lockhart. Latest version: https://docs.oasis-open.org/kmip/kmip-profiles/v2.0/kmip-profiles-v2.0.html.

·         Key Management Interoperability Protocol Test Cases Version 2.0. Edited by Tim Hudson and Mark Joseph. Latest version: https://docs.oasis-open.org/kmip/kmip-testcases/v2.0/kmip-testcases-v2.0.html.

·         Key Management Interoperability Protocol Usage Guide Version 2.0. Edited by Judith Furlong. Latest version: https://docs.oasis-open.org/kmip/kmip-ug/v2.0/kmip-ug-v2.0.html.

Abstract:

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 OASIS Key Management Interoperability Protocol (KMIP) TC on the above date. The level of approval is also listed above. Check the “Latest version” location noted above for possible later revisions of this document. Any other numbered Versions and other technical work produced by the Technical Committee (TC) are listed at https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=kmip#technical.

TC members should send comments on this specification to the TC’s email list. Others should send comments to the TC’s public comment list, after subscribing to it by following the instructions at the “Send A Comment” button on the TC’s web page at https://www.oasis-open.org/committees/kmip/.

This specification is provided under the RF on RAND Terms Mode of the OASIS IPR Policy, the mode chosen when the Technical Committee was established. 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 TC’s web page (https://www.oasis-open.org/committees/kmip/ipr.php).

Note that any machine-readable content (Computer Language Definitions) declared Normative for this Work Product is provided in separate plain text files. In the event of a discrepancy between any such plain text file and display content in the Work Product's prose narrative document(s), the content in the separate plain text file prevails.

Citation format:

When referencing this specification the following citation format should be used:

[kmip-spec-v2.0]

Key Management Interoperability Protocol Specification Version 2.0. Edited by Tony Cox and Charles White. 12 June 2019. OASIS Committee Specification 01. https://docs.oasis-open.org/kmip/kmip-spec/v2.0/cs01/kmip-spec-v2.0-cs01.html. Latest version: https://docs.oasis-open.org/kmip/kmip-spec/v2.0/kmip-spec-v2.0.html.

Notices

Copyright © OASIS Open 2019. All Rights Reserved.

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 name "OASIS" is a trademark 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 https://www.oasis-open.org/policies-guidelines/trademark for above guidance.

Table of Contents

1        Introduction. 11

1.1 IPR Policy. 11

1.2 Terminology. 11

1.3 Normative References. 14

1.4 Non-Normative References. 17

1.5 Item Data Types. 17

2        Objects. 18

2.1 Certificate. 18

2.2 Certificate Request 18

2.3 Opaque Object 18

2.4 PGP Key. 18

2.5 Private Key. 19

2.6 Public Key. 19

2.7 Secret Data. 19

2.8 Split Key. 19

2.9 Symmetric Key. 20

3        Object Data Structures. 21

3.1 Key Block. 21

3.2 Key Value. 22

3.3 Key Wrapping Data. 22

3.4 Transparent Symmetric Key. 23

3.5 Transparent DSA Private Key. 24

3.6 Transparent DSA Public Key. 24

3.7 Transparent RSA Private Key. 24

3.8 Transparent RSA Public Key. 25

3.9 Transparent DH Private Key. 25

3.10 Transparent DH Public Key. 25

3.11 Transparent EC Private Key. 25

3.12 Transparent EC Public Key. 26

4        Object Attributes. 27

4.1 Activation Date. 28

4.2 Alternative Name. 29

4.3 Always Sensitive. 29

4.4 Application Specific Information. 30

4.5 Archive Date. 31

4.6 Certificate Attributes. 31

4.7 Certificate Type. 32

4.8 Certificate Length. 33

4.9 Comment 33

4.10 Compromise Date. 33

4.11 Compromise Occurrence Date. 34

4.12 Contact Information. 34

4.13 Cryptographic Algorithm.. 35

4.14 Cryptographic Domain Parameters. 35

4.15 Cryptographic Length. 36

4.16 Cryptographic Parameters. 37

4.17 Cryptographic Usage Mask. 39

4.18 Deactivation Date. 39

4.19 Description. 40

4.20 Destroy Date. 40

4.21 Digest 41

4.22 Digital Signature Algorithm.. 42

4.23 Extractable. 42

4.24 Fresh. 43

4.25 Initial Date. 43

4.26 Key Format Type. 44

4.27 Key Value Location. 45

4.28 Key Value Present 45

4.29 Last Change Date. 46

4.30 Lease Time. 46

4.31 Link. 47

4.32 Name. 48

4.33 Never Extractable. 49

4.34 NIST Key Type. 49

4.35 Object Group. 50

4.36 Object Type. 50

4.37 Opaque Data Type. 51

4.38 Original Creation Date. 51

4.39 PKCS#12 Friendly Name. 52

4.40 Process Start Date. 52

4.41 Protect Stop Date. 53

4.42 Protection Level 54

4.43 Protection Period. 54

4.44 Protection Storage Mask. 54

4.45 Quantum Safe. 55

4.46 Random Number Generator 55

4.47 Revocation Reason. 56

4.48 Sensitive. 57

4.49 Short Unique Identifier 57

4.50 State. 58

4.51 Unique Identifier 60

4.52 Usage Limits. 61

4.53 Vendor Attribute. 62

4.54 X.509 Certificate Identifier 62

4.55 X.509 Certificate Issuer 63

4.56 X.509 Certificate Subject 64

5        Attribute Data Structures. 65

5.1 Attributes. 65

5.2 Common Attributes. 65

5.3 Private Key Attributes. 65

5.4 Public Key Attributes. 65

5.5 Attribute Reference. 66

5.6 Current Attribute. 66

5.7 New Attribute. 66

6        Operations. 67

6.1 Client-to-Server Operations. 67

6.1.1 Activate. 68

6.1.2 Add Attribute. 68

6.1.3 Adjust Attribute. 69

6.1.4 Archive. 70

6.1.5 Cancel 71

6.1.6 Certify. 71

6.1.7 Check. 73

6.1.8 Create. 75

6.1.9 Create Key Pair 75

6.1.10 Create Split Key. 77

6.1.11 Decrypt 78

6.1.12 Delegated Login. 80

6.1.13 Delete Attribute. 81

6.1.14 Derive Key. 82

6.1.15 Destroy. 83

6.1.16 Discover Versions. 84

6.1.17 Encrypt 85

6.1.18 Export 87

6.1.19 Get 88

6.1.20 Get Attributes. 89

6.1.21 Get Attribute List 90

6.1.22 Get Usage Allocation. 91

6.1.23 Hash. 92

6.1.24 Import 93

6.1.25 Interop. 94

6.1.26 Join Split Key. 95

6.1.27 Locate. 96

6.1.28 Log. 98

6.1.29 Login. 99

6.1.30 Logout 99

6.1.31 MAC. 100

6.1.32 MAC Verify. 102

6.1.33 Modify Attribute. 104

6.1.34 Obtain Lease. 105

6.1.35 PKCS#11. 106

6.1.36 Poll 107

6.1.37 Query. 107

6.1.38 Recover 110

6.1.39 Register 111

6.1.40 Revoke. 112

6.1.41 Re-certify. 113

6.1.42 Re-key. 116

6.1.43 Re-key Key Pair 117

6.1.44 Re-Provision. 120

6.1.45 RNG Retrieve. 121

6.1.46 RNG Seed. 121

6.1.47 Set Attribute. 122

6.1.48 Set Endpoint Role. 123

6.1.49 Sign. 124

6.1.50 Signature Verify. 126

6.1.51 Validate. 128

6.2 Server-to-Client Operations. 129

6.2.1 Discover Versions. 129

6.2.2 Notify. 130

6.2.3 Put 131

6.2.4 Query. 132

6.2.5 Set Endpoint Role. 134

7        Operations Data Structures. 135

7.1 Authenticated Encryption Additional Data. 135

7.2 Authenticated Encryption Tag. 135

7.3 Capability Information. 135

7.4 Correlation Value. 136

7.5 Data. 136

7.6 Data Length. 136

7.7 Defaults Information. 136

7.8 Derivation Parameters. 137

7.9 Extension Information. 138

7.10 Final Indicator 138

7.11 Interop Function. 138

7.12 Interop Identifier 138

7.13 Init Indicator 139

7.14 Key Wrapping Specification. 139

7.15 Log Message. 139

7.16 MAC Data. 140

7.17 Objects. 140

7.18 Object Defaults. 140

7.19 Operations. 140

7.20 PKCS#11 Function. 140

7.21 PKCS#11 Input Parameters. 141

7.22 PKCS#11 Interface. 141

7.23 PKCS#11 Output Parameters. 141

7.24 PKCS#11 Return Code. 141

7.25 Profile Information. 142

7.26 Profile Version. 142

7.27 Protection Storage Masks. 142

7.28 Right 142

7.29 Rights. 143

7.30 RNG Parameters. 143

7.31 Server Information. 144

7.32 Signature Data. 144

7.33 Ticket 144

7.34 Usage Limits. 144

7.35 Validation Information. 145

8        Messages. 146

8.1 Request Message. 146

8.2 Request Header 146

8.3 Request Batch Item.. 147

8.4 Response Message. 147

8.5 Response Header 147

8.6 Response Batch Item.. 148

9        Message Data Structures. 149

9.1 Asynchronous Correlation Value. 149

9.2 Asynchronous Indicator 149

9.3 Attestation Capable Indicator 149

9.4 Authentication. 149

9.5 Batch Count 150

9.6 Batch Error Continuation Option. 150

9.7 Batch Item.. 150

9.8 Batch Order Option. 150

9.9 Correlation Value (Client) 150

9.10 Correlation Value (Server) 151

9.11 Credential 151

9.12 Maximum Response Size. 153

9.13 Message Extension. 153

9.14 Nonce. 154

9.15 Operation. 154

9.16 Protocol Version. 154

9.17 Result Message. 154

9.18 Result Reason. 155

9.19 Result Status. 155

9.20 Time Stamp. 155

9.21 Unique Batch Item ID. 155

10      Message Protocols. 157

10.1 TTLV. 157

10.1.1 Tag. 157

10.1.2 Type. 157

10.1.3 Length. 158

10.1.4 Value. 158

10.1.5 Padding. 158

10.2 Other Message Protocols. 158

10.2.1 HTTPS. 158

10.2.2 JSON. 159

10.2.3 XML. 159

10.3 Authentication. 159

10.4 Transport 159

11      Enumerations. 160

11.1 Adjustment Type Enumeration. 160

11.2 Alternative Name Type Enumeration. 160

11.3 Asynchronous Indicator Enumeration. 161

11.4 Attestation Type Enumeration. 161

11.5 Batch Error Continuation Option Enumeration. 161

11.6 Block Cipher Mode Enumeration. 162

11.7 Cancellation Result Enumeration. 163

11.8 Certificate Request Type Enumeration. 163

11.9 Certificate Type Enumeration. 164

11.10 Client Registration Method Enumeration. 164

11.11 Credential Type Enumeration. 165

11.12 Cryptographic Algorithm Enumeration. 165

11.13 Data Enumeration. 167

11.14 Derivation Method Enumeration. 167

11.15 Destroy Action Enumeration. 169

11.16 Digital Signature Algorithm Enumeration. 169

11.17 DRBG Algorithm Enumeration. 170

11.18 Encoding Option Enumeration. 170

11.19 Endpoint Role Enumeration. 170

11.20 FIPS186 Variation Enumeration. 171

11.21 Hashing Algorithm Enumeration. 171

11.22 Interop Function Enumeration. 172

11.23 Item Type Enumeration. 172

11.24 Key Compression Type Enumeration. 173

11.25 Key Format Type Enumeration. 173

11.26 Key Role Type Enumeration. 175

11.27 Key Value Location Type Enumeration. 175

11.28 Link Type Enumeration. 176

11.29 Key Wrap Type Enumeration. 177

11.30 Mask Generator Enumeration. 177

11.31 Name Type Enumeration. 177

11.32 NIST Key Type Enumeration. 178

11.33 Object Group Member Enumeration. 179

11.34 Object Type Enumeration. 179

11.35 Opaque Data Type Enumeration. 179

11.36 Operation Enumeration. 179

11.37 Padding Method Enumeration. 181

11.38 PKCS#11 Function Enumeration. 181

11.39 PKCS#11 Return Code Enumeration. 181

11.40 Profile Name Enumeration. 182

11.41 Protection Level Enumeration. 183

11.42 Put Function Enumeration. 183

11.43 Query Function Enumeration. 183

11.44 Recommended Curve Enumeration. 184

11.45 Result Reason Enumeration. 186

11.46 Result Status Enumeration. 191

11.47 Revocation Reason Code Enumeration. 191

11.48 RNG Algorithm Enumeration. 192

11.49 RNG Mode Enumeration. 192

11.50 Secret Data Type Enumeration. 192

11.51 Shredding Algorithm Enumeration. 193

11.52 Split Key Method Enumeration. 193

11.53 State Enumeration. 193

11.54 Tag Enumeration. 193

11.55 Ticket Type Enumeration. 204

11.56 Unique Identifier Enumeration. 204

11.57 Unwrap Mode Enumeration. 205

11.58 Usage Limits Unit Enumeration. 205

11.59 Validity Indicator Enumeration. 206

11.60 Wrapping Method Enumeration. 206

11.61 Validation Authority Type Enumeration. 207

11.62 Validation Type Enumeration. 207

12      Bit Masks. 208

12.1 Cryptographic Usage Mask. 208

12.2 Protection Storage Mask. 210

12.3 Storage Status Mask. 210

13      Algorithm Implementation. 211

13.1 Split Key Algorithms. 211

14      KMIP Client and Server Implementation Conformance. 212

14.1 KMIP Client Implementation Conformance. 212

14.2 KMIP Server Implementation Conformance. 212

Appendix A. Acknowledgments. 213

Appendix B. Acronyms. 215

Appendix C. List of Figures and Tables. 218

Appendix D. Revision History. 229

 

 


1      Introduction

This document is intended as a specification of the protocol used for the communication (request and response messages) 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 and digital certificates . 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.

This specification is complemented by several other documents. The KMIP Usage Guide [KMIP-UG] provides illustrative information on using the protocol. The KMIP Profiles Specification [KMIP-Prof] provides a normative set of base level conformance profiles and authentication suites that include the specific tests used to test conformance with the applicable KMIP normative documents. The KMIP Test Cases [KMIP-TC] provides samples of protocol messages corresponding to a set of defined test cases that are also used in conformance testing.

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

1.1 IPR Policy

This specification is provided under the RF on RAND Terms Mode of the OASIS IPR Policy, the mode chosen when the Technical Committee was established. 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 TC’s web page (https://www.oasis-open.org/committees/kmip/ipr.php).

1.2 Terminology

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].

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

Term

Definition

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.

Authorization

Access privileges that are granted to an entity; conveying an “official” sanction to perform a security function or activity.

Certificate length

The length (in bytes) of an X.509 public key certificate.

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, and

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 hashing algorithm 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.

Digital Signature Algorithm

A cryptographic algorithm used for digital signature.

Encryption

The process of changing plaintext into ciphertext using a cryptographic algorithm and key.

Hashing algorithm (or hash algorithm, hash function)

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.

Message Authentication Code (MAC)

A cryptographic checksum on data that uses a symmetric key to detect both accidental and intentional modifications of data.

PGP Key

A RFC 4880-compliant container of cryptographic keys and associated metadata.  Usually text-based (in PGP-parlance, ASCII-armored).

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 can 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 Key

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 necessary 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 inverse (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.3 Normative References

[AWS-SIGV4]          Authenticating Requests (AWS Signature Version 4) https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating- requests.htm

[CHACHA]               D. J. Bernstein. ChaCha, a variant of Salsa20. https://cr.yp.to/chacha/chacha-20080128.pdf

[ECC-Brainpool]     ECC Brainpool Standard Curves and Curve Generation v. 1.0.19.10.2005, http://www.ecc-brainpool.org/download/Domain-parameters.pdf.

[FIPS180-4]             Secure Hash Standard (SHS), FIPS PUB 186-4, March 2012, http://csrc.nist.gov/publications/fips/fips18-4/fips-180-4.pdf.

[FIPS186-4]             Digital Signature Standard (DSS), FIPS PUB 186-4, July 2013, http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf.

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

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

[FIPS202]               SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions, August 2015. http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.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, 2012.

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

[KMIP-Prof]            Key Management Interoperability Protocol Profiles Version 2.0. Edited by Tim Hudson and Robert Lockhart. Latest version: https://docs.oasis-open.org/kmip/kmip-profiles/v2.0/kmip-profiles-v2.0.html.

[PKCS#1]                RSA Laboratories, PKCS #1 v2.1: RSA Cryptography Standard, June 14, 2002, http://www.preserveitall.org/emc-plus/rsa-labs/standards-initiatives/pkcs-rsa-cryptography-standard.htm.

[PKCS#5]                RSA Laboratories, PKCS #5 v2.1: Password-Based Cryptography Standard, October 5, 2006, http://www.preserveitall.org/emc-plus/rsa-labs/standards-initiatives/pkcs-5-password-based-cryptography-standard.htm.

[PKCS#8]                RSA Laboratories, PKCS#8 v1.2: Private-Key Information Syntax Standard, November 1, 1993, http://www.preserveitall.org/emc-plus/rsa-labs/standards-initiatives/pkcs-8-private-key-information-syntax-stand.htm.

[PKCS#10]              RSA Laboratories, PKCS #10 v1.7: Certification Request Syntax Standard, May 26, 2000, http://www.preserveitall.org/emc-plus/rsa-labs/standards-initiatives/pkcs10-certification-request-syntax-standard.htm.

[PKCS#11]              OASIS PKCS#11 Cryptographic Token Interface Base Specification Version 3.0

[POLY1305]            Daniel J. Bernstein. The Poly1305-AES Message-Authentication Code. In Henri Gilbert and Helena Handschuh, editors, Fast Software Encryption: 12th International Workshop, FSE 2005, Paris, France, February 21-23, 2005, Revised Selected Papers, volume 3557 of Lecture Notes in Computer Science, pages 32–49. Springer, 2005.

[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, April 1992, http://www.ietf.org/rfc/rfc1320.txt.

[RFC1321]               R. Rivest, The MD5 Message-Digest Algorithm, IETF RFC 1321, April 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, February 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, February 1997, http://www.ietf.org/rfc/rfc2104.txt.

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

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

[RFC2986]               M. Nystrom and B. Kaliski, PKCS #10:  Certification Request Syntax Specification Version 1.7, IETF RFC2986, November 2000, http://www.rfc-editor.org/rfc/rfc2986.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, November 2003, http://www.ietf.org/rfc/rfc3629.txt.

[RFC3686]               R. Housley, Using Advanced Encryption Standard (AES) Counter Mode with IPsec Encapsulating Security Payload (ESP), IETF RFC 3686, January 2004, http://www.ietf.org/rfc/rfc3686.txt.

[RFC4210]               C. Adams, S. Farrell, T. Kause and T. Mononen, Internet X.509 Public Key Infrastructure Certificate Management Protocol (CMP), IETF RFC 4210, September 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, September 2005, http://www.ietf.org/rfc/rfc4211.txt.

[RFC4880]               J. Callas, L. Donnerhacke, H. Finney, D. Shaw, and R. Thayer, OpenPGP Message Format, IETF RFC 4880, November 2007, http://www.ietf.org/rfc/rfc4880.txt.

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

[RFC5272]               J. Schaad and M. Meyers, Certificate Management over CMS (CMC), IETF RFC 5272, June 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.

[RFC5639]               M. Lochter, J. Merkle, Elliptic Curve Cryptography (ECC) Brainpool Standard Curves and Curve Generation, IETF RFC 5639, March 2010, http://www.ietf.org/rfc/rfc5639.txt.

[RFC5869]               H. Krawczyk, HMAC-based Extract-and-Expand Key Derivation Function (HKDF), IETF RFC5869, May 2010, https://tools.ietf.org/html/rfc5869

[RFC5958]               S. Turner, Asymmetric Key Packages, IETF RFC5958, August 2010, https://tools.ietf.org/rfc/rfc5958.txt

 [RFC6402]              J. Schaad, Certificate Management over CMS (CMC) Updates, IETF RFC6402, November 2011, http://www.rfc-editor.org/rfc/rfc6402.txt.

[RFC6818]               P. Yee, Updates to the Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile, IETF RFC6818, January 2013, http://www.rfc-editor.org/rfc/rfc6818.txt.

[RFC7778]               A. Langley, M. Hamburg, S. Turner Elliptic Curves for Security, IETF RFC7748, January 2016, https://tools.ietf.org/html/rfc7748

[SEC2]                    SEC 2: Recommended Elliptic Curve Domain Parameters, http://www.secg.org/SEC2-Ver-1.0.pdf.

[SP800-38A]            M. Dworkin, Recommendation for Block Cipher Modes of Operation – Methods and Techniques, NIST Special Publication 800-38A, December 2001, http://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-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://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-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, updated July 2007 http://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38c.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://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-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, January 2010, http://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38e.pdf.

[SP800-56A]            E. Barker, L. Chen, A. Roginsky and M. Smid, Recommendation for Pair-Wise Key Establishment Schemes Using Discrete Logarithm Cryptography, NIST Special Publication 800-56A Revision 2, May 2013, http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar2.pdf.

[SP800-57-1]           E. Barker, W. Barker, W. Burr, W. Polk, and M. Smid, Recommendations for Key Management - Part 1: General (Revision 3), NIST Special Publication 800-57 Part 1 Revision 3, July 2012, http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57_part1_rev3_general.pdf.

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

[X.509]                    International Telecommunication Union (ITU)–T, X.509:  Information technology – Open systems interconnection – The Directory:  Public-key and attribute certificate frameworks, November 2008, http://www.itu.int/rec/recommendation.asp?lang=en&parent=T-REC-X.509-200811-1.

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

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

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

[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, 2011.

[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, 2010.

1.4 Non-Normative References

[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.

[KMIP-UG]              Key Management Interoperability Protocol Usage Guide Version 2.0. Work in progress.

[KMIP-TC]               Key Management Interoperability Protocol Test Cases Version 2.0. Edited by Tim Hudson and Mark Joseph. Latest version: https://docs.oasis-open.org/kmip/kmip-testcases/v2.0/kmip-testcases-v2.0.html.

[RFC6151]               S. Turner and L. Chen, Updated Security Considerations for the MD5 Message-Digest and the HMAC-MD5 Algorithms, IETF RFC6151, March 2011, http://www.rfc-editor.org/rfc/rfc6151.txt.

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

[RFC7292]               K. Moriarty, M. Nystrom, S. Parkinson, A. Rusch, M. Scott. PKCS #12: Personal Information Exchange Syntax v1.1, July 2014, https://tools.ietf.org/html/rfc7292

1.5 Item Data Types

The following are the data types of which all items (Objects, Attributes and Messages) are composed of Integer, Long Integer, Big Integer, Enumeration, Boolean, Text String, Byte String, Date Time, Interval, Date Time Extended, and Structure.

2      Objects

Managed Objects are objects that are the subjects of key management operations. Managed Cryptographic Objects are the subset of Managed Objects that contain cryptographic material.

2.1 Certificate

A Managed Cryptographic Object that is a digital certificate. It is a DER-encoded X.509 public key certificate.

Object

Encoding

REQUIRED

Certificate

Structure

 

Certificate Type

Enumeration

Yes

Certificate Value

Byte String

Yes

Table 2: Certificate Object Structure

2.2 Certificate Request

A Managed Cryptographic Object containing the Certificate Request.

Object

Encoding

REQUIRED

Certificate Request

Structure

 

Certificate Request Type

Enumeration

Yes

Certificate Request Value

Byte String

Yes

Table 3: Certificate Request Structure

2.3 Opaque Object

A Managed Object that the key management server is possibly not able to interpret. The context information for this object MAY be stored and retrieved using Custom Attributes.

An Opaque Object MAY be a Managed Cryptographic Object depending on the client context of usage and as such is treated in the same manner as a Managed Cryptographic Object for handling of attributes.

Object

Encoding

REQUIRED

Opaque Object

Structure

 

Opaque Data Type

Enumeration

Yes

Opaque Data Value

Byte String

Yes

Table 4: Opaque Object Structure

2.4 PGP Key

A Managed Cryptographic Object that is a text-based representation of a PGP key. The Key Block field, indicated below, will contain the ASCII-armored export of a PGP key in the format as specified in RFC 4880. It MAY contain only a public key block, or both a public and private key block. Two different versions of PGP keys, version 3 and version 4, MAY be stored in this Managed Cryptographic Object.

KMIP implementers SHOULD treat the Key Block field as an opaque blob. PGP-aware KMIP clients SHOULD take on the responsibility of decomposing the Key Block into other Managed Cryptographic Objects (Public Keys, Private Keys, etc.).

Object

Encoding

REQUIRED

PGP Key

Structure

 

PGP Key Version

Integer

Yes

Key Block

Object Data Structure

Yes

Table 5: PGP Key Object Structure

2.5 Private Key

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

Object

Encoding

REQUIRED

Private Key

Structure

 

Key Block

Object Data Structure

Yes

Table 6: Private Key Object Structure

2.6 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

Object Data Structure

Yes

Table 7: Public Key Object Structure

2.7 Secret Data

A Managed Cryptographic Object containing a shared secret value that is not a key or certificate (e.g., a password). The Key Block of the Secret Data object contains a Key Value of the Secret Data Type. The Key Value MAY be wrapped.

Object

Encoding

REQUIRED

Secret Data

Structure

 

Secret Data Type

Enumeration

Yes

Key Block

Object Data Structure

Yes

Table 8: Secret Data Object Structure

2.8 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

Yes

Prime Field Size

Big Integer

No, REQUIRED only if Split Key Method is Polynomial Sharing Prime Field.

Key Block

Object Data Structure

Yes

Table 9: Split Key Object Structure

2.9 Symmetric Key

A Managed Cryptographic Object that is a symmetric key.

Object

Encoding

REQUIRED

Symmetric Key

Structure

 

Key Block

Structure

Yes

Table 10: Symmetric Key Object Structure

3      Object Data Structures

3.1 Key Block

A Key Block object is a structure used to encapsulate all of the information that is closely associated with a cryptographic key.

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:

Value

Description

RSA keys

Typically 1024, 2048 or 3072 bits in length.

3DES keys

Typically from 112 to 192 bits (depending upon key length and the presence of parity bits).

AES keys

128, 192 or 256 bits in length

Table 11: Key Block Cryptographic Algorithm & Length Description

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

Yes

Key Compression Type

Enumeration

No

Key Value

Byte String: for wrapped Key Value; Structure: for plaintext Key Value

No

Cryptographic Algorithm

Enumeration

Yes. MAY be omitted only if this information is available from the Key Value. Does not apply to Secret Data  or Opaque 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. If present, the Cryptographic Algorithm SHALL also be present.

Key Wrapping Data

Object Data Structure

No. SHALL only be present if the key is wrapped.

Table 12: Key Block Object Structure

3.2 Key Value

The Key Value is used only inside a Key Block and is either a Byte String or a:

·         The Key Value structure contains the key material, either as a byte string or as a Transparent Key structure, 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 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 either the wrapped TTLV-encoded Key Value structure, or the wrapped un-encoded value of the Byte String Key Material field.

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

Attributes

Structure

No

Table 13: Key Value Object Structure

3.3 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. It is only used inside a Key Block.

This structure contains fields for:

Value

Description

Wrapping Method

Indicates the method used to wrap the Key Value.

Encryption Key Information

Contains the Unique Identifier value of the encryption key and associated cryptographic parameters.

MAC/Signature Key Information

Contains the Unique Identifier value of the MAC/signature key and associated cryptographic parameters.

MAC/Signature

Contains a MAC or signature of the Key Value

IV/Counter/Nonce

If REQUIRED by the wrapping method.

Encoding Option

Specifies the encoding of the Key Material within the Key Value structure of the Key Block that has been wrapped. If No Encoding is specified, then the Key Value structure SHALL NOT contain any attributes.

Table 14: Key Wrapping Data Structure Description

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). Either the Encryption Key Information or the MAC/Signature Key Information (or both) in the Key Wrapping Data structure SHALL be specified.

Object

Encoding

REQUIRED

Key Wrapping Data

Structure

 

Wrapping Method

Enumeration

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

Encoding Option

Enumeration

No. Specifies the encoding of the Key Value Byte String. If not present, the wrapped Key Value structure SHALL be TTLV encoded.

Table 15: Key Wrapping Data Object Structure

The structures of the Encryption Key Information  and the MAC/Signature Key Information  are as follows:

Object

Encoding

REQUIRED

Encryption Key Information

Structure

 

Unique Identifier

Text string

Yes

Cryptographic Parameters

Structure

No

Table 16: Encryption Key Information Object Structure

Object

Encoding

REQUIRED

MAC/Signature Key Information

Structure

 

Unique Identifier

Text string

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

No

Table 17: MAC/Signature Key Information Object Structure

3.4 Transparent Symmetric Key

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

Object

Encoding

REQUIRED

Key Material

Structure

 

Key

Byte String

Yes

Table 18: Key Material Object Structure for Transparent Symmetric Keys

3.5 Transparent DSA Private Key

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

Object

Encoding

REQUIRED

Key Material

Structure

 

P

Big Integer

Yes

Q

Big Integer

Yes

G

Big Integer

Yes

X

Big Integer

Yes

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

3.6 Transparent DSA Public Key

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

Object

Encoding

REQUIRED

Key Material

Structure

 

P

Big Integer

Yes

Q

Big Integer

Yes

G

Big Integer

Yes

Y

Big Integer

Yes

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

3.7 Transparent RSA Private Key

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

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 21: 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), or

·         Prime Exponent P and Prime Exponent Q.

3.8 Transparent RSA Public Key

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

Object

Encoding

REQUIRED

Key Material

Structure

 

Modulus

Big Integer

Yes

Public Exponent

Big Integer

Yes

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

3.9 Transparent DH Private Key

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

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 23: Key Material Object Structure for Transparent DH Private Keys

3.10 Transparent DH Public Key

If the Key Format Type in the Key Block is Transparent DH Public Key, then Key Material is a.

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 24: Key Material Object Structure for Transparent DH Public Keys

3.11 Transparent EC Private Key

If the Key Format Type in the Key Block is Transparent EC Private Key, then Key Material is a structure.

Object

Encoding

REQUIRED

Key Material

Structure

 

Recommended Curve

Enumeration

Yes

D

Big Integer

Yes

Table 25: Key Material Object Structure for Transparent EC Private Keys

3.12 Transparent EC Public Key

If the Key Format Type in the Key Block is Transparent EC Public Key, then Key Material is a structure.

Object

Encoding

REQUIRED

Key Material

Structure

 

Recommended Curve

Enumeration

Yes

Q String

Byte String

Yes

Table 26: Key Material Object Structure for Transparent EC Public Keys

 

4      Object Attributes  

The following subsections describe the attributes that are associated with Managed Objects. Attributes that an object MAY have multiple instances of are referred to as multi-instance attributes. All instances of an attribute SHOULD have a different value. Similarly, attributes which an object SHALL only have at most one instance of are referred to as single-instance attributes. Attributes are able to be obtained by a client from the server using the Get Attribute operation. Some attributes are able to be set by the Add Attribute operation or updated by the Modify Attribute operation, and some are able to be deleted by the Delete Attribute operation if they no longer apply to the Managed Object. Read-only attributes are attributes that SHALL NOT be modified by either server or client, and that SHALL NOT be deleted by a client.

When attributes are returned by the server (e.g., via a Get Attributes operation), the attribute value returned SHALL NOT differ for different clients unless specifically noted against each attribute.

The first table in each subsection contains the attribute name in the first row. This name is the canonical name used when managing attributes using the Get Attributes, Get Attribute List, Add Attribute, Modify Attribute, and Delete Attribute operations.

A server SHALL NOT delete attributes without receiving a request from a client until the object is destroyed. After an object is destroyed, the server MAY retain all, some or none of the object attributes, depending on the object type and server policy.

The second table in each subsection lists certain attribute characteristics (e.g., “SHALL always have a value. The server policy MAY further restrict these attribute characteristics.

SHALL always have a value

All Managed Objects that are of the Object Types for which this attribute applies, SHALL always have this attribute set once the object has been created or registered, up until the object has been destroyed.

Initially set by

Who is permitted to initially set the value of the attribute (if the attribute has never been set, or if all the attribute values have been deleted)?

Modifiable by server

Is the server allowed to change an existing value of the attribute without receiving a request from a client?

Modifiable by client

Is the client able to change an existing value of the attribute value once it has been set?

Deletable by client

Is the client able to delete an instance of the attribute?

Multiple instances permitted

Are multiple instances of the attribute permitted?

When implicitly set

Which operations MAY cause this attribute to be set even if the attribute is not specified in the operation request itself?

Applies to Object Types

Which Managed Objects MAY have this attribute set?

Table 27: Attribute Rules

There are default values for some mandatory attributes of Cryptographic Objects. The values in use by a particular server are available via Query. KMIP servers SHALL supply values for these attributes if the client omits them.

Object

Attribute

Symmetric Key

Cryptographic Algorithm

Cryptographic Length

Cryptographic Usage Mask

Private Key

Cryptographic Algorithm

Cryptographic Length

Cryptographic Usage Mask

Public Key

Cryptographic Algorithm

Cryptographic Length

Cryptographic Usage Mask

Certificate

Cryptographic Algorithm

Cryptographic Length

Digital Signature Algorithm

Split Key

Cryptographic Algorithm

Cryptographic Length

Cryptographic Usage Mask

Secret Data

Cryptographic Usage Mask

Table 28: Default Cryptographic Parameters

4.1 Activation Date

The Activation Date attribute contains the date and time when the Managed Object MAY begin to be used. This time corresponds to state transition. The object SHALL NOT be used for any cryptographic purpose before the Activation Date has been reached. Once the state transition from Pre-Active has occurred, then this attribute SHALL NOT be changed or deleted before the object is destroyed.

Item

Encoding

Activation Date

Date-Time

Table 29: Activation Date Attribute

SHALL always have a value

No

Initially set by

Server or Client

Modifiable by server

Yes, only while in Pre-Active state

Modifiable by client

Yes, only while in Pre-Active state

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Create, Create Key Pair, Register, Derive Key, Activate Certify, Re-certify, Re-key, Re-key Key Pair

Applies to Object Types

All Objects

Table 30: Activation Date Attribute Rules

4.2 Alternative Name

The Alternative Name attribute is used to identify and locate the object. This attribute is assigned by the client, and the Alternative Name Value is intended to be in a form that humans are able to interpret. The key management system MAY specify rules by which the client creates valid alternative names. Clients are informed of such rules by a mechanism that is not specified by this standard. Alternative Names MAY NOT be unique within a given key management domain.

Item

Encoding

REQUIRED

Alternative Name

Structure

 

Alternative Name Value

Text String

Yes

Alternative Name Type

Enumeration

Yes

Table 31: Alternative Name Attribute Structure

SHALL always have a value

No

Initially set by

Client

Modifiable by server

Yes (Only if no value present)

Modifiable by client

Yes

Deletable by client

Yes

Multiple instances permitted

Yes

Applies to Object Types

All Objects

Table 32: Alternative Name Attribute Rules

4.3 Always Sensitive

The server SHALL create this attribute, and set it to True if the Sensitive attribute has always been True. The server SHALL set it to False if the Sensitive attribute has ever been set to False.

Item

Encoding

Sensitive

Boolean

Table 33: Always Sensitive Attribute

SHALL always have a value

Yes

Initially set by

Server

Modifiable by server

Yes

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

When implicitly set

When Sensitive attribute is set or changed

Applies to Object Types

All Objects

Table 34: Always Sensitive Attribute Rules

4.4 Application Specific Information

The Application Specific Information attribute is a structure used to store data specific to the application(s) using the Managed Object. It consists of the following fields: an Application Namespace and Application Data specific to that application namespace.

Clients MAY request to set (i.e., using any of the operations that result in new Managed Object(s) on the server or adding/modifying the attribute of an existing Managed Object an instance of this attribute with a particular Application Namespace while omitting Application Data. In that case, if the server supports this namespace (as indicated by the Query operation), then it SHALL return a suitable Application Data value. If the server does not support this namespace, then an error SHALL be returned.

 

Item

Encoding

REQUIRED

Application Specific Information

Structure

 

Application Namespace

Text String

Yes

Application Data

Text String

No

Table 35: Application Specific Information Attribute

 

SHALL always have a value

No

Initially set by

Client or Server (only if the Application Data is omitted, in the client request)

Modifiable by server

Yes (only if the Application Data is omitted in the client request)

Modifiable by client

Yes

Deletable by client

Yes

Multiple instances permitted

Yes

When implicitly set

Re-key, Re-key Key Pair, Re-certify

Applies to Object Types

All Objects

Table 36: Application Specific Information Attribute Rules

4.5 Archive Date

The Archive Date attribute is the date and time when the Managed Object was placed in archival storage. This value is set by the server as a part of the Archive operation. The server SHALL delete this attribute whenever a Recover operation is performed.

Item

Encoding

Archive Date

Date-Time

Table 37: Archive Date Attribute

SHALL always have a value

No

Initially set by

Server

Modifiable by server

No

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Archive

Applies to Object Types

All Objects

Table 38: Archive Date Attribute Rules

4.6 Certificate Attributes

The Certificate Attributes are the various items included in a certificate. The following list is based on RFC2253.

Item

Encoding

Certificate Subject CN

Text String

Certificate Subject O

Text String

Certificate Subject OU

Text String

Certificate Subject Email

Text String

Certificate Subject C

Text String

Certificate Subject ST

Text String

Certificate Subject L

Text String

Certificate Subject UID

Text String

Certificate Subject Serial Number

Text String

Certificate Subject Title

Text String

Certificate Subject DC

Text String

Certificate Subject DN Qualifier

Text String

Certificate Issuer CN

Text String

Certificate Issuer O

Text String

Certificate Issuer OU

Text String

Certificate Issuer Email

Text String

Certificate Issuer C

Text String

Certificate Issuer ST

Text String

Certificate Issuer L

Text String

Certificate Issuer UID

Text String

Certificate Issuer Serial Number

Text String

Certificate Issuer Title

Text String

Certificate Issuer DC

Text String

Certificate Issuer DN Qualifier

Text String

Table 39: Certificate Attributes

 

SHALL always have a value

No

Initially set by

Server

Modifiable by server

No

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

Yes

When implicitly set

Register, Certify, Re-certify

Applies to Object Types

Certificates

Table 40: Certificate Attribute Rules

4.7 Certificate Type

The Certificate Type attribute is a type of certificate (e.g., X.509).

The Certificate Type value SHALL be set by the server when the certificate is created or registered and then SHALL NOT be changed or deleted before the object is destroyed.

Item

Encoding

 

Certificate Type

Enumeration

 

Table 41: Certificate Type Attribute

SHALL always have a value

Yes

Initially set by

Server

Modifiable by server

No

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Register, Certify, Re-certify

Applies to Object Types

Certificates

Table 42: Certificate Type Attribute Rules

4.8 Certificate Length

The Certificate Length attribute is the length in bytes of the Certificate object. The Certificate Length SHALL be set by the server when the object is created or registered, and then SHALL NOT be changed or deleted before the object is destroyed.

Item

Encoding

Certificate Length

Integer

Table 43: Certificate Length Attribute

SHALL always have a value

Yes

Initially set by

Server

Modifiable by server

No

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Register, Certify, Re-certify

Applies to Object Types

Certificates

Table 44: Certificate Length Attribute Rules

4.9 Comment

The Comment attribute is used for descriptive purposes only. It is not used for policy enforcement. The attribute is set by the client or the server.

 

Item

Encoding

Description

Text String

Table 45: Comment Attribute

SHALL always have a value

No

Initially set by

Client or Server

Modifiable by server

Yes

Modifiable by client

Yes

Deletable by client

Yes

Multiple instances permitted

No

Applies to Object Types

All Objects

Table 46: Comment Rules

4.10 Compromise Date

The Compromise Date attribute contains the date and time when the Managed Cryptographic Object entered into the compromised state. This time corresponds to state transitions 3, 5, 8, or 10. This time indicates when the key management system was made aware of the compromise, not necessarily when the compromise occurred. This attribute is set by the server when it receives a Revoke operation with a Revocation Reason containing a Revocation Reason Code of Compromised code, or due to server policy or out-of-band administrative action.

Item

Encoding

Compromise Date

Date-Time

Table 47: Compromise Date Attribute

SHALL always have a value

No

Initially set by

Server

Modifiable by server

No

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Revoke

Applies to Object Types

All Objects

Table 48: Compromise Date Attribute Rules

4.11 Compromise Occurrence Date

The Compromise Occurrence Date attribute is the date and time when the Managed Object was first believed to be compromised. If it is not possible to estimate when the compromise occurred, then this value SHOULD be set to the Initial Date for the object.

Item

Encoding

Compromise Occurrence Date

Date-Time

Table 49: Compromise Occurrence Date Attribute

SHALL always have a value

No

Initially set by

Server

Modifiable by server

No

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Revoke

Applies to Object Types

All Objects

Table 50: Compromise Occurrence Date Attribute Rules

4.12 Contact Information

The Contact Information attribute is used for descriptive purposes only. It is not used for policy enforcement. The attribute is set by the client or the server.

Item

Encoding

Contact Information

Text String

Table 51: Contact Information Attribute

SHALL always have a value

No

Initially set by

Client or Server

Modifiable by server

Yes

Modifiable by client

Yes

Deletable by client

Yes

Multiple instances permitted

No

When implicitly set

Create, Create Key Pair, Register, Derive Key, Certify, Re-certify, Re-key, Re-key Key Pair

Applies to Object Types

All Objects

Table 52: Contact Information Attribute Rules

4.13 Cryptographic Algorithm

The Cryptographic Algorithm of an object. The Cryptographic Algorithm of a Certificate object identifies the algorithm for the public key contained within the Certificate. The digital signature algorithm used to sign the Certificate is identified in the Digital Signature Algorithm attribute. This attribute SHALL be set by the server when the object is created or registered and then SHALL NOT be changed or deleted before the object is destroyed.

Item

Encoding

Cryptographic Algorithm

Enumeration

Table 53: Cryptographic Algorithm Attribute

SHALL always have a value

Yes (except for Secret Data and Opaque Object)

Initially set by

Server

Modifiable by server

No

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Certify, Create, Create Key Pair, Re-certify, Register, Derive Key, Re-key, Re-key Key Pair

Applies to Object Types

All Objects

Table 54: Cryptographic Algorithm Attribute Rules

4.14 Cryptographic Domain Parameters

The Cryptographic Domain Parameters attribute is a structure that contains fields that MAY need to be specified in the Create Key Pair Request Payload. Specific fields MAY only pertain to certain types of Managed Cryptographic Objects.

The domain parameter Qlength correponds to the bit length of parameter Q (refer to [RFC7778], [SEC2] and [SP800-56A]).

Qlength applies to algorithms such as DSA and DH. The bit length of parameter P (refer to to [RFC7778], [SEC2] and [SP800-56A]) is specified separately by setting the Cryptographic Length attribute.

Recommended Curve is applicable to elliptic curve algorithms such as ECDSA, ECDH, and ECMQV.

Item

Encoding

Required

Cryptographic Domain Parameters

Structure

Yes

Qlength

Integer

No

Recommended Curve

Enumeration

No

Table 55: Cryptographic Domain Parameters Attribute Structure

 

Shall always have a value

No

Initially set by

Client

Modifiable by server

No

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Re-key, Re-key Key Pair

Applies to Object Types

Public Keys, Private Keys

Table 56: Cryptographic Domain Parameters Attribute Rules

4.15 Cryptographic Length

For keys, Cryptographic Length is the length in bits of the clear-text cryptographic key material of the Managed Cryptographic Object. For certificates, Cryptographic Length is the length in bits of the public key contained within the Certificate. This attribute SHALL be set by the server when the object is created or registered, and then SHALL NOT be changed or deleted before the object is destroyed.

Item

Encoding

Cryptographic Length

Integer

Table 57: Cryptographic Length Attribute

SHALL always have a value

Yes (Except for Opaque Object)

Initially set by

Server

Modifiable by server

No

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Certify, Create, Create Key Pair, Re-certify, Register, Derive Key, Re-key, Re-key Key Pair

Applies to Object Types

All Objects

Table 58: Cryptographic Length Attribute Rules

4.16 Cryptographic Parameters

The Cryptographic Parameters attribute is a structure that contains a set of OPTIONAL fields that describe certain cryptographic parameters to be used when performing cryptographic operations using the object. Specific fields MAY pertain only to certain types of Managed Objects. The Cryptographic Parameters attribute of a Certificate object identifies the cryptographic parameters of the public key contained within the Certificate.

The Cryptographic Algorithm is also used to specify the parameters for cryptographic operations. For operations involving digital signatures, either the Digital Signature Algorithm can be specified or the Cryptographic Algorithm and Hashing Algorithm combination can be specified.

Random IV can be used to request that the KMIP server generate an appropriate IV for a cryptographic operation that uses an IV. The generated Random IV is returned in the response to the cryptographic operation.

IV Length is the length of the Initialization Vector in bits. This parameter SHALL be provided when the specified Block Cipher Mode supports variable IV lengths such as CTR or GCM.

Tag Length is the length of the authenticator tag in bytes. This parameter SHALL be provided when the Block Cipher Mode is GCM.

The IV used with counter modes of operation (e.g., CTR and GCM) cannot repeat for a given cryptographic key. To prevent an IV/key reuse, the IV is often constructed of three parts: a fixed field, an invocation field, and a counter as described in [SP800-38A] and [SP800-38D]. The Fixed Field Length is the length of the fixed field portion of the IV in bits. The Invocation Field Length is the length of the invocation field portion of the IV in bits. The Counter Length is the length of the counter portion of the IV in bits.

Initial Counter Value is the starting counter value for CTR mode (for [RFC3686] it is 1).

Item

Encoding

REQUIRED

Cryptographic Parameters

Structure

 

Block Cipher Mode

Enumeration

No

Padding Method

Enumeration

No

Hashing Algorithm

Enumeration

No

Key Role Type

Enumeration

No

Digital Signature Algorithm

Enumeration

No

Cryptographic Algorithm

Enumeration

No

Random IV

Boolean

No

IV Length

Integer

No unless Block Cipher Mode supports variable IV lengths

Tag Length

Integer

No unless Block Cipher Mode is GCM

Fixed Field Length

Integer

No

Invocation Field Length

Integer

No

Counter Length

Integer

No

Initial Counter Value

Integer

No

Salt Length

Integer

No (if omitted, defaults to the block size of the Mask Generator Hashing Algorithm)

Mask Generator

Enumeration

No (if omitted defaults to MGF1).

Mask Generator Hashing Algorithm

Enumeration

No. (if omitted defaults to SHA-1).

P Source

Byte String

No (if omitted, defaults to an empty byte string for encoding input P in OAEP padding)

Trailer Field

Integer

No (if omitted, defaults to the standard one-byte trailer in PSS padding)

Table 59: Cryptographic Parameters Attribute Structure

 

SHALL always have a value

No

Initially set by

Client

Modifiable by server

No

Modifiable by client

Yes

Deletable by client

Yes

Multiple instances permitted

Yes

When implicitly set

Re-key, Re-key Key Pair, Re-certify

Applies to Object Types

All Objects

Table 60: Cryptographic Parameters Attribute Rules

4.17 Cryptographic Usage Mask

The Cryptographic Usage Mask attribute defines the cryptographic usage of a key. This is a bit mask that indicates to the client which cryptographic functions MAY be performed using the key, and which ones SHALL NOT be performed.

 

Item

Encoding

Cryptographic Usage Mask

Integer

Table 61: Cryptographic Usage Mask Attribute

SHALL always have a value

Yes (Except for Opaque Object)

Initially set by

Server or Client

Modifiable by server

Yes

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Create, Create Key Pair, Register, Derive Key, Certify, Re-certify, Re-key, Re-key Key Pair

Applies to Object Types

All Objects

Table 62: Cryptographic Usage Mask Attribute Rules

4.18 Deactivation Date

The Deactivation Date attribute is the date and time when the Managed Object SHALL NOT be used for any purpose, except for decryption, signature verification, or unwrapping, but only under extraordinary circumstances and only when special permission is granted. This time corresponds to state transition 6. This attribute SHALL NOT be changed or deleted before the object is destroyed, unless the object is in the Pre-Active or Active state.

Item

Encoding

Deactivation Date

Date-Time

Table 63: Deactivation Date Attribute

SHALL always have a value

No

Initially set by

Server or Client

Modifiable by server

Yes, only while in Pre-Active or Active state

Modifiable by client

Yes, only while in Pre-Active or Active state

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Create, Create Key Pair, Register, Derive Key, Revoke Certify, Re-certify, Re-key, Re-key Key Pair

Applies to Object Types

All Objects

Table 64: Deactivation Date Attribute Rules

4.19 Description

The Description attribute is used for descriptive purposes only. It is not used for policy enforcement. The attribute is set by the client or the server. 

 

Item

Encoding

Description

Text String

Table 65: Description Attribute

SHALL always have a value

No

Initially set by

Client or Server

Modifiable by server

Yes

Modifiable by client

Yes

Deletable by client

Yes

Multiple instances permitted

No

Applies to Object Types

All Objects

Table 66: Description Attribute Rules

4.20 Destroy Date

The Destroy Date attribute is the date and time when the Managed Object was destroyed. This time corresponds to state transitions 2, 7, or 9  This value is set by the server when the object is destroyed due to the reception of a Destroy operation, or due to server policy or out-of-band administrative action.

Item

Encoding

Destroy Date

Date-Time

Table 67: Destroy Date Attribute

SHALL always have a value

No

Initially set by

Server

Modifiable by server

No

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Destroy

Applies to Object Types

All Objects

Table 68: Destroy Date Attribute Rules

4.21 Digest

The Digest attribute is a structure that contains the digest value of the key or secret data (i.e., digest of the Key Material), certificate (i.e., digest of the Certificate Value), or opaque object (i.e., digest of the Opaque Data Value). If the Key Material is a Byte String, then the Digest Value SHALL be calculated on this Byte String. If the Key Material is a structure, then the Digest Value SHALL be calculated on the TTLV-encoded Key Material structure. The Key Format Type field in the Digest attribute indicates the format of the Managed Object from which the Digest Value was calculated. Multiple digests MAY be calculated using different algorithms and/or key format types. If this attribute exists, then it SHALL have a mandatory attribute instance computed with the SHA-256 hashing algorithm and the default Key Value Format for this object type and algorithm. Clients may request via supplying a non-default Key Format Value attribute on operations that create a Managed Object, and the server SHALL produce an additional Digest attribute for that Key Value Type. The digest(s) are static and SHALL be set by the server when the object is created or registered, provided that the server has access to the Key Material or the Digest Value (possibly obtained via out-of-band mechanisms).

Item

Encoding

REQUIRED

Digest

Structure

 

Hashing Algorithm

Enumeration

Yes

Digest Value

Byte String

Yes, if the server has access to the Digest Value or the Key Material (for keys and secret data), the Certificate Value (for certificates) or the Opaque Data Value (for opaque objects).

Key Format Type

Enumeration

Yes, if the Managed Object is a key or secret data object.

Table 69: Digest Attribute Structure

SHALL always have a value

Yes, if the server has access to the Digest Value or the Key Material (for keys and secret data), the Certificate Value (for certificates) or the Opaque Data Value (for opaque objects).

Initially set by

Server

Modifiable by server

No

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

Yes

When implicitly set

Create, Create Key Pair, Register, Derive Key, Certify, Re-certify, Re-key, Re-key Key Pair

Applies to Object Types

All Objects

Table 70: Digest Attribute Rules

4.22 Digital Signature Algorithm

The Digital Signature Algorithm attribute identifies the digital signature algorithm associated with a digitally signed object (e.g., Certificate).  This attribute SHALL be set by the server when the object is created or registered and then SHALL NOT be changed or deleted before the object is destroyed.

Item

Encoding

Digital Signature Algorithm

Enumeration

Table 71: Digital Signature Algorithm Attribute

SHALL always have a value

Yes

Initially set by

Server

Modifiable by server

No

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

Yes for PGP keys. No for X.509 certificates.

When implicitly set

Certify, Re-certify, Register

Applies to Object Types

Certificates, PGP keys

Table 72: Digital Signature Algorithm Attribute Rules

4.23 Extractable

If False then the server SHALL prevent the object value being retrieved. The server SHALL set its value to True if not provided by the client.

 

Item

Encoding

Extractable

Boolean

Table 73: Extractable Attribute

SHALL always have a value

Yes

Initially set by

Client or Server

Modifiable by server

Yes

Modifiable by client

Yes

Deletable by client

No

Multiple instances permitted

No

When implicitly set

When object is created or registered

Applies to Object Types

All Objects

Table 74: Extractable Attribute Rules

4.24 Fresh

The Fresh attribute is a Boolean attribute that indicates that the object has not yet been served to a client using a Get operation. The Fresh attribute SHALL be set to True when a new object is created on the server unless the client provides a False value in Register or Import. The server SHALL change the attribute value to False as soon as the object has been served via the Get operation to a client.

Item

Encoding

Fresh

Boolean

Table 75: Fresh Attribute

SHALL always have a value

Yes

Initially set by

Client or Server

Modifiable by server

Yes

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Create, Create Key Pair, Register, Derive Key, Certify, Re-certify, Re-key, Re-key Key Pair, Re-key Key Pair

Applies to Object Types

All Objects

Table 76: Fresh Attribute Rules

4.25 Initial Date

The Initial Date attribute contains the date and time when the Managed Object was first created or registered at the server. This time corresponds to state transition 1. This attribute SHALL be set by the server when the object is created or registered, and then SHALL NOT be changed or deleted before the object is destroyed. This attribute is also set for non-cryptographic objects when they are first registered with the server.

Item

Encoding

Initial Date

Date-Time

Table 77: Initial Date Attribute

SHALL always have a value

Yes

Initially set by

Server

Modifiable by server

No

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Create, Create Key Pair, Register, Derive Key, Certify, Re-certify, Re-key, Re-key Key Pair

Applies to Object Types

All Objects

Table 78: Initial Date Attribute Rules

4.26 Key Format Type

The Key Format Type attribute is a required attribute of a Cryptographic Object. It is set by the server, but a particular Key Format Type MAY be requested by the client if the cryptographic material is produced by the server (i.e., Create, Create Key Pair, Create Split Key, Re-key, Re-key Key Pair, Derive Key) on the client’s behalf. The server SHALL comply with the client’s requested format or SHALL fail the request. When the server calculates a Digest for the object, it SHALL compute the digest on the data in the assigned Key Format Type, as well as a digest in the default KMIP Key Format Type for that type of key and the algorithm requested (if a non-default value is specified).

Object

Encoding

Key Format Type

Enumeration

Table 79: Key Format Type Attribute

SHALL always have a value

Yes

Initially set by

Server

Modifiable by server

No

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

Applies to Object Types

All Objects

Table 80: Key Format Type Attribute Rules

Keys have a default Key Format Type that SHALL be produced by KMIP servers. The default Key Format Type by object (and algorithm) is listed in the following table:

Object

Default Key Format Type

Certificate

X.509

Certificate Request

PKCS#10

Opaque Object

Opaque

PGP Key

Raw

Secret Data

Raw

Symmetric Key

Raw

Split Key

Raw

RSA Private Key

PKCS#1

RSA Public Key

PKCS#1

EC Private Key

Transparent EC Private Key

EC Public Key

Transparent EC Public Key

DSA Private Key

Transparent DSA Private Key

DSA Public Key

Transparent DSA Public Key

Table 81: Default Key Format Type, by Object

4.27 Key Value Location

Key Value Location MAY be specified by the client when the Key Value is omitted from the Key Block in a Register request. Key Value Location is used to indicate the location of the Key Value absent from the object being registered..

Object

Encoding

REQUIRED

Key Value Location

Structure

 

Key Value Location Value

Text String

Yes

Key Value Location Type

Enumeration

Yes

Table 82: Key Value Location Attribute

SHALL always have a value

No

Initially set by

Client

Modifiable by server

No

Modifiable by client

Yes

Deletable by client

Yes

Multiple instances permitted

Yes

When implicitly set

Never

Applies to Object Types

All Objects

`

4.28 Key Value Present

Key Value Present is an attribute of the managed object created by the server. It SHALL NOT be specified by the client in a Register request. Key Value Present SHALL be created by the server if the Key Value is absent from the Key Block in a Register request. The value of Key Value Present SHALL NOT be modified by either the client or the server. Key Value Present attribute MAY be used as a part of the Locate operation.

Item

Encoding

REQUIRED

Key Value Present

Boolean

 No

Table 83: Key Value Present Attribute

SHALL always have a value

No

Initially set by

Server

Modifiable by server

No

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

When implicitly set

During Register operation

Applies to Object Types

All Objects

Table 84: Key Value Present Attribute Rules

4.29 Last Change Date

The Last Change Date attribute contains the date and time of the last change of the specified object.

Item

Encoding

Last Change Date

Date-Time

Table 85: Last Change Date Attribute

SHALL always have a value

Yes

Initially set by

Server

Modifiable by server

Yes

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Create, Create Key Pair, Register, Derive Key, Activate, Revoke, Destroy, Archive, Recover, Certify, Re-certify, Re-key, Re-key Key Pair, Add Attribute, Modify Attribute, Delete Attribute, Get Usage Allocation

Applies to Object Types

All Objects

Table 86: Last Change Date Attribute Rules

4.30 Lease Time

The Lease Time attribute defines a time interval for a Managed Object beyond which the client SHALL NOT use the object without obtaining another lease. This attribute always holds the initial length of time allowed for a lease, and not the actual remaining time. Once its lease expires, the client is only able to renew the lease by calling Obtain Lease. A server SHALL store in this attribute the maximum Lease Time it is able to serve and a client obtains the lease time (with Obtain Lease) that is less than or equal to the maximum Lease Time. This attribute is read-only for clients. It SHALL be modified by the server only.

Item

Encoding

Lease Time

Interval

Table 87: Lease Time Attribute

SHALL always have a value

No

Initially set by

Server

Modifiable by server

Yes

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Create, Create Key Pair, Register, Derive Key, Certify, Re-certify, Re-key, Re-key Key Pair

Applies to Object Types

All Objects

Table 88: Lease Time Attribute Rules

4.31 Link

The Link attribute is a structure used to create a link from one Managed Cryptographic Object to another, closely related target Managed Cryptographic Object. The link has a type, and the allowed types differ, depending on the Object Type of the Managed Cryptographic Object, as listed below. The Linked Object Identifier identifies the target Managed Cryptographic Object by its Unique Identifier. The link contains information about the association between the Managed Objects (e.g., the private key corresponding to a public key; the parent certificate for a certificate in a chain; or for a derived symmetric key, the base key from which it was derived).

The Link attribute SHOULD be present for private keys and public keys for which a certificate chain is stored by the server, and for certificates in a certificate chain.

Note that it is possible for a Managed Object to have multiple instances of the Link attribute (e.g., a Private Key has links to the associated certificate, as well as the associated public key; a Certificate object has links to both the public key and to the certificate of the certification authority (CA) that signed the certificate).

It is also possible that a Managed Object does not have links to associated cryptographic objects. This MAY occur in cases where the associated key material is not available to the server or client (e.g., the registration of a CA Signer certificate with a server, where the corresponding private key is held in a different manner).

Encoding

Description

Text String

Unique Identifier of a Managed Object.

Enumeration

Unique Identifier  Enumeration

Integer

Zero based nth Unique Identifier in the response. If negative the count is backwards from the beginning of the current operation’s batch item.

Table 89: Linked Object Identifier encoding descriptions

Item

Encoding

REQUIRED

Link

Structure

 

Link Type

Enumeration

Yes

Linked Object Identifier

Text String/Enumeration/Integer

Yes

Table 90: Link Attribute Structure

SHALL always have a value

No

Initially set by

Client or Server

Modifiable by server

Yes

Modifiable by client

Yes

Deletable by client

Yes

Multiple instances permitted

Yes

When implicitly set

Create Key Pair, Derive Key, Certify, Re-certify, Re-key, Re-key Key Pair, Register

Applies to Object Types

All Objects

Table 91: Link Attribute Structure Rules

4.32 Name

The Name attribute is a structure used to identify and locate an object. This attribute is assigned by the client, and the Name Value is intended to be in a form that humans are able to interpret. The key management system MAY specify rules by which the client creates valid names. Clients are informed of such rules by a mechanism that is not specified by this standard. Names SHALL be unique within a given key management domain, but are NOT REQUIRED to be globally unique.

Item

Encoding

REQUIRED

Name

Structure

 

Name Value

Text String

Yes

Name Type

Enumeration

Yes

Table 92: Name Attribute Structure

SHALL always have a value

No

Initially set by

Client

Modifiable by server

Yes

Modifiable by client

Yes

Deletable by client

Yes

Multiple instances permitted

Yes

When implicitly set

Re-key, Re-key Key Pair, Re-certify

Applies to Object Types

All Objects

Table 93: Name Attribute Rules

4.33 Never Extractable

The server SHALL create this attribute, and set it to True if the Extractable attribute has always been False.

The server SHALL set it to False if the Extractable attribute has ever been set to True.

Item

Encoding

Never Extractable

Boolean

Table 94: Never Extractable Attribute

SHALL always have a value

Yes

Initially set by

Server

Modifiable by server

Yes

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

When implicitly set

When Never Extractable attribute is

set or changed

Applies to Object Types

All Objects

Table 95: Never Extractable Attribute Rules

4.34 NIST Key Type

The NIST SP800-57 Key Type is an attribute of a Key (or Secret Data object). It MAY be set by the client, preferably when the object is registered or created.  Although the attribute is optional, once set, MAY NOT be deleted or modified by either the client or the server.  This attribute is intended to reflect the NIST SP-800-57 view of cryptographic material, so an object SHOULD have only one usage (see [SP800-57-1] for rationale), but this is not enforced at the server.

Item

Encoding

NIST Key Type

Enumeration

Table 96 SP800-57 Key Type Attribute

SHALL always have a value

No

Initially set by

Client

Modifiable by server

No

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

Yes

Applies to Object Types

All Objects

Table 97 SP800-57 Key Type Attribute Rules

4.35 Object Group

A Managed Object MAY be part of a group of objects. An object MAY belong to more than one group of objects. To assign an object to a group of objects, the object group name SHOULD be set into this attribute.

Item

Encoding

Object Group

Text String

Table 98: Object Group Attribute

SHALL always have a value

No

Initially set by

Client or Server

Modifiable by server

Yes

Modifiable by client

Yes

Deletable by client

Yes

Multiple instances permitted

Yes

When implicitly set

Create, Create Key Pair, Register, Derive Key, Certify, Re-certify, Re-key, Re-key Key Pair

Applies to Object Types

All Objects

Table 99: Object Group Attribute Rules

4.36 Object Type

The Object Type of a Managed Object (e.g., public key, private key, symmetric key, etc.) SHALL be set by the server when the object is created or registered and then SHALL NOT be changed or deleted before the object is destroyed.

Item

Encoding

Object Type

Enumeration

Table 100: Object Type Attribute

SHALL always have a value

Yes

Initially set by

Server

Modifiable by server

No

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Create, Create Key Pair, Register, Derive Key, Certify, Re-certify, Re-key, Re-key Key Pair

Applies to Object Types

All Objects

Table 101: Object Type Attribute Rules

4.37 Opaque Data Type

The Opaque Data Type of an Opaque Object SHALL be set by the server when the object is registered and then SHALL NOT be changed or deleted before the object is destroyed.

Item

Encoding

Opaque Data Type

Enumeration

Table 102: Opaque Data Type Attribute

SHALL always have a value

Yes

Initially set by

Server

Modifiable by server

No

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Register

Applies to Object Types

Opaque Objects

Table 103: Opaque Data Type Attribute Rules

4.38 Original Creation Date

The Original Creation Date attribute contains the date and time the object was originally created, which can be different from when the object is registered with a key management server.

It is OPTIONAL for an object being registered by a client. The Original Creation Date MAY be set by the client during a Register operation. If no Original Creation Date attribute was set by the client during a Register operation, it MAY do so at a later time through an Add Attribute operation for that object.

It is mandatory for an object created on the server as a result of a Create, Create Key Pair, Derive Key, Re-key, or Re-key Key Pair operation. In such cases the Original Creation Date SHALL be set by the server and SHALL be the same as the Initial Date attribute.

In all cases, once the Original Creation Date is set, it SHALL NOT be deleted or updated.

Item

Encoding

Original Creation Date

Date-Time

Table 104: Original Creation Date Attribute

SHALL always have a value

No

Initially set by

Client or Server (when object is generated by Server)

Modifiable by server

No

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Create, Create Key Pair, Derive Key, Re-key, Re-key Key Pair

Applies to Object Types

All Objects

Table 105: Original Creation Date Attribute Rules

4.39 PKCS#12 Friendly Name

PKCS#12 Friendly Name is an attribute used for descriptive purposes. If supplied on a Register Private Key with Key Format Type PKCS#12, it informs the server of the alias/friendly name (see [RFC7292]) under which the private key and its associated certificate chain SHALL be found in the Key Material. If no such alias/friendly name is supplied, the server SHALL record the alias/friendly name (if any) it finds for the first Private Key in the Key Material.  

When a Get with Key Format Type PKCS#12 is issued, this attribute informs the server what alias/friendly name the server SHALL use when encoding the response.  If this attribute is absent for the object on which the Get is issued, the server SHOULD use an alias/friendly name of “alias”.  Since the PKCS#12 Friendly Name is defined in ASN.1 with an EQUALITY MATCHING RULE of caseIgnoreMatch, clients and servers SHOULD utilize a lowercase text string.

Item

Encoding

PKCS#12 Friendly Name

Text String

Table 106: PKCS#12 Friendly Name Attribute

SHALL always have a value

No

Initially set by

Client or Server

Modifiable by server

No

Modifiable by client

Yes

Deletable by client

Yes

Multiple instances permitted

No

Applies to Object Types

All Objects

Table 107: Friendly Name Attribute Rules

4.40 Process Start Date

The Process Start Date attribute is the date and time when a valid Managed Object MAY begin to be used to process cryptographically protected information (e.g., decryption or unwrapping), depending on the value of its Cryptographic Usage Mask attribute. The object SHALL NOT be used for these cryptographic purposes before the Process Start Date has been reached. This value MAY be equal to or later than, but SHALL NOT precede, the Activation Date. Once the Process Start Date has occurred, then this attribute SHALL NOT be changed or deleted before the object is destroyed.

Item

Encoding

Process Start Date

Date-Time

Table 108: Process Start Date Attribute

SHALL always have a value

No

Initially set by

Server or Client

Modifiable by server

Yes, only while in Pre-Active or Active state and as long as the Process Start Date has been not reached.

Modifiable by client

Yes, only while in Pre-Active or Active state and as long as the Process Start Date has been not reached.

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Create, Register, Derive Key, Re-key

Applies to Object Types

All Objects

Table 109: Process Start Date Attribute Rules

4.41 Protect Stop Date

The Protect Stop Date attribute is the date and time after which a valid Managed Object SHALL NOT be used for applying cryptographic protection (e.g., encryption or wrapping), depending on the value of its Cryptographic Usage Mask attribute. This value MAY be equal to or earlier than, but SHALL NOT be later than the Deactivation Date. Once the Protect Stop Date has occurred, then this attribute SHALL NOT be changed or deleted before the object is destroyed.

Item

Encoding

Protect Stop Date

Date-Time

Table 110: Protect Stop Date Attribute

SHALL always have a value

No

Initially set by

Server or Client

Modifiable by server

Yes, only while in Pre-Active or Active state and as long as the Protect Stop Date has not been reached.

Modifiable by client

Yes, only while in Pre-Active or Active state and as long as the Protect Stop Date has not been reached.

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Create, Register, Derive Key, Re-key

Applies to Object Types

All Objects

Table 111: Protect Stop Date Attribute Rules

4.42 Protection Level

The Protection Level attribute is the Level of protection required for a given object.

Item

Encoding

Protection Level

Enumeration

Table 112: Protection Level Attribute

SHALL always have a value

No

Initially set by

Client

Modifiable by server

No

Modifiable by client

Yes

Deletable by client

Yes

Multiple instances permitted

No

When implicitly set

 

Applies to Object Types

All Objects

Table 113: Protection Level Attribute Rules

4.43 Protection Period

The Protection Period attribute is the period of time for which the output of an operation or a Managed Cryptographic Object SHALL remain safe. The Protection Period is specified as an Interval.

Item

Encoding

Protection Period

Interval

Table 114: Protection Period Attribute

SHALL always have a value

No

Initially set by

Client

Modifiable by server

No

Modifiable by client

Yes

Deletable by client

Yes

Multiple instances permitted

No

When implicitly set

 

Applies to Object Types

All Objects

Table 115: Protection Period Attribute Rules

4.44 Protection Storage Mask

The Protection Storage Mask attribute records which of the requested mask values have been used for protection storage.

Item

Encoding

Protection Storage Mask

Integer

Table 116: Protection Storage Mask

SHALL always have a value

Yes

Initially set by

Server

Modifiable by server

No

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

When implicitly set

When object is stored

Applies to Object Types

All Objects

Table 117: Protection Storage Mask Rules

 

4.45 Quantum Safe

The Quantum Safe attribute is a flag to be set to indicate an object is required to be Quantum Safe for the given Protection Period and Protection Level.

Item

Encoding

Quantum Safe

Boolean

Table 118: Quantum Safe Attribute

SHALL always have a value

No

Initially set by

Client

Modifiable by server

No

Modifiable by client

Yes

Deletable by client

Yes

Multiple instances permitted

No

When implicitly set

 

Applies to Object Types

All Objects

Table 119: Quantum Safe Attribute Rules

4.46 Random Number Generator

The Random Number Generator attribute contains the details of the random number generator used during the creation of the managed cryptographic object.

The Random Number Generator MAY be set by the client during a Register operation. If no Random Number Generator attribute was set by the client during a Register operation, it MAY do so at a later time through an Add Attribute operation for that object.

It is mandatory for an object created on the server as a result of a Create, Create Key Pair, Derive Key, Re-key, or Re-key Key Pair operation. In such cases the Random Number Generator SHALL be set by the server depending on which random number generator was used. If the specific details of the random number generator are unknown then the RNG Algorithm within the RNG Parameters structure SHALL be set to Unspecified.

If one or more Random Number Generator attribute values are provided in the Attributes in a Create, Create Key Pair, Derive Key, Re-key, or Re-key Key Pair operation then the server SHALL use a random number generator that matches one of the Random Number Generator attributes. If the server does not support or is otherwise unable to use a matching random number generator then it SHALL fail the request.

The Random Number Generator attribute SHALL NOT be copied from the original object in a Re-key or Re-key Key Pair operation.

In all cases, once the Random Number Generator attribute is set, it SHALL NOT be deleted or updated.

Note: the encoding is the same as the RNG Parameters structure using a different tag; it does not contain a nested RNG Parameters structure.

Item

Encoding

Random Number Generator

RNG Parameters

Table 120: Random Number Generator Attribute

SHALL always have a value

No

Initially set by

Client (when the object is generated by the Client and registered) or Server (when object is generated by Server)

Modifiable by server

No

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Create, Create Key Pair, Derive Key, Re-key, Re-key Key Pair

Applies to Object Types

All Objects

Table 121: Random Number Generator Attribute Rules

4.47 Revocation Reason

The Revocation Reason attribute is a structure used to indicate why the Managed Cryptographic Object was revoked (e.g., “compromised”, “expired”, “no longer used”, etc.). This attribute is only set by the server as a part of the Revoke Operation.

The Revocation Message is an OPTIONAL field that is used exclusively for audit trail/logging purposes and MAY contain additional information about why the object was revoked (e.g., “Laptop stolen”, or “Machine decommissioned”).

Item

Encoding

REQUIRED

Revocation Reason

Structure

 

Revocation Reason Code

Enumeration

Yes

Revocation Message

Text String

No

Table 122: Revocation Reason Attribute Structure

SHALL always have a value

No

Initially set by

Server

Modifiable by server

Yes

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Revoke

Applies to Object Types

All Objects

Table 123: Revocation Reason Attribute Rules

4.48 Sensitive

If True then the server SHALL prevent the object value being retrieved (via the Get operation) unless it is wrapped by another key. The server SHALL set the value to False if the value is not provided by the client.

 

Item

Encoding

Sensitive

Boolean

Table 124: Sensitive Attribute

SHALL always have a value

Yes

Initially set by

Client or Server

Modifiable by server

Yes

Modifiable by client

Yes

Deletable by client

No

Multiple instances permitted

No

When implicitly set

When object is created or registered

Applies to Object Types

All Objects

Table 125: Sensitive Attribute Rules

4.49 Short Unique Identifier

The Short Unique Identifier is generated by the key management system to uniquely identify a Managed Object using a shorter identifier. It is only REQUIRED to be unique within the identifier space managed by a single key management system, however this identifier SHOULD be globally unique in order to allow for a key management domain export of such objects. This attribute SHALL be assigned by the key management system upon creation or registration of a Unique Identifier, and then SHALL NOT be changed or deleted before the object is destroyed.

The Short Unique Identifier SHOULD be generated as a SHA-256 hash of the Unique Identifier and SHALL be a 32 byte byte string.

Item

Encoding

Short Unique Identifier

Byte String

Table 126: Unique Identifier Attribute

SHALL always have a value

Yes

Initially set by

Server

Modifiable by server

No

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Create, Create Key Pair, Register, Derive Key, Certify, Re-certify, Re-key, Re-key Key Pair

Applies to Object Types

All Objects

Table 127: Short Unique Identifier Attribute Rules

4.50 State

This attribute is an indication of the State of an object as known to the key management server. The State SHALL NOT be changed by using the Modify Attribute operation on this attribute. The State SHALL only be changed by the server as a part of other operations or other server processes. An object SHALL be in one of the following states at any given time.

Note: The states correspond to those described in [SP800-57-1].

 

Figure 1: Cryptographic Object States and Transitions

 

·         Pre-Active: The object exists and SHALL NOT be used for any cryptographic purpose.

·         Active: The object SHALL be transitioned to the Active state prior to being used for any cryptographic purpose. The object SHALL only be used for all cryptographic purposes that are allowed by its Cryptographic Usage Mask attribute. If a Process Start Date attribute is set, then the object SHALL NOT be used for cryptographic purposes prior to the Process Start Date. If a Protect Stop attribute is set, then the object SHALL NOT be used for cryptographic purposes after the Process Stop Date.

·         Deactivated: The object SHALL NOT be used for applying cryptographic protection (e.g., encryption, signing, wrapping, MACing, deriving) . The object SHALL only be used for cryptographic purposes permitted by the Cryptographic Usage Mask attribute. The object SHOULD only be used to process cryptographically-protected information (e.g., decryption, signature verification, unwrapping, MAC verification under extraordinary circumstances and when special permission is granted.

·         Compromised: The object SHALL NOT be used for applying cryptographic protection (e.g., encryption, signing, wrapping, MACing, deriving). The object SHOULD only be used to process cryptographically-protected information (e.g., decryption, signature verification, unwrapping, MAC verification in a client that is trusted to use managed objects that have been compromised. The object SHALL only be used for cryptographic purposes permitted by the Cryptographic Usage Mask attribute.

·         Destroyed: The object SHALL NOT be used for any cryptographic purpose.

·         Destroyed Compromised: The object SHALL NOT be used for any cryptographic purpose; however its compromised status SHOULD be retained for audit or security purposes.

State transitions occur as follows:

1.     The transition from a non-existent key to the Pre-Active state is caused by the creation of the object. When an object is created or registered, it automatically goes from non-existent to Pre-Active. If, however, the operation that creates or registers the object contains an Activation Date that has already occurred, then the state immediately transitions from Pre-Active to Active. In this case, the server SHALL set the Activation Date attribute to the value specified in the request, or fail the request attempting to create or register the object, depending on server policy. If the operation contains an Activation Date attribute that is in the future, or contains no Activation Date, then the Cryptographic Object is initialized in the key management system in the Pre-Active state.

2.     The transition from Pre-Active to Destroyed is caused by a client issuing a Destroy operation. The server destroys the object when (and if) server policy dictates.

3.     The transition from Pre-Active to Compromised is caused by a client issuing a Revoke operation with a Revocation Reason containing a Revocation Reason Code of Compromised.

4.     The transition from Pre-Active to Active SHALL occur in one of three ways:

·         The Activation Date is reached,

·         A client successfully issues a Modify Attribute operation, modifying the Activation Date to a date in the past, or the current date, or

·         A client issues an Activate operation on the object. The server SHALL set the Activation Date to the time the Activate operation is received.

5.     The transition from Active to Compromised is caused by a client issuing a Revoke operation with a Revocation Reason containing a Revocation Reason Code of Compromised.

6.     The transition from Active to Deactivated SHALL occur in one of three ways:

·         The object's Deactivation Date is reached,

·         A client issues a Revoke operation, with a Revocation Reason containing a Revocation Reason Code other than Compromised, or

·         The client successfully issues a Modify Attribute operation, modifying the Deactivation Date to a date in the past, or the current date.

7.     The transition from Deactivated to Destroyed is caused by a client issuing a Destroy operation, or by a server, both in accordance with server policy. The server destroys the object when (and if) server policy dictates.

8.     The transition from Deactivated to Compromised is caused by a client issuing a Revoke operation with a Revocation Reason containing a Revocation Reason Code of Compromised.

9.     The transition from Compromised to Destroyed Compromised is caused by a client issuing a Destroy operation, or by a server, both in accordance with server policy. The server destroys the object when (and if) server policy dictates.

10.  The transition from Destroyed to Destroyed Compromised is caused by a client issuing a Revoke operation with a Revocation Reason containing a Revocation Reason Code of Compromised.

Only the transitions described above are permitted.

Item

Encoding

State

Enumeration

Table 128: State Attribute

SHALL always have a value

Yes

Initially set by

Server

Modifiable by server

Yes

Modifiable by client

No, but only by the server in response to certain requests (see above)

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Create, Create Key Pair, Register, Derive Key, Activate, Revoke, Destroy, Certify, Re-certify, Re-key, Re-key Key Pair

Applies to Object Types

All Objects

Table 129: State Attribute Rules

4.51 Unique Identifier

The Unique Identifier is generated by the key management system to uniquely identify a Managed Object. It is only REQUIRED to be unique within the identifier space managed by a single key management system, however this identifier SHOULD be globally unique in order to allow for a key management domain export of such objects. This attribute SHALL be assigned by the key management system at creation or registration time, and then SHALL NOT be changed or deleted before the object is destroyed.

Encoding

Description

Text String

Unique Identifier of a Managed Object.

Enumeration

Unique Identifier  Enumeration

Integer

Zero based nth Unique Identifier in the response. If negative the count is backwards from the beginning of the current operation’s batch item.

Table 130: Unique Identifier encoding descriptions

Item

Encoding

Unique Identifier

Text String, Enumeration or Integer

Table 131: Unique Identifier Attribute

SHALL always have a value

Yes

Initially set by

Server

Modifiable by server

No

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Create, Create Key Pair, Register, Derive Key, Certify, Re-certify, Re-key, Re-key Key Pair

Applies to Object Types

All Objects

Table 132: Unique Identifier Attribute Rules

4.52 Usage Limits

The Usage Limits attribute is a mechanism for limiting the usage of a Managed Object. It only applies to Managed Objects that are able to be used for applying cryptographic protection and it SHALL only reflect their usage for applying that protection (e.g., encryption, signing, etc.). This attribute does not necessarily exist for all Managed Cryptographic Objects, since some objects are able to be used without limit for cryptographically protecting data, depending on client/server policies. Usage for processing cryptographically protected data (e.g., decryption, verification, etc.) is not limited. The Usage Limits attribute contains the Usage Limit structure which has the three following fields:

Value

Description

Usage Limits Total

The total number of Usage Limits Units allowed to be protected. This is the total value for the entire life of the object and SHALL NOT be changed once the object begins to be used for applying cryptographic protection.

Usage Limits Count

The currently remaining number of Usage Limits Units allowed to be protected by the object.

 

Usage Limits Unit

The type of quantity for which this structure specifies a usage limit (e.g., byte, object).

Table 133;: Usage Limits Descriptions

 

When the attribute is initially set (usually during object creation or registration), the Usage Limits Count is set to the Usage Limits Total value allowed for the useful life of the object, and are decremented when the object is used. The server SHALL ignore the Usage Limits Count value if the attribute is specified in an operation that creates a new object. Changes made via the Modify Attribute operation reflect corrections to the Usage Limits Total value, but they SHALL NOT be changed once the Usage Limits Count value has changed by a Get Usage Allocation operation. The Usage Limits Count value SHALL NOT be set or modified by the client via the Add Attribute or Modify Attribute operations.

 

SHALL always have a value

No

Initially set by

Server (Usage Limits Total, Usage Limits Count, and Usage Limits Unit) or Client (Usage Limits Total and/or Usage Limits Unit only)

Modifiable by server

Yes

Modifiable by client

Yes (Usage Limits Total and/or Usage Limits Unit only, as long as Get Usage Allocation has not been performed)

Deletable by client

Yes, as long as Get Usage Allocation has not been performed

Multiple instances permitted

No

When implicitly set

Create, Create Key Pair, Register, Derive Key, Re-key, Re-key Key Pair, Get Usage Allocation

Applies to Object Types

All Objects

Table 134: Usage Limits Attribute Rules

4.53 Vendor Attribute

A vendor specific Attribute is a structure used for sending and receiving a Managed Object attribute. The Vendor Identification and Attribute Name are text-strings that are used to identify the attribute. The Attribute Value is either a primitive data type or structured object, depending on the attribute. Vendor identification values “x” and “y” are reserved for KMIP v2.0 and later implementations referencing KMIP v1.x Custom Attributes.

Vendor Attributes created by the client with Vendor Identification “x” are not created (provided during object creation), set, added, adjusted, modified or deleted by the server.

Vendor Attributes created by the server with Vendor Identification “y” are not created (provided during object creation), set, added, adjusted, modified or deleted by the client.

 

Item

Encoding

REQUIRED

Attribute

Structure

 

Vendor Identification

Text String (with usage limited to alphanumeric, underscore and period – i.e. [A-Za-z0-9_.])

Yes

Attribute Name

Text String

Yes

Attribute Value

Varies, depending on attribute.

Yes, except for the Notify operation

Table 135: Attribute Object Structure

4.54 X.509 Certificate Identifier

The X.509 Certificate Identifier attribute is a structure used to provide the identification of an X.509 public key certificate. The X.509 Certificate Identifier contains the Issuer Distinguished Name (i.e., from the Issuer field of the X.509 certificate) and the Certificate Serial Number (i.e., from the Serial Number field of the X.509 certificate).  The X.509 Certificate Identifier SHALL be set by the server when the X.509 certificate is created or registered and then SHALL NOT be changed or deleted before the object is destroyed.

Item

Encoding

REQUIRED

X.509 Certificate Identifier

Structure

 

Issuer Distinguished Name

Byte String

Yes

Certificate Serial Number

Byte String

Yes

Table 136: X.509 Certificate Identifier Attribute Structure

SHALL always have a value

Yes

Initially set by

Server

Modifiable by server

No

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Register, Certify, Re-certify

Applies to Object Types

X.509 Certificates

Table 137: X.509 Certificate Identifier Attribute Rules

4.55 X.509 Certificate Issuer

The X.509 Certificate Issuer attribute is a structure used to identify the issuer of a X.509 certificate, containing the Issuer Distinguished Name (i.e., from the Issuer field of the X.509 certificate). It MAY include one or more alternative names (e.g., email address, IP address, DNS name) for the issuer of the certificate (i.e., from the Issuer Alternative Name extension within the X.509 certificate). The server SHALL set these values based on the information it extracts from a X.509 certificate that is created as a result of a Certify or a Re-certify operation or is sent as part of a Register operation. These values SHALL NOT be changed or deleted before the object is destroyed.

Item

Encoding

REQUIRED

X.509 Certificate Issuer

Structure

 

Issuer Distinguished Name

Byte String

Yes

Issuer Alternative Name

Byte String, MAY be repeated

No

Table 138: X.509 Certificate Issuer Attribute Structure

SHALL always have a value

Yes

Initially set by

Server

Modifiable by server

No

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Register, Certify, Re-certify

Applies to Object Types

X.509 Certificates

Table 139: X.509 Certificate Issuer Attribute Rules

4.56 X.509 Certificate Subject

The X.509 Certificate Subject attribute is a structure used to identify the subject of a X.509 certificate. The X.509 Certificate Subject contains the Subject Distinguished Name (i.e., from the Subject field of the X.509 certificate). It MAY include one or more alternative names (e.g., email address, IP address, DNS name) for the subject of the X.509 certificate (i.e., from the Subject Alternative Name extension within the X.509 certificate).  The X.509 Certificate Subject SHALL be set by the server based on the information it extracts from the X.509 certificate that is created (as a result of a Certify or a Re-certify operation) or registered (as part of a Register operation) and SHALL NOT be changed or deleted before the object is destroyed.

If the Subject Alternative Name extension is included in the X.509 certificate and is marked critical within the X.509 certificate itself, then an X.509 certificate MAY be issued with the subject field left blank. Therefore an empty string is an acceptable value for the Subject Distinguished Name.

Item

Encoding

REQUIRED

X.509 Certificate Subject

Structure

 

Subject Distinguished Name

Byte String

Yes, but MAY be the empty string

Subject Alternative Name

Byte String, MAY be repeated

Yes, if the Subject Distinguished Name is an empty string.

Table 140: X.509 Certificate Subject Attribute Structure

SHALL always have a value

Yes

Initially set by

Server

Modifiable by server

No

Modifiable by client

No

Deletable by client

No

Multiple instances permitted

No

When implicitly set

Register, Certify, Re-certify

Applies to Object Types

X.509 Certificates

Table 141: X.509 Certificate Subject Attribute Rules

 

5      Attribute Data Structures

5.1 Attributes

This structure is used in various operations to provide the desired attribute values in the request and to return the actual attribute values in the response.

The Attributes structure is defined as follows:

Item

Encoding

REQUIRED

Attributes

Structure

 

Any attribute in §4 - Object Attributes

Any, MAY be repeated

No

Table 142: Attributes Definition

5.2 Common Attributes

This structure is used in various operations to provide the desired attribute values in the request and to return the actual attribute values in the response.

The Common Attributes structure is defined as follows:

Item

Encoding

REQUIRED

Common Attributes

Structure

 

Any attribute in §4 - Object Attributes

Any, MAY be repeated

No

Table 143: Common Attributes Definition

5.3 Private Key Attributes

This structure is used in various operations to provide the desired attribute values in the request and to return the actual attribute values in the response.

The Private Key Attributes structure is defined as follows:

Item

Encoding

REQUIRED

Private Key Attributes

Structure

 

Any attribute in §4 - Object Attributes

Any, MAY be repeated

No

Table 144: Private Key Attributes Definition

5.4 Public Key Attributes

This structure is used in various operations to provide the desired attribute values in the request and to return the actual attribute values in the response.

The Public Key Attributes structure is defined as follows:

Item

Encoding

REQUIRED

Public Key Attributes

Structure

 

Any attribute in §4 - Object Attributes

Any, MAY be repeated

No

Table 145: Public Key Attributes Definition

5.5 Attribute Reference

These structures are used in various operations to provide reference to an attribute by name or by tag in a request or response.

The Attribute Reference definition is as follows:

Object

Encoding

REQUIRED

Attribute Reference

Structure

 

Vendor Identification

Text String (with usage limited to alphanumeric, underscore and period – i.e. [A-Za-z0-9_.])

Yes

Attribute Name

Text String

Yes

OR

Object

Encoding

REQUIRED

Attribute Reference

Enumeration (Tag)

Yes

Table 146: Attribute Reference Definition

5.6 Current Attribute

Structure used in various operations to provide the Current Attribute value in the request.

The Current Attribute structure is defined identically as follows:

Item

Encoding

REQUIRED

Current Attribute

Structure

 

Any attribute in §4 - Object Attributes

Any

Yes

Table 147: Current Attribute Definition

5.7 New Attribute

Structure used in various operations to provide the New Attribute value in the request.

The New Attribute structure is defined identically as follows:

Item

Encoding

REQUIRED

New Attribute

Structure

 

Any attribute in §4 - Object Attributes

Any

Yes

Table 148: New Attribute Definition

6      Operations

6.1 Client-to-Server Operations

The following subsections describe the operations that MAY be requested by a key management client. Not all clients have to be capable of issuing all operation requests; however any client that issues a specific request SHALL be capable of understanding the response to the request. All Object Management operations are issued in requests from clients to servers, and results obtained in responses from servers to clients. Multiple operations MAY be combined within a batch, resulting in a single request/response message pair.

A number of the operations whose descriptions follow are affected by a mechanism referred to as the ID Placeholder.

The key management server SHALL implement a temporary variable called the ID Placeholder. This value consists of a single Unique Identifier. It is a variable stored inside the server that is only valid and preserved during the execution of a batch of operations. Once the batch of operations has been completed, the ID Placeholder value SHALL be discarded and/or invalidated by the server, so that subsequent requests do not find this previous ID Placeholder available.

The ID Placeholder is obtained from the Unique Identifier returned in response to the Create, Create Pair, Register, Derive Key, Re-key, Re-key Key Pair, Certify, Re-Certify, Locate, and Recover operations. If any of these operations successfully completes and returns a Unique Identifier, then the server SHALL copy this Unique Identifier into the ID Placeholder variable, where it is held until the completion of the operations remaining in the batched request or until a subsequent operation in the batch causes the ID Placeholder to be replaced. If the Batch Order Option is set to true (or unspecified), then subsequent operations in the batched request MAY make use of the ID Placeholder by omitting the Unique Identifier field from the request payloads for these operations.

Requests MAY contain attribute values to be assigned to the object. This information is specified with zero or more individual attributes.

For any operations that operate on Managed Objects already stored on the server, any archived object SHALL first be made available by a Recover operation before they MAY be specified (i.e., as on-line objects).

Multi-part cryptographic operations (operations where a stream of data is provided across multiple requests from a client to a server) are optionally supported by those cryptographic operations that include the Correlation Value, Init Indicator  and Final Indicator request parameters.

For multi-part cryptographic operations the following sequence is performed

  1. On the first request

a.     Provide an Init Indicator with a value of True

b.     Provide any other required parameters

c.     Preserve the Correlation Value returned in the response for use in subsequent requests

d.     Use the Data output (if any) from the response

  1. On subsequent requests

a.     Provide the Correlation Value from the response to the first request

b.     Provide any other required parameters

c.     Use the next block of Data output (if any) from the response

  1. On the final request

a.     Provide the Correlation Value from the response to the first request

b.     Provide a Final Indicator with a value of True

c.     Use the final block of Data output (if any) from the response

Single-part cryptographic operations (operations where a single input is provided and a single response returned) the following sequence is performed:

  1. On each request

a.     Do not provide an Init Indicator, Final Indicator or Correlation Value or provide an Init indicator and Final Indicator but no Correlation Value.

b.     Provide any other required parameters

c.     Use the Data output from the response

Data is always required in cryptographic operations except when either Init Indicator or Final Indicator is true.

6.1.1 Activate

This operation requests the server to activate a Managed Object. The operation SHALL only be performed on an object in the Pre-Active state and has the effect of changing its state to Active, and setting its Activation Date to the current date and time.

Request Payload

Item

REQUIRED

Description

Unique Identifier

No

Determines the object being activated. If omitted, then the ID Placeholder value is used by the server as the Unique Identifier.

Table 149: Activate Request Payload

Response Payload

Item

REQUIRED

Description

Unique Identifier

Yes

The Unique Identifier of the object.

Table 150: Activate Response Payload

6.1.1.1 Error Handling – Activate

This section details the specific Result Reasons that SHALL be returned for errors detected in a Activate Operation.

 

Result Status

Result Reason

Operation Failed

Invalid Object Type, Object Not Found, Wrong Key Lifecycle State, Attestation Failed, Attestation Required, Feature Not Supported, Invalid Field, Invalid Message, Operation Not Supported, Permission Denied, Response Too Large

Table 151: Activate Errors

6.1.2 Add Attribute

This operation requests the server to add a new attribute instance to be associated with a Managed Object and set its value. The request contains the Unique Identifier of the Managed Object to which the attribute pertains, along with the attribute name and value. For single-instance attributes, this creates the attribute value. For multi-instance attributes, this is how the first and subsequent values are created. Existing attribute values SHALL NOT be changed by this operation. Read-Only attributes SHALL NOT be added using the Add Attribute operation.

Request Payload

Item

REQUIRED

Description

Unique Identifier

No

The Unique Identifier of the object. If omitted, then the ID Placeholder value is used by the server as the Unique Identifier. 

New Attribute

Yes

Specifies the attribute to be added to the object.

Table 152: Add Attribute Request Payload

Response Payload

Item

REQUIRED

Description

Unique Identifier

Yes

The Unique Identifier of the object.

Table 153: Add Attribute Response Payload

6.1.2.1 Error Handling - Add Attribute

This section details the specific Result Reasons that SHALL be returned for errors detected in a Add Attribute Operation.

 

Result Status

Result Reason

Operation Failed

Attribute Single Valued, Invalid Attribute, Invalid Message, Non Unique Name Attribute, Object Not Found, Read Only Attribute, Server Limit Exceeded, Attestation Failed, Attestation Required, Feature Not Supported, Invalid Field, Invalid Message, Operation Not Supported, Permission Denied, Response Too Large

Table 154: Add Attribute Errors

6.1.3 Adjust Attribute

This operation requests the server to adjust the value of an attribute. The request contains the Unique Identifier of the Managed Object to which the attribute pertains, along with the attribute reference and value. If the object did not have value for the attribute, the previous value is assumed to be a 0 for numeric types and intervals, or false for Boolean, otherwise an error is raised. If the object had exactly one instance, then it is modified. If it has more than one instance an error is raised. Read-Only attributes SHALL NOT be added or modified using this operation.

Request Payload

Item

REQUIRED

Description

Unique Identifier

No

The Unique Identifier of the object. If omitted, then the ID Placeholder value is used by the server as the Unique Identifier. 

Attribute Reference

Yes

The attribute to be adjusted.

Adjustment Type

Yes

The adjustment to be made.

Adjustment Value

No

The value for the adjustment

Table 155: Adjust Attribute Request Payload

Response Payload

Item

REQUIRED

Description

Unique Identifier

Yes

The Unique Identifier of the object.

Table 156: Adjust Attribute Response Payload

6.1.3.1 Error Handling - Adjust Attribute

This section details the specific Result Reasons that SHALL be returned for errors detected in a Adjust Attribute Operation.

Result Status

Result Reason

Operation Failed

Invalid Data Type, Item Not Found, Multi Valued Attribute, Numeric Range, Object Archived, Read Only Attribute, Unsupported Attribute, Attestation Failed, Attestation Required, Feature Not Supported, Invalid Field, Invalid Message, Operation Not Supported, Permission Denied, Response Too Large

Table 157: Adjust Attribute Errors

6.1.4 Archive

This operation is used to specify that a Managed Object MAY be archived. The actual time when the object is archived, the location of the archive, or level of archive hierarchy is determined by the policies within the key management system and is not specified by the client. The request contains the Unique Identifier of the Managed Object. This request is only an indication from a client that, from its point of view, the key management system MAY archive the object.

Request Payload

Item

REQUIRED

Description

Unique Identifier

No

Determines the object being archived. If omitted, then the ID Placeholder value is used by the server as the Unique Identifier.

Table 158: Archive Request Payload

Response Payload

Item

REQUIRED

Description

Unique Identifier

Yes

The Unique Identifier of the object.

Table 159: Archive Response Payload

6.1.4.1 Error Handling – Archive

This section details the specific Result Reasons that SHALL be returned for errors detected in a Archive Operation.

Result Status

Result Reason

Operation Failed

Object Archived, Object Not Found, Attestation Failed, Attestation Required, Feature Not Supported, Invalid Field, Invalid Message, Operation Not Supported, Permission Denied, Response Too Large

Table 160: Archive Errors

6.1.5 Cancel

This operation requests the server to cancel an outstanding asynchronous operation. The correlation value of the original operation SHALL be specified in the request. The server SHALL respond with a Cancellation Result. The response to this operation is not able to be asynchronous.

Request Payload

Item

REQUIRED

Description

Asynchronous Correlation Value

Yes

Specifies the request being canceled.

Table 161: Cancel Request Payload

Response Payload

Item

REQUIRED

Description

Asynchronous Correlation Value

Yes

Specified in the request.

Cancellation Result

Yes

Enumeration indicating the result of the cancellation.

Table 162: Cancel Response Payload

This section details the specific Result Reasons that SHALL be returned for errors detected in a Cancel Operation.

Result Status

Result Reason

Operation Failed

Invalid Asynchronous Correlation Value, Attestation Failed, Attestation Required, Feature Not Supported, Invalid Field, Invalid Message, Operation Not Supported, Permission Denied, Response Too Large

 Table 163: Cancel Errors

6.1.6 Certify

This request is used to generate a Certificate object for a public key. This request supports the certification of a new public key, as well as the certification of a public key that has already been certified (i.e., certificate update). Only a single certificate SHALL be requested at a time.

The Certificate Request object MAY be omitted, in which case the public key for which a Certificate object is generated SHALL be specified by its Unique Identifier only. If the Certificate Request Type and the Certificate Request objects are omitted from the request, then the Certificate Type SHALL be specified using the Attributes object.

The Certificate Request is passed as a Byte String, which allows multiple certificate request types for X.509 certificates (e.g., PKCS#10, PEM, etc.) to be submitted to the server.

The generated Certificate object whose Unique Identifier is returned MAY be obtained by the client via a Get operation in the same batch, using the ID Placeholder mechanism.

For the public key, the server SHALL create a Link attribute of Link Type Certificate pointing to the generated certificate. For the generated certificate, the server SHALL create a Link attribute of Link Type Public Key pointing to the Public Key.

The server SHALL copy the Unique Identifier of the generated certificate returned by this operation into the ID Placeholder variable.

If the information in the Certificate Request conflicts with the attributes specified in the Attributes, then the information in the Certificate Request takes precedence.

Request Payload

Item

REQUIRED

Description

Unique Identifier

No

The Unique Identifier of the Public Key or the Certificate Request being certified. If omitted and Certificate Request is not present, then the ID Placeholder value is used by the server as the Unique Identifier.

Certificate Request Type

No

An Enumeration object specifying the type of certificate request. It is REQUIRED if the Certificate Request is present.

Certificate Request Value

No

A Byte String object with the certificate request.

Attributes

No

Specifies desired object attributes.

 

Protection Storage Masks

No

Specifies all permissible Protection Storage Mask selections for the new object

Table 164: Certify Request Payload

Response Payload

Item

REQUIRED

Description

Unique Identifier

Yes

The Unique Identifier of the generated Certificate object.

Table 165: Certify Response Payload

6.1.6.1 Error Handling – Certify

This section details the specific Result Reasons that SHALL be returned for errors detected in a Certify Operation.

 

Result Status

Result Reason

Operation Failed

Invalid CSR, Invalid Object Type, Item Not Found, Attestation Failed, Attestation Required, Feature Not Supported, Invalid Field, Invalid Message, Operation Not Supported, Permission Denied, Protection Storage Unavailable, Response Too Large

Table 166: Certify Errors

 

6.1.7 Check

This operation requests that the server check for the use of a Managed Object according to values specified in the request. This operation SHOULD only be used when placed in a batched set of operations, usually following a Locate, Create, Create Pair, Derive Key, Certify, Re-Certify, Re-key or Re-key Key Pair operation, and followed by a Get operation.

If the server determines that the client is allowed to use the object according to the specified attributes, then the server returns the Unique Identifier of the object.

If the server determines that the client is not allowed to use the object according to the specified attributes, then the server empties the ID Placeholder and does not return the Unique Identifier, and the operation returns the set of attributes specified in the request that caused the server policy denial. The only attributes returned are those that resulted in the server determining that the client is not allowed to use the object, thus allowing the client to determine how to proceed. 

In a batch containing a Check operation the Batch Order Option SHOULD be set to true. Only STOP or UNDO Batch Error Continuation Option values SHOULD be used by the client in such a batch. Additional attributes that MAY be specified in the request are limited to:

Value

Description

Usage Limits Count

The request MAY contain the usage amount that the client deems necessary to complete its needed function. This does not require that any subsequent Get Usage Allocation operations request this amount. It only means that the client is ensuring that the amount specified is available.

Cryptographic Usage Mask

This is used to specify the cryptographic operations for which the client intends to use the object (see Section 3.19). This allows the server to determine if the policy allows this client to perform these operations with the object. Note that this MAY be a different value from the one specified in a Locate operation that precedes this operation. Locate, for example, MAY specify a Cryptographic Usage Mask requesting a key that MAY be used for both Encryption and Decryption, but the value in the Check operation MAY specify that the client is only using the key for Encryption at this time.

Lease Time

This specifies a desired lease time (see Section 3.20). The client MAY use this to determine if the server allows the client to use the object with the specified lease or longer. Including this attribute in the Check operation does not actually cause the server to grant a lease, but only indicates that the requested lease time value MAY be granted if requested by a subsequent, batched Obtain Lease operation.

Table 167: Check value description

Note that these objects are not encoded in an Attribute structure.

Request Payload

Item

REQUIRED

Description

Unique Identifier

No

Determines the object being checked. If omitted, then the ID Placeholder value is used by the server as the Unique Identifier.

Usage Limits Count

No

Specifies the number of Usage Limits Units to be protected to be checked against server policy.

Cryptographic Usage Mask

No

Specifies the Cryptographic Usage for which the client intends to use the object.

Lease Time

No

Specifies a Lease Time value that the Client is asking the server to validate against server policy.

Table 168: Check Request Payload

Response Payload

Item

REQUIRED

Description

Unique Identifier

Yes, unless a failure,

The Unique Identifier of the object.

Usage Limits Count

No

Returned by the Server if the Usage Limits value specified in the Request Payload is larger than the value that the server policy allows.

Cryptographic Usage Mask

No

Returned by the Server if the Cryptographic Usage Mask specified in the Request Payload is rejected by the server for policy violation.

Lease Time

No

Returned by the Server if the Lease Time value in the Request Payload is larger than a valid Lease Time that the server MAY grant.

Table 169: Check Response Payload

6.1.7.1 Error Handling – Check

This section details the specific Result Reasons that SHALL be returned for errors detected in a Check Operation.

 

Result Status

Result Reason

Operation Failed

Illegal Object Type, Incompatible Cryptographic Usage Mask, Object Not Found, Usage Limit Exceeded, Attestation Failed, Attestation Required, Feature Not Supported, Invalid Field, Invalid Message, Operation Not Supported, Permission Denied, Response Too Large

Table 170: Check Errors

6.1.8 Create

This operation requests the server to generate a new symmetric key or generate Secret Data as a Managed Cryptographic Object.

The request contains information about the type of object being created, and some of the attributes to be assigned to the object (e.g., Cryptographic Algorithm, Cryptographic Length, etc.).

The response contains the Unique Identifier of the created object. The server SHALL copy the Unique Identifier returned by this operation into the ID Placeholder variable.

Request Payload

Item

REQUIRED

Description

Object Type

Yes

Determines the type of object to be created.

Attributes

Yes

Specifies desired attributes to be associated with the new object.

 

Protection Storage Masks

No

Specifies all permissible Protection