Internet Engineering Task Force D. Lanz Internet-Draft L. Novikov Intended status: Informational MITRE Expires: January 26, 2012 July 25, 2011 Common Interface to Cryptographic Modules (CICM) Key Management draft-lanz-cicm-km-01 Abstract [RFC Editor: Please update the RFC references prior to publication.] This memo defines a programming interface for the management of cryptographic keys as outlined in draft-lanz-cicm-model-00 and required by draf-lanz-cicm-02 including managing a key database as well as individual symmetric and asymmetric keys. Comments are solicited and should be addressed to the mailing list at cicm@ietf.org. Status of this Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on January 26, 2012. Copyright Notice Copyright (c) 2011 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect Lanz & Novikov Expires January 26, 2012 [Page 1] Internet-Draft CICM Key Management July 2011 to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 4 1.2. Definition Language . . . . . . . . . . . . . . . . . . . 4 1.3. Conformance and Extension Language . . . . . . . . . . . . 4 2. CICM Dependencies . . . . . . . . . . . . . . . . . . . . . . 4 2.1. Namespaces . . . . . . . . . . . . . . . . . . . . . . . . 4 2.2. Types . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.3. Interfaces . . . . . . . . . . . . . . . . . . . . . . . . 5 3. General Key Concepts . . . . . . . . . . . . . . . . . . . . . 5 3.1. Creating and Establishing Keys . . . . . . . . . . . . . . 5 3.2. Exporting Keys . . . . . . . . . . . . . . . . . . . . . . 6 3.3. Destroying Keys . . . . . . . . . . . . . . . . . . . . . 6 3.4. Locating Keys . . . . . . . . . . . . . . . . . . . . . . 6 3.5. Protecting Keys . . . . . . . . . . . . . . . . . . . . . 6 3.6. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 6 3.7. Interface CICM::Key . . . . . . . . . . . . . . . . . . . 7 3.8. Interface CICM::KeyDatabase . . . . . . . . . . . . . . . 12 4. Asymmetric Keys . . . . . . . . . . . . . . . . . . . . . . . 13 4.1. Interface CICM::AsymKeyManager . . . . . . . . . . . . . . 13 4.2. Interface CICM::AsymKey . . . . . . . . . . . . . . . . . 21 4.3. Interface CICM::AsymKeyIterator . . . . . . . . . . . . . 24 5. Symmetric Keys . . . . . . . . . . . . . . . . . . . . . . . . 25 5.1. Interface CICM::SymKeyManager . . . . . . . . . . . . . . 25 5.2. Interface CICM::SymKey . . . . . . . . . . . . . . . . . . 34 5.3. Interface CICM::SymKeyIterator . . . . . . . . . . . . . . 39 6. Key Protocol . . . . . . . . . . . . . . . . . . . . . . . . . 40 6.1. Participants in the Interaction . . . . . . . . . . . . . 42 6.2. Return Status, Condition, and Session Status . . . . . . . 43 6.3. Generic Scenario . . . . . . . . . . . . . . . . . . . . . 44 6.4. Key Agreement Example Using Diffie-Hellman Protocol . . . 45 6.5. Protocol Support Examples . . . . . . . . . . . . . . . . 48 6.6. Interface CICM::KeyProtocolSender . . . . . . . . . . . . 49 6.7. Interface CICM::KeyProtocolReceiver . . . . . . . . . . . 53 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 56 8. Security Considerations . . . . . . . . . . . . . . . . . . . 56 8.1. Authorization . . . . . . . . . . . . . . . . . . . . . . 56 8.2. Authentication . . . . . . . . . . . . . . . . . . . . . . 57 8.3. Entity Authentication . . . . . . . . . . . . . . . . . . 57 8.4. Confidentiality . . . . . . . . . . . . . . . . . . . . . 57 8.5. Data Integrity . . . . . . . . . . . . . . . . . . . . . . 57 Lanz & Novikov Expires January 26, 2012 [Page 2] Internet-Draft CICM Key Management July 2011 8.6. Inappropriate Usage . . . . . . . . . . . . . . . . . . . 57 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 58 9.1. Normative References . . . . . . . . . . . . . . . . . . . 58 9.2. Informative References . . . . . . . . . . . . . . . . . . 58 Appendix A. IDL Definitions . . . . . . . . . . . . . . . . . . . 58 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 65 Lanz & Novikov Expires January 26, 2012 [Page 3] Internet-Draft CICM Key Management July 2011 1. Introduction This document defines the key management functions for the Common Interface to Cryptographic Modules (CICM) as defined in [CICM]. The underlying logical model and terminology is defined in [CICM-LM]. 1.1. Requirements Language 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]. 1.2. Definition Language This document uses the Interface Definition Language (IDL) [IDL] to specify language-neutral interfaces and is not intended to prescribe or preclude a particular communications protocol such as General Inter-ORB Protocol (GIOP) [CORBA] between programs in different address spaces or on different devices. In other words, any specific protocol is strictly OPTIONAL. See Definition Language in [CICM] for more information. 1.3. Conformance and Extension Language This document contains definitions for several opaque data parameters whose format is not defined by CICM. Instead, implementers are required to create an Implementation Conformance Statement which MUST reference a standard format or define a module developer-specific format implemented by the module for these datatypes. See Conformance and Extensions in [CICM] for more details. 2. CICM Dependencies This document depends on type definitions and interfaces that are defined in other CICM documents. 2.1. Namespaces The CICM namespace is defined in [CICM]. 2.2. Types The following type definitions are defined in [CICM]: CICM::UInt32 Lanz & Novikov Expires January 26, 2012 [Page 4] Internet-Draft CICM Key Management July 2011 CICM::CharString CICM::Buffer CICM::Status (including all return values) CICM::LocalPort CICM::Classification The type definitions for the following identifiers are defined in [CICM-CM]: CICM::SymEncrAlgorithmId CICM::SymEncrAlgorithmId CICM::HashAlgorithmId CICM::KeyWrapAlgorithmId CICM::ProtocolId 2.3. Interfaces The interface CICM::Iterator is defined in [CICM]; CICM::Negotiator is defined in [CICM-CM]. 3. General Key Concepts 3.1. Creating and Establishing Keys This specification provides facilities to convey key material into a cryptographic module via one of several methods, including importing key into the module through the API or a key fill interface, or generating or deriving key on the module. Key material may also be created through the use of a key establishment protocol between the module and a key infrastructure component or another module. Such a protocol is initiated between two or more parties to establish a secret key over a communications channel. The specification supports conveying generic protocol messages to and from a cryptographic module to effect the establishment of this secret key. See the CICM::KeyProtocolSender and CICM::KeyProtocolReceiver interfaces for additional information. Key metadata may be retrieved and set for individual keys. Metadata Lanz & Novikov Expires January 26, 2012 [Page 5] Internet-Draft CICM Key Management July 2011 elements include the key identifier, alias, and classification. Keys imported via a fill device that are untagged may require certain metadata to be applied after the conclusion of the load, for example. 3.2. Exporting Keys Key material may also be exported out of a cryptographic module through the use of the key export functionality to enable transfer to another entity or for storage within the host system. 3.3. Destroying Keys This specification provides the ability to permanently and irretrievably destroy key material. These capabilities apply to keys managed by the module, whether stored internal to the module or stored externally. 3.4. Locating Keys A key is typically designated by a global identifier defined by the external key management system from which the key originated. Alternatively, a key may be designated by a numeric value representing the physical storage location of the key within the module. Key location methods enable a key object representing the key specified by a supplied identifier to be retrieved by the caller. Note that the format of the key identifier is not defined by CICM. The Implementation Conformance Statement (see Conformance and Extensions in [CICM]) MUST reference a standard format or define a module developer-specific format implemented by the module for this datatype. 3.5. Protecting Keys These methods enable the encryption and decryption of key material to support transferring keys between modules or other entities (including storage of key material external to the module). 3.6. Identifiers Type CICM::KeyId typedef CICM::CharString KeyId; Unique key identifier. Lanz & Novikov Expires January 26, 2012 [Page 6] Internet-Draft CICM Key Management July 2011 3.7. Interface CICM::Key Interface CICM::Key interface Key { Interface from which symmetric and asymmetric key interfaces inherit. 3.7.1. CICM::Key Types and Constants Type CICM::Key::State typedef CICM::UInt32 State; Indicates whether or not the key is valid. Constant CICM::Key::C_KEY_INVALID const CICM::Key::State C_KEY_INVALID = 0x00006010; Key is invalid. Constant CICM::Key::C_KEY_VALID_WRAPPED const CICM::Key::State C_KEY_VALID_WRAPPED = 0x00006013; Key is valid and in wrapped form. Constant CICM::Key::C_KEY_VALID_UNWRAPPED const CICM::Key::State C_KEY_VALID_UNWRAPPED = 0x00006015; Key is valid and in unwrapped form. Type CICM::Key::UsageStatus typedef CICM::UInt32 UsageStatus; Indicates whether a key usage is allowed or forbidden. Constant CICM::Key::C_KEY_USAGE_ALLOWED const CICM::Key::UsageStatus C_KEY_USAGE_ALLOWED = 0x00006016; Key is valid for this usage. Constant CICM::Key::C_KEY_USAGE_FORBIDDEN const CICM::Key::UsageStatus C_KEY_USAGE_FORBIDDEN = 0x00006019; Key is not valid for this usage. Lanz & Novikov Expires January 26, 2012 [Page 7] Internet-Draft CICM Key Management July 2011 3.7.2. CICM::Key Attributes Attribute CICM::Key::identifier attribute CICM::CharString identifier; Unique global identifier for this key. Remarks: This identifier is the string representation of a key management authority-specific global key identifier. The identifier may be composed of multiple components; the representation of these components within the CICM identifier string is not defined in this specification. The Implementation Conformance Statement (see Conformance and Extensions in [CICM]) MUST reference a standard format or define a module developer-specific format implemented by the module for this identifier. Warning: This attribute MUST NOT be implemented if CICM::Key::location is implemented. Attribute CICM::Key::location attribute CICM::UInt32 location; Module-specific physical storage location for this key. Warning: This attribute should only be used when a module utilizes a key storage model that requires keys of particular types to be stored in specific locations or in situations where keys are tied to module capabilities based upon physical location of the key. Because of the architectural knowledge of a module required, its use is highly discouraged because it virtually guarantees that code using it will be incompatible with other dissimilar modules. This attribute MUST NOT be implemented if CICM::Key::identifier is implemented. Attribute CICM::Key::alias attribute CICM::CharString alias; Key alias, to assist in distinguishing one key from another. Attribute CICM::Key::classification attribute CICM::Classification classification; Key classification level. Lanz & Novikov Expires January 26, 2012 [Page 8] Internet-Draft CICM Key Management July 2011 Attribute CICM::Key::caveat attribute CICM::CharString caveat; Key caveat, a protective marking or distribution/handling instruction that may augment classification level. Attribute CICM::Key::authority attribute CICM::CharString authority; Key management authority governing generation and use of key. Attribute CICM::Key::state readonly attribute CICM::Key::State state; State of key. A key may become invalid if zeroized, for example. Note that if an attempt is made to use an invalid key, the method accepting the key reference will return with an appropriate error status. 3.7.3. CICM::Key Methods Method CICM::Key::wrap() CICM::Status wrap( in CICM::Key kek, in CICM::KeyWrapAlgorithmId algorithm ); Instruct module to wrap key, destroying the original unwrapped key and replacing it with the newly wrapped key. Parameters: [in] kek Reference to key encryption key. [in] algorithm Key wrap algorithm/mode used to wrap key. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_KEY_USED_INVALID, S_KEY_USED_EXPIRED, S_KEY_USED_CLASSIFICATION, S_KEY_USED_WRAPPED, S_KEY_USED_CONTEXT, S_KEY_USED_COMPONENT_NOT_AVAIL, S_KEY_INVALID, S_KEY_EXPIRED, S_KEY_INCOMPATIBLE, S_KEY_CLASSIFICATION, S_KEY_WRAPPED, S_KEY_NOT_WRAPPABLE, S_KEY_WRAPPED_EXISTS, S_ALGO_INVALID, S_ALGO_INCOMPATIBLE, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT Lanz & Novikov Expires January 26, 2012 [Page 9] Internet-Draft CICM Key Management July 2011 Method CICM::Key::unwrap() CICM::Status unwrap( in CICM::Key kek, in CICM::KeyWrapAlgorithmId algorithm ); Instruct module to unwrap key, destroying the original wrapped key and replacing it with the newly unwrapped key. Parameters: [in] kek Reference to key decryption key. [in] algorithm Key wrap algorithm/mode used to unwrap key. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_KEY_USED_INVALID, S_KEY_USED_EXPIRED, S_KEY_USED_CLASSIFICATION, S_KEY_USED_WRAPPED, S_KEY_USED_CONTEXT, S_KEY_USED_COMPONENT_NOT_AVAIL, S_KEY_INVALID, S_KEY_EXPIRED, S_KEY_INCOMPATIBLE, S_KEY_CLASSIFICATION, S_KEY_UNWRAPPED_EXISTS, S_KEY_MALFORMED, S_KEY_METADATA_MALFORMED, S_ALGO_INVALID, S_ALGO_INCOMPATIBLE, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT Method CICM::Key::export() CICM::Status export( out CICM::Buffer key_material ); Export key material from a cryptographic module as an opaque binary object. Remarks: The key must have been previously wrapped, if required. See CICM::Key::wrap. Parameters: [out] key_material Binary version of the key. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, Lanz & Novikov Expires January 26, 2012 [Page 10] Internet-Draft CICM Key Management July 2011 S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_KEY_INVALID, S_KEY_EXPIRED, S_KEY_WRAPPED, S_KEY_NOT_WRAPPED, S_KEY_NOT_EXPORTABLE, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT Method CICM::Key::export_via_fill_interface() CICM::Status export_via_fill_interface( in CICM::LocalPort fill_port ); Export key material from a cryptographic module via a port representing a key fill interface. Remarks: The key must have been previously wrapped, if required. See CICM::Key::wrap. Parameters: [in] fill_port The local port from which the key will emanate. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_KEY_INVALID, S_KEY_EXPIRED, S_KEY_WRAPPED, S_KEY_NOT_WRAPPED, S_KEY_NOT_EXPORTABLE, S_KEY_FILL_DEVICE_NOT_CONNECTED, S_KEY_FILL_NOT_INITIATED, S_LOCAL_PORT_INVALID, S_LOCAL_PORT_INCOMPATIBLE, S_LOCAL_PORT_IN_USE, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT Method CICM::Key::zeroize() CICM::Status zeroize(); Zeroize the selected key. Remarks: Future cryptographic operations depending upon this key MUST fail with a CICM::S_KEY_INVALID status. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_KEY_INVALID, Lanz & Novikov Expires January 26, 2012 [Page 11] Internet-Draft CICM Key Management July 2011 S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT 3.8. Interface CICM::KeyDatabase Interface CICM::KeyDatabase interface KeyDatabase { CICM::KeyDatabase supports zeroizing keys and reencrypting a module key database. It is accessed from CICM::CryptoModule via the CICM:: CryptoModule::key_database attribute. 3.8.1. CICM::KeyDatabase Methods Method CICM::KeyDatabase::zeroize() CICM::Status zeroize(); Zeroize all key material on the module. Remarks: This method renders all instantiated key objects invalid. Future cryptographic operations depending upon zeroized keys MAY fail with a CICM::S_KEY_INVALID status. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT Method CICM::KeyDatabase::reencrypt() CICM::Status reencrypt(); Re-encrypt the module key database. Remarks: This method uses a module-managed key to protect the key database and only applies to keys managed by the module, whether stored internal to the module or stored externally. Keys stored external to the module and not directly managed by the module must utilize the key wrap methods to protect key material. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_TOKEN_NOT_PRESENT, Lanz & Novikov Expires January 26, 2012 [Page 12] Internet-Draft CICM Key Management July 2011 S_TOKEN_ADMIN_NOT_PRESENT, S_INSUFFICIENT_ENTROPY 4. Asymmetric Keys 4.1. Interface CICM::AsymKeyManager Interface CICM::AsymKeyManager interface AsymKeyManager { CICM::AsymKeyManager supports retrieving, importing, and generating asymmetric keysets. It is accessed from CICM::CryptoModule via the CICM::CryptoModule::asym_key_manager attribute. CICM::AsymKeyManager constructs the CICM::AsymKeyIterator and CICM::AsymKey interfaces. 4.1.1. CICM::AsymKeyManager Attributes AttributeCICM::AsymKeyManager::asymkey_iterator readonly attribute CICM::AsymKeyIterator asymkey_iterator; Returns an iterator to enable a reference to each asymmetric keyset in the module key database to be retrieved. Remarks: The returned iterator is set to the beginning of the iterated sequence. 4.1.2. CICM::AsymKeyManager Methods Method CICM::AsymKeyManager::get_key_by_id() CICM::Status get_key_by_id( in CICM::KeyId key_id, out CICM::AsymKey key_ref ); Retrieves a reference to the asymmetric keyset corresponding to the specified infrastructure-specific identifier. Warning: This method MUST NOT be implemented if CICM::AsymKeyManager:: get_key_by_phys_location is implemented. Parameters: [in] key_id Unique identifier of the keyset to be retrieved. [out] key_ref Reference to keyset corresponding to key identifier. Returns: Lanz & Novikov Expires January 26, 2012 [Page 13] Internet-Draft CICM Key Management July 2011 S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_NOT_AVAILABLE, S_KEY_INVALID, S_KEY_EXPIRED, S_KEY_INVALID_ID, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT Method CICM::AsymKeyManager::get_key_by_phys_location() CICM::Status get_key_by_phys_location( in CICM::UInt32 phys_location, out CICM::AsymKey key_ref ); Retrieves a reference to the asymmetric keyset corresponding to the specified module physical storage location. Warning: This call should only be used when a module utilizes a key storage model that requires keys of particular types to be stored in specific locations or in situations where keys are tied to module capabilities based upon physical location of the key. Because of the architectural knowledge of a module required, its use is highly discouraged because it virtually guarantees that code using it will be incompatible with other dissimilar modules. This method MUST NOT be implemented if CICM::AsymKeyManager:: get_key_by_id is implemented. Parameters: [in] phys_location Physical location of the key to be retrieved. [out] key_ref Reference to key corresponding to physical location. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_NOT_AVAILABLE, S_KEY_INVALID, S_KEY_EXPIRED, S_KEY_PHYSICAL_LOC, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT Lanz & Novikov Expires January 26, 2012 [Page 14] Internet-Draft CICM Key Management July 2011 Method CICM::AsymKeyManager::get_key_last_filled() CICM::Status get_key_last_filled( out CICM::AsymKey key_ref ); Retrieves a reference to the asymmetric keyset corresponding to the keyset most recently filled via a key fill device. Remarks: A client program may need to initiate this action if key material imported into a module does not contain the corresponding key metadata. This method allows a reference to the last keyset filled over the key fill interface to be referenced to enable metadata to be applied directly to the resulting keyset. The error status CICM::S_NOT_AVAILABLE is returned if no key is filled. Parameters: [out] key_ref Object representing last filled key. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_NOT_AVAILABLE, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT See also: SymKeyManager::get_key_last_filled for the symmetric version of this method. Method CICM::AsymKeyManager::import_key() CICM::Status import_key( in CICM::Buffer key_material, out CICM::AsymKey key_ref ); Import asymmetric keysets into a cryptographic module. Remarks: Keysets may be imported into a module as wrapped entities, necessitating the use of CICM::Key::unwrap to decrypt the keyset prior to use. Lanz & Novikov Expires January 26, 2012 [Page 15] Internet-Draft CICM Key Management July 2011 Keyset attributes may optionally be set to create or supplement key metadata. The format of the key material value is not defined by CICM. The Implementation Conformance Statement (see Conformance and Extensions in [CICM]) MUST reference a standard format or define a module developer-specific format implemented by the module for this datatype. Warning: This method MUST NOT be implemented if CICM::AsymKeyManager:: import_key_into_phys_location is implemented. Parameters: [in] key_material Key material to be imported into the module. [out] key_ref Reference to newly imported key. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_KEY_MALFORMED, S_KEY_METADATA_MALFORMED, S_KEY_TRUST_ANCHOR, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT See also: CICM::SymKeyManager::import_key for the symmetric version of this method. CICM::AsymKeyManager::import_key_via_fill for the key fill version of this method. CICM::AsymKeyManager::import_key_into_phys_location for the version of this method that imports key into a specific module key location. CICM::AsymKeyManager::import_key_via_fill_into_phys_location for the version of this method that fills key into a specific module key location. Lanz & Novikov Expires January 26, 2012 [Page 16] Internet-Draft CICM Key Management July 2011 Method CICM::AsymKeyManager::import_key_into_phys_location() CICM::Status import_key_into_phys_location( in CICM::Buffer key_material, in CICM::UInt32 phys_location, out CICM::SymKey key_ref ); Import key material into a specific physical key location in a cryptographic module. Remarks: Keysets may be imported into a module as wrapped entities, necessitating the use of CICM::Key::unwrap to decrypt the keyset prior to use. Keyset object attributes may optionally be set to create or supplement keyset metadata. The format of the key material value is not defined by CICM. The Implementation Conformance Statement (see Conformance and Extensions in [CICM]) MUST reference a standard format or define a module developer-specific format implemented by the module for this datatype. Warning: This call should only be used when a module utilizes a key storage model that requires keys of particular types to be stored in specific locations or in situations where keys are tied to module capabilities based upon physical location of the key. Because of the architectural knowledge of a module required, its use is highly discouraged because it virtually guarantees that code using it will be incompatible with other dissimilar modules. This method MUST NOT be implemented if CICM::AsymKeyManager:: import_key is implemented. Parameters: [in] key_material Key material to be imported into the module. [in] phys_location Physical location into which to import keyset. [out] key_ref Reference to newly imported keyset. Returns: Lanz & Novikov Expires January 26, 2012 [Page 17] Internet-Draft CICM Key Management July 2011 S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_KEY_PHYSICAL_LOC, S_KEY_MALFORMED, S_KEY_METADATA_MALFORMED, S_KEY_TRUST_ANCHOR, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT Method CICM::AsymKeyManager::import_key_via_fill() CICM::Status import_key_via_fill( in CICM::LocalPort fill_port, out CICM::AsymKey key_ref ); Initiate the import of key material via a key fill interface. Remarks: In some cases, a key fill device can initiate and effect the filling of key into a module completely independent of the host and thus any API control. In such cases, the host will utilize the CICM::AsymKeyManager::get_key_by_id, CICM::AsymKeyManager:: get_key_by_phys_location, or CICM::AsymKeyManager:: get_key_last_filled methods after the key fill has completed to enable future reference to the keyset. Keysets may be imported into a module as wrapped entities, necessitating the use of CICM::Key::unwrap to decrypt the key prior to use. Keyset attributes may optionally be set to create or supplement keyset metadata. Warning: This method MUST NOT be implemented if CICM::AsymKeyManager:: import_key_via_fill_into_phys_location is implemented. Parameters: [in] fill_port Fill port on which to initiate import. [out] key_ref Reference to newly imported keyset. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_KEY_MALFORMED, Lanz & Novikov Expires January 26, 2012 [Page 18] Internet-Draft CICM Key Management July 2011 S_KEY_METADATA_MALFORMED, S_KEY_FILL_DEVICE_NOT_CONNECTED, S_KEY_FILL_NOT_INITIATED, S_KEY_TRUST_ANCHOR, S_LOCAL_PORT_INVALID, S_LOCAL_PORT_INCOMPATIBLE, S_LOCAL_PORT_IN_USE, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT Method CICM::AsymKeyManager::import_key_via_fill_into_phys_location() CICM::Status import_key_via_fill_into_phys_location( in CICM::LocalPort fill_port, in CICM::UInt32 phys_location, out CICM::AsymKey key_ref ); Initiate the import of key material into a specific key physical location via a key fill interface. Remarks: In some cases, a key fill device can initiate and effect the filling of key into a module completely independent of the host and thus any API control. In such cases, the host will utilize the CICM::AsymKeyManager::get_key_by_id, CICM::AsymKeyManager:: get_key_by_phys_location, or CICM::AsymKeyManager:: get_key_last_filled methods after the key fill has completed to enable future reference to the keyset. Keysets may be imported into a module as wrapped entities, necessitating the use of CICM::Key::unwrap to decrypt the keyset prior to use. Keyset attributes may optionally be set to create or supplement keyset metadata. Warning: This call should only be used when a module utilizes a key storage model that requires keys of particular types to be stored in specific locations or in situations where keys are tied to module capabilities based upon physical location of the key. Because of the architectural knowledge of a module required, its use is highly discouraged because it virtually guarantees that code using it will be incompatible with other dissimilar modules. This method MUST NOT be implemented if CICM::AsymKeyManager:: import_key_via_fill is implemented. Parameters: Lanz & Novikov Expires January 26, 2012 [Page 19] Internet-Draft CICM Key Management July 2011 [in] fill_port Port of the key fill interface. [in] phys_location Physical location into which to import keyset. [out] key_ref Reference to newly imported keyset. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_KEY_PHYSICAL_LOC, S_KEY_MALFORMED, S_KEY_METADATA_MALFORMED, S_KEY_FILL_DEVICE_NOT_CONNECTED, S_KEY_FILL_NOT_INITIATED, S_KEY_TRUST_ANCHOR, S_LOCAL_PORT_INVALID, S_LOCAL_PORT_INCOMPATIBLE, S_LOCAL_PORT_IN_USE, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT Method CICM::AsymKeyManager::generate_key_pair() CICM::Status generate_key_pair( in CICM::AsymEncrAlgorithmId algorithm, out CICM::AsymKey key_ref ); Generate an asymmetric key pair compatible with the characteristics of the specified algorithm. Parameters: [in] algorithm Desired algorithm of resulting asymmetric key pair. [out] key_ref Reference to newly generated key pair. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_ALGO_INVALID, S_ALGO_INCOMPATIBLE, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT, S_INSUFFICIENT_ENTROPY Lanz & Novikov Expires January 26, 2012 [Page 20] Internet-Draft CICM Key Management July 2011 4.2. Interface CICM::AsymKey Interface CICM::AsymKey interface AsymKey : CICM::Key { CICM::AsymKey serves as an abstraction for an asymmetric keyset, which may comprise an asymmetric key pair, the public and private key components of a keypair, the digital certificate corresponding to the keyset public key, one or more verification certificates in the certificate chain of trust, and related public domain parameters; and supports operations on asymmetric keys, including wrapping and unwrapping. 4.2.1. CICM::AsymKey Inheritance CICM::AsymKey inherits from: CICM::Key. 4.2.2. CICM::AsymKey Types and Constants Type CICM::AsymKey::Usage typedef CICM::UInt32 Usage; Asymmetric key usage types. Constant CICM::AsymKey::C_USAGE_ASYM_DATA_ENCIPHERMENT const CICM::AsymKey::Usage C_USAGE_ASYM_DATA_ENCIPHERMENT = 0x00006001; Key intended for enciphering data. Constant CICM::AsymKey::C_USAGE_ASYM_KEY_ENCIPHERMENT const CICM::AsymKey::Usage C_USAGE_ASYM_KEY_ENCIPHERMENT = 0x00006002; Key intended for enciphering other keys. Constant CICM::AsymKey::C_USAGE_CERT_SIGN const CICM::AsymKey::Usage C_USAGE_CERT_SIGN = 0x00006004; Key intended for signing/verifying digital certificates. Constant CICM::AsymKey::C_USAGE_CRL_SIGN const CICM::AsymKey::Usage C_USAGE_CRL_SIGN = 0x00006007; Key intended for signing/verifying certificate revocation lists. Constant CICM::AsymKey::C_USAGE_DIGITAL_SIGNATURE const CICM::AsymKey::Usage C_USAGE_DIGITAL_SIGNATURE = 0x00006008; Key intended for producing digital signatures. Lanz & Novikov Expires January 26, 2012 [Page 21] Internet-Draft CICM Key Management July 2011 Constant CICM::AsymKey::C_USAGE_INFRA_KEY_AGREEMENT const CICM::AsymKey::Usage C_USAGE_INFRA_KEY_AGREEMENT = 0x0000600B; Key intended for participating in an infrastructure key agreement protocol. Constant CICM::AsymKey::C_USAGE_P2P_KEY_AGREEMENT const CICM::AsymKey::Usage C_USAGE_P2P_KEY_AGREEMENT = 0x0000600D; Key intended for participating in a peer-to-peer key agreement protocol. Constant CICM::AsymKey::C_USAGE_SEED const CICM::AsymKey::Usage C_USAGE_SEED = 0x0000600E; Key intended to serve as seed material. 4.2.3. CICM::AsymKey Methods Method CICM::AsymKey::wrap_and_copy() CICM::Status wrap_and_copy( in CICM::Key kek, in CICM::KeyWrapAlgorithmId algorithm, out CICM::AsymKey wrapped_key ); Instruct module to wrap keyset, resulting in two keysets, the original unwrapped keyset and the newly wrapped keyset. Parameters: [in] kek Reference to key encryption key. [in] algorithm Key wrap algorithm/mode used to wrap keyset. [out] wrapped_key Reference to resulting wrapped keyset. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_KEY_USED_INVALID, S_KEY_USED_EXPIRED, S_KEY_USED_CLASSIFICATION, S_KEY_USED_WRAPPED, S_KEY_USED_CONTEXT, S_KEY_USED_COMPONENT_NOT_AVAIL, S_KEY_INVALID, S_KEY_EXPIRED, S_KEY_INCOMPATIBLE, S_KEY_CLASSIFICATION, S_KEY_WRAPPED, S_KEY_NOT_WRAPPABLE, S_KEY_WRAPPED_EXISTS, S_ALGO_INVALID, S_ALGO_INCOMPATIBLE, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT Lanz & Novikov Expires January 26, 2012 [Page 22] Internet-Draft CICM Key Management July 2011 See also: CICM::SymKey::wrap_and_copy for the symmetric version of this method. Method CICM::AsymKey::unwrap_and_copy() CICM::Status unwrap_and_copy( in CICM::Key kek, in CICM::KeyWrapAlgorithmId algorithm, out CICM::AsymKey unwrapped_key ); Instruct module to unwrap key, resulting in two keys, the original wrapped key and the newly unwrapped key. Parameters: [in] kek Reference to key decryption key. [in] algorithm Key wrap algorithm/mode used to unwrap keyset. [out] unwrapped_key Reference to resulting unwrapped keyset. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_KEY_USED_INVALID, S_KEY_USED_EXPIRED, S_KEY_USED_CLASSIFICATION, S_KEY_USED_WRAPPED, S_KEY_USED_CONTEXT, S_KEY_USED_COMPONENT_NOT_AVAIL, S_KEY_INVALID, S_KEY_EXPIRED, S_KEY_INCOMPATIBLE, S_KEY_CLASSIFICATION, S_KEY_UNWRAPPED_EXISTS, S_KEY_MALFORMED, S_KEY_METADATA_MALFORMED, S_ALGO_INVALID, S_ALGO_INCOMPATIBLE, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT See also: CICM::SymKey::unwrap_and_copy for the symmetric version of this method. Lanz & Novikov Expires January 26, 2012 [Page 23] Internet-Draft CICM Key Management July 2011 Method CICM::AsymKey::validate_key_usage() CICM::Status validate_key_usage( in CICM::AsymKey::Usage usage_type, out CICM::Key::UsageStatus valid ); Validate that this keyset may be used for a specific purpose. Remarks: In some cases, a given keyset can be used for multiple purposes. Parameters: [in] usage_type Specific purpose to validate. [out] valid Indiciates whether or not the key may be used for the specified purpose. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_KEY_INVALID, S_KEY_EXPIRED, S_KEY_WRAPPED, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT See also: CICM::SymKey::validate_key_usage for the symmetric version of this method. 4.3. Interface CICM::AsymKeyIterator Interface CICM::AsymKeyIterator interface AsymKeyIterator : CICM::Iterator { CICM::AsymKeyIterator supports retrieving a reference to each usable asymmetric key on a module. CICM::AsymKeyIterator constructs the CICM::AsymKey interface. 4.3.1. CICM::AsymKeyIterator Inheritance CICM::AsymKeyIterator inherits from: CICM::Iterator. Lanz & Novikov Expires January 26, 2012 [Page 24] Internet-Draft CICM Key Management July 2011 4.3.2. CICM::AsymKeyIterator Methods Method CICM::AsymKeyIterator::get_next() CICM::Status get_next( out CICM::AsymKey asym_key_ref ); Returns a reference to the next asymmetric key. Remarks: Use CICM::Iterator::has_next to determine if additional elements exist. Parameters: [out] asym_key_ref Reference to next asymmetric key. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT 5. Symmetric Keys 5.1. Interface CICM::SymKeyManager Interface CICM::SymKeyManager interface SymKeyManager { CICM::SymKeyManager supports retrieving, importing, generating and deriving symmetric keys; and operating key management protocols. It is accessed from CICM::CryptoModule via the CICM::CryptoModule:: sym_key_manager attribute. CICM::SymKeyManager constructs the CICM:: KeyProtocolSender, CICM::KeyProtocolReceiver, CICM::SymKeyIterator, and CICM::SymKey interfaces. 5.1.1. CICM::SymKeyManager Attributes AttributeCICM::SymKeyManager::symkey_iterator readonly attribute CICM::SymKeyIterator symkey_iterator; Returns an iterator to enable a reference to each symmetric key in the module key database to be retrieved. Remarks: Lanz & Novikov Expires January 26, 2012 [Page 25] Internet-Draft CICM Key Management July 2011 The returned iterator is set to the beginning of the iterated sequence. AttributeCICM::SymKeyManager::key_protocol_sender readonly attribute CICM::KeyProtocolSender key_protocol_sender; CICM::KeyProtocolSender supports sending key management protocol- related messages into a module. AttributeCICM::SymKeyManager::key_protocol_receiver readonly attribute CICM::KeyProtocolReceiver key_protocol_receiver; CICM::KeyProtocolReceiver supports receiving key management protocol- related messages from a module. CICM::KeyProtocolReceiver constructs the CICM::SymKey interface. 5.1.2. CICM::SymKeyManager Methods Method CICM::SymKeyManager::get_key_by_id() CICM::Status get_key_by_id( in CICM::KeyId key_id, out CICM::SymKey key_ref ); Retrieves a reference to the symmetric key corresponding to the specified infrastructure-specific identifier. Warning: This method MUST NOT be implemented if CICM::SymKeyManager:: get_key_by_phys_location is implemented. Parameters: [in] key_id Unique identifier of the key to be retrieved. [out] key_ref Reference to key corresponding to key identifier. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_NOT_AVAILABLE, S_KEY_INVALID, S_KEY_EXPIRED, S_KEY_INVALID_ID, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT Lanz & Novikov Expires January 26, 2012 [Page 26] Internet-Draft CICM Key Management July 2011 Method CICM::SymKeyManager::get_key_by_phys_location() CICM::Status get_key_by_phys_location( in CICM::UInt32 phys_location, out CICM::SymKey key_ref ); Retrieves a reference to the symmetric key corresponding to the specified module physical storage location. Warning: This call should only be used when a module utilizes a key storage model that requires keys of particular types to be stored in specific locations or in situations where keys are tied to module capabilities based upon physical location of the key. Because of the architectural knowledge of a module required, its use is highly discouraged because it virtually guarantees that code using it will be incompatible with other dissimilar modules. This method MUST NOT be implemented if CICM::SymKeyManager:: get_key_by_id is implemented. Parameters: [in] phys_location Physical location of the key to be retrieved. [out] key_ref Reference to key corresponding to physical location. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_NOT_AVAILABLE, S_KEY_INVALID, S_KEY_EXPIRED, S_KEY_PHYSICAL_LOC, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT Method CICM::SymKeyManager::get_key_last_filled() CICM::Status get_key_last_filled( out CICM::SymKey key_ref ); Retrieves a reference to the symmetric key corresponding to the key most recently filled via a key fill device. Remarks: A client program may need to initiate this action if key material imported into a module does not contain the corresponding key metadata. This method allows a reference to the last key filled Lanz & Novikov Expires January 26, 2012 [Page 27] Internet-Draft CICM Key Management July 2011 over the key fill interface to be referenced to enable metadata to be applied directly to the resulting key. The error status CICM:: S_NOT_AVAILABLE is returned if no key is filled. Parameters: [out] key_ref Reference to last filled key. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_NOT_AVAILABLE, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT Method CICM::SymKeyManager::import_key() CICM::Status import_key( in CICM::Buffer key_material, out CICM::SymKey key_ref ); Import key material or seed key for pseudorandom data generation into a cryptographic module. Remarks: Keys may be imported into a module as wrapped entities, necessitating the use of CICM::Key::unwrap to decrypt the key prior to use. Key attributes may optionally be set to create or supplement key metadata. The format of the key material value is not defined by CICM. The Implementation Conformance Statement (see Conformance and Extensions in [CICM]) must reference a standard format or define a module developer-specific format implemented by the module for this datatype. Warning: This method MUST NOT be implemented if CICM::SymKeyManager:: import_key_into_phys_location is implemented. Parameters: [in] key_material Key material to be imported into the module. Lanz & Novikov Expires January 26, 2012 [Page 28] Internet-Draft CICM Key Management July 2011 [out] key_ref Reference to newly imported key. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_KEY_MALFORMED, S_KEY_METADATA_MALFORMED, S_KEY_TRUST_ANCHOR, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT Method CICM::SymKeyManager::import_key_into_phys_location() CICM::Status import_key_into_phys_location( in CICM::Buffer key_material, in CICM::UInt32 phys_location, out CICM::SymKey key_ref ); Import key material or seed key for pseudorandom data generation into a specific physical key location in a cryptographic module. Remarks: Keys may be imported into a module as wrapped entities, necessitating the use of CICM::Key::unwrap to decrypt the key prior to use. Key attributes may optionally be set to create or supplement key metadata. The format of the key material value is not defined by CICM. The Implementation Conformance Statement (see Conformance and Extensions in [CICM]) must reference a standard format or define a module developer-specific format implemented by the module for this datatype. Warning: This call should only be used when a module utilizes a key storage model that requires keys of particular types to be stored in specific locations or in situations where keys are tied to module capabilities based upon physical location of the key. Because of the architectural knowledge of a module required, its use is highly discouraged because it virtually guarantees that code using it will be incompatible with other dissimilar modules. This method MUST NOT be implemented if CICM::SymKeyManager:: import_key is implemented. Lanz & Novikov Expires January 26, 2012 [Page 29] Internet-Draft CICM Key Management July 2011 Parameters: [in] key_material Key material to be imported into the module. [in] phys_location Physical location into which to import key. [out] key_ref Reference to newly imported key. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_KEY_PHYSICAL_LOC, S_KEY_MALFORMED, S_KEY_METADATA_MALFORMED, S_KEY_TRUST_ANCHOR, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT Method CICM::SymKeyManager::import_key_via_fill() CICM::Status import_key_via_fill( in CICM::LocalPort fill_port, out CICM::SymKey key_ref ); Initiate the import of key material via a key fill interface. Remarks: In some cases, a key fill device can initiate and effect the filling of key into a module completely independent of the host and thus any API control. In such cases, the host will utilize the CICM::SymKeyManager::get_key_by_id, CICM::SymKeyManager:: get_key_by_phys_location, or CICM::SymKeyManager:: get_key_last_filled methods after the key fill has completed to enable future reference to the key. Keys may be imported into a module as wrapped entities, necessitating the use of CICM::Key::unwrap to decrypt the key prior to use. Key attributes may optionally be set to create or supplement key metadata. Warning: This method MUST NOT be implemented if CICM::SymKeyManager:: import_key_via_fill_into_phys_location is implemented. Parameters: Lanz & Novikov Expires January 26, 2012 [Page 30] Internet-Draft CICM Key Management July 2011 [in] fill_port Port of the key fill interface. [out] key_ref Reference to newly imported key. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_KEY_MALFORMED, S_KEY_METADATA_MALFORMED, S_KEY_FILL_DEVICE_NOT_CONNECTED, S_KEY_FILL_NOT_INITIATED, S_KEY_TRUST_ANCHOR, S_LOCAL_PORT_INVALID, S_LOCAL_PORT_INCOMPATIBLE, S_LOCAL_PORT_IN_USE, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT Method CICM::SymKeyManager::import_key_via_fill_into_phys_location() CICM::Status import_key_via_fill_into_phys_location( in CICM::LocalPort fill_port, in CICM::UInt32 phys_location, out CICM::SymKey key_ref ); Initiate the import of key material into a specific key physical location via a key fill interface. Remarks: In some cases, a key fill device can initiate and effect the filling of key into a module completely independent of the host and thus any API control. In such cases, the host will utilize the CICM::SymKeyManager::get_key_by_id, CICM::SymKeyManager:: get_key_by_phys_location, or CICM::SymKeyManager:: get_key_last_filled methods after the key fill has completed to enable future reference to the key. Keys may be imported into a module as wrapped entities, necessitating the use of CICM::Key::unwrap to decrypt the key prior to use. Key attributes may optionally be set to create or supplement key metadata. Warning: This call should only be used when a module utilizes a key storage model that requires keys of particular types to be stored in specific locations or in situations where keys are tied to module capabilities based upon physical location of the key. Because of Lanz & Novikov Expires January 26, 2012 [Page 31] Internet-Draft CICM Key Management July 2011 the architectural knowledge of a module required, its use is highly discouraged because it virtually guarantees that code using it will be incompatible with other dissimilar modules. This method MUST NOT be implemented if CICM::SymKeyManager:: import_key_via_fill is implemented. Parameters: [in] fill_port Port of the key fill interface. [in] phys_location Physical location into which to import key. [out] key_ref Reference to newly imported key. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_KEY_PHYSICAL_LOC, S_KEY_MALFORMED, S_KEY_METADATA_MALFORMED, S_KEY_FILL_DEVICE_NOT_CONNECTED, S_KEY_FILL_NOT_INITIATED, S_KEY_TRUST_ANCHOR, S_LOCAL_PORT_INVALID, S_LOCAL_PORT_INCOMPATIBLE, S_LOCAL_PORT_IN_USE, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT Method CICM::SymKeyManager::generate_key() CICM::Status generate_key( in CICM::SymEncrAlgorithmId algorithm, out CICM::SymKey key_ref ) Generate a symmetric key compatible with the characteristics of the specified algorithm. Parameters: [in] algorithm Desired algorithm of resulting symmetric key. [out] key_ref Reference to newly generated key. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_ALGO_INVALID, S_ALGO_INCOMPATIBLE, S_TOKEN_NOT_PRESENT, Lanz & Novikov Expires January 26, 2012 [Page 32] Internet-Draft CICM Key Management July 2011 S_TOKEN_ADMIN_NOT_PRESENT, S_INSUFFICIENT_ENTROPY Method CICM::SymKeyManager::derive_key() CICM::Status derive_key( in CICM::CharString password, in CICM::Buffer salt, in CICM::UInt32 iteration_count, in CICM::HashAlgorithmId hash_algorithm, in CICM::SymEncrAlgorithmId algorithm, out CICM::SymKey key_ref ); Derives a symmetric key from a password and other parameters using a password-based key derivation function (PBKDF). Parameters: [in] password Password for conversion into a cryptographic key. [in] salt Binary salt value. [in] iteration_count Positive integer representing number of iterations to apply to hashing algorithm. [in] hash_algorithm Hash function applied to derive key. [in] algorithm Desired algorithm/mode of resulting symmetric key. [out] key_ref Reference to newly derived key. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_ALGO_INVALID, S_ALGO_INCOMPATIBLE, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT, S_PASSWORD_INVALID, S_PASSWORD_INVALID_CHAR, S_PASSWORD_INVALID_LEN, S_SALT_INVALID, S_ITERATION_COUNT_INVALID Lanz & Novikov Expires January 26, 2012 [Page 33] Internet-Draft CICM Key Management July 2011 Method CICM::SymKeyManager::derive_deterministic_key() CICM::Status derive_deterministic_key( in CICM::SymKey key_prod_key, in CICM::CharString shared_secret, in CICM::SymEncrAlgorithmId algorithm, out CICM::SymKey key_ref ); Derives a symmetric key using a distributed deterministic key generation scheme. Remarks: This may be used by peers in an ad-hoc group who initially only share a key production key (KPK) but are subsequently able to share an additional secret. Parameters: [in] key_prod_key Key production key. [in] shared_secret Text-based secret sharable amongst peers in a group. [in] algorithm Desired algorithm/mode of resulting symmetric key. [out] key_ref Reference to newly derived key. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_KEY_USED_INVALID, S_KEY_USED_EXPIRED, S_KEY_USED_CLASSIFICATION, S_KEY_USED_WRAPPED, S_KEY_USED_CONTEXT, S_KEY_USED_COMPONENT_NOT_AVAIL, S_ALGO_INVALID, S_ALGO_INCOMPATIBLE, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT, S_PASSWORD_INVALID, S_PASSWORD_INVALID_CHAR, S_PASSWORD_INVALID_LEN 5.2. Interface CICM::SymKey Interface CICM::SymKey interface SymKey : CICM::Key { CICM::SymKey serves as a reference to a symmetric key contained within a module and supports operations on symmetric keys, including key conversion, updating, wrapping, and unwrapping. Lanz & Novikov Expires January 26, 2012 [Page 34] Internet-Draft CICM Key Management July 2011 5.2.1. CICM::SymKey Inheritance CICM::SymKey inherits from: CICM::Key. 5.2.2. CICM::SymKey Types and Constants Type CICM::SymKey::Usage typedef CICM::UInt32 Usage; Symmetric key usage types. Constant CICM::SymKey::C_USAGE_GENERATE_KEYSTREAM const CICM::SymKey::Usage C_USAGE_GENERATE_KEYSTREAM = 0x0000601A; Key intended for generating keystream. Constant CICM::SymKey::C_USAGE_KEY_PRODUCTION_KEY const CICM::SymKey::Usage C_USAGE_KEY_PRODUCTION_KEY = 0x0000601C; Key intended for producing other keys. Constant CICM::SymKey::C_USAGE_MESSAGE_AUTHENTICATION_CODE const CICM::SymKey::Usage C_USAGE_MESSAGE_AUTHENTICATION_CODE = 0x0000601F; Key intended for computing a Message Authentication Code. Constant CICM::SymKey::C_USAGE_SYM_DATA_ENCIPHERMENT const CICM::SymKey::Usage C_USAGE_SYM_DATA_ENCIPHERMENT = 0x00006020; Key intended for enciphering data. Constant CICM::SymKey::C_USAGE_SYM_KEY_ENCIPHERMENT const CICM::SymKey::Usage C_USAGE_SYM_KEY_ENCIPHERMENT = 0x00006023; Key intended for enciphering other keys. 5.2.3. CICM::SymKey Attributes Attribute CICM::SymKey::update_count readonly attribute CICM::UInt32 update_count; Key update count. Lanz & Novikov Expires January 26, 2012 [Page 35] Internet-Draft CICM Key Management July 2011 5.2.4. CICM::SymKey Methods Method CICM::SymKey::update() CICM::Status update(); Cryptographically update the key using the key's native algorithm. The update modifies the existing key. Remarks: The new update count resulting from a call to this method is available as an attribute of the key object. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_KEY_INVALID, S_KEY_EXPIRED, S_KEY_INCOMPATIBLE, S_KEY_WRAPPED, S_KEY_UPDATE_MAX, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT See also: CICM::SymKey::update_with_algo for the version of this method that accepts an algorithm parameter. Method CICM::SymKey::update_with_algo() CICM::Status update_with_algo( in CICM::SymEncrAlgorithmId algorithm ); Cryptographically update the key using the specified key update algorithm. The update modifies the existing key. Remarks: The new update count resulting from a call to this method is available as an attribute of the key object. Parameters: [in] algorithm Cryptographic algorithm/mode to use to effect the key update. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, Lanz & Novikov Expires January 26, 2012 [Page 36] Internet-Draft CICM Key Management July 2011 S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_KEY_INVALID, S_KEY_EXPIRED, S_KEY_INCOMPATIBLE, S_KEY_WRAPPED, S_KEY_UPDATE_MAX, S_ALGO_INVALID, S_ALGO_INCOMPATIBLE, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT See also: CICM::SymKey::update for the version of this method that does not require an algorithm to be specified. Method CICM::SymKey::wrap_and_copy() CICM::Status wrap_and_copy( in CICM::Key kek, in CICM::KeyWrapAlgorithmId algorithm, out CICM::SymKey wrapped_key ); Instruct module to wrap key, resulting in two keys, the original unwrapped key and the newly wrapped key. Parameters: [in] kek Reference to key encryption key. [in] algorithm Key wrap algorithm/mode used to wrap key. [out] wrapped_key Reference to resulting wrapped key. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_KEY_USED_INVALID, S_KEY_USED_EXPIRED, S_KEY_USED_CLASSIFICATION, S_KEY_USED_WRAPPED, S_KEY_USED_CONTEXT, S_KEY_USED_COMPONENT_NOT_AVAIL, S_KEY_INVALID, S_KEY_EXPIRED, S_KEY_INCOMPATIBLE, S_KEY_CLASSIFICATION, S_KEY_WRAPPED, S_KEY_NOT_WRAPPABLE, S_KEY_WRAPPED_EXISTS, S_ALGO_INVALID, S_ALGO_INCOMPATIBLE, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT See also: CICM::AsymKey::wrap_and_copy for the asymmetric version of this method. Lanz & Novikov Expires January 26, 2012 [Page 37] Internet-Draft CICM Key Management July 2011 Method CICM::SymKey::unwrap_and_copy() CICM::Status unwrap_and_copy( in CICM::Key kek, in CICM::KeyWrapAlgorithmId algorithm, out CICM::SymKey unwrapped_key ); Instruct module to unwrap key, resulting in two keys, the original wrapped key and the newly unwrapped key. Parameters: [in] kek Reference to key decryption key. [in] algorithm Key wrap algorithm/mode used to unwrap key. [out] unwrapped_key Reference to resulting unwrapped key. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_KEY_USED_INVALID, S_KEY_USED_EXPIRED, S_KEY_USED_CLASSIFICATION, S_KEY_USED_WRAPPED, S_KEY_USED_CONTEXT, S_KEY_USED_COMPONENT_NOT_AVAIL, S_KEY_INVALID, S_KEY_EXPIRED, S_KEY_INCOMPATIBLE, S_KEY_CLASSIFICATION, S_KEY_UNWRAPPED_EXISTS, S_KEY_MALFORMED, S_KEY_METADATA_MALFORMED, S_ALGO_INVALID, S_ALGO_INCOMPATIBLE, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT See also: CICM::AsymKey::unwrap_and_copy for the asymmetric version of this method. Method CICM::SymKey::validate_key_usage() CICM::Status validate_key_usage( in CICM::SymKey::Usage usage_type, out CICM::Key::UsageStatus valid ); Validate that this key may be used for a specific purpose. Remarks: In some cases, a given key can be used for multiple purposes. Parameters: Lanz & Novikov Expires January 26, 2012 [Page 38] Internet-Draft CICM Key Management July 2011 [in] usage_type Specific purpose to validate. [out] valid Indiciates if the key may be used for the specified purpose. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_KEY_INVALID, S_KEY_EXPIRED, S_KEY_WRAPPED, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT See also: CICM::AsymKey::validate_key_usage for the asymmetric version of this method. 5.3. Interface CICM::SymKeyIterator Interface CICM::SymKeyIterator interface SymKeyIterator : CICM::Iterator { CICM::SymKeyIterator supports retrieving a reference to each usable symmetric key on a module. CICM::SymKeyIterator constructs the CICM::SymKey interface. 5.3.1. CICM::SymKeyIterator Inheritance CICM::SymKeyIterator inherits from: CICM::Iterator. 5.3.2. CICM::SymKeyIterator Methods Method CICM::SymKeyIterator::get_next() CICM::Status get_next( out CICM::SymKey sym_key_ref ); Returns a reference to the next symmetric key. Remarks: Use CICM::Iterator::has_next to determine if additional elements exist. Parameters: [out] sym_key_ref Reference to next symmetric key. Lanz & Novikov Expires January 26, 2012 [Page 39] Internet-Draft CICM Key Management July 2011 Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT 6. Key Protocol The key management capabilities described here support certain key management protocols, including key establishment/distribution protocols such as Diffie-Hellman, EC-DH, and EC-MQV; trust anchor management protocols; the importation of key white lists (acceptable keys) or black lists (revoked keys or keys restricted administratively); and the execution of remote key functions. These key protocol IDL interfaces initiate a key agreement protocol between two or more entities to establish a secret key over an insecure communications channel. CICM channel negotiators (CICM::Negotiator) similarly initiate a key agreement protocol with a remote entity, but this typically results in an ephemeral key, in contrast to these key protocol interfaces which result in a persistent symmetric key that can be used by a variety of key management and channel management functions. For the purposes of these key protocol-related interfaces, a client program using the CICM API is only an intermediary in a key management protocol being conducted between a cryptographic module and other participants in a protocol session. In this role, a client program determines which module(s) should be involved and conveys the protocol messages, but otherwise does not participate in the protocol session. The client may be responsible for determining which key agreement protocol to use as well as for the reliable transport of messages passed between the peer entities. The interactions that comprise a protocol session in its entirety may entail a number of exchanges among the participants in the protocol. Any results from calls to key protocol methods during the course of the protocol exchange must be communicated to the appropriate peer entity by the caller. The progress, success, or failure of the protocol session is determined by the modules and other active participants in the interaction. CICM key protocol functionality is exported via two independent objects: CICM::KeyProtocolSender for protocol messages inbound to the module and CICM::KeyProtocolReceiver for messages outbound from the module. Access to each respective object is available via CICM:: SymKeyManager::key_protocol_sender and CICM::SymKeyManager:: Lanz & Novikov Expires January 26, 2012 [Page 40] Internet-Draft CICM Key Management July 2011 key_protocol_receiver. The key protocol methods support protocol sessions that may be long- term interactions potentially extending over several invocations of the controlling client program. To allow for this possibility, KeyProtocolReceiver::get_from_module may be used to "query" a module to determine if a response is ready and, if so, to retrieve response traffic (including current session status information) from the module. Thus, a single response from the module may take the form of a number of queries by the client program, with any productive response deferred until the module is ready: query, response is C_PROTOCOL_RECEIVE_BUSY query, response is C_PROTOCOL_RECEIVE_BUSY ... query, response is C_PROTOCOL_RECEIVE_BUSY query, results returned, response is C_PROTOCOL_RECEIVE_OKAY In the example above, the client program expects either a "condition" update from the module as part of the protocol session, or the most recent results from the active session. Thus, the client program queries the module periodically until it is ready to produce a response. The traffic relayed by these functions is part of a specific protocol session. The protocol governing this session is specified with the protocol parameter, either the value CICM::IMPLICIT_PROTOCOL_ID, denoting that the message itself indicates the protocol, or a unique protocol identifier designating the protocol directly. If the protocol parameter is CICM::IMPLICIT_PROTOCOL_ID but the message does not indicate the protocol, then the method fails, returning the CICM::S_PROTO_UNDETERMINED error status. The initial message in a protocol exchange can be generated either by the cryptographic module or some other party, including some party in a key management infrastructure or the client program itself. If the initial message is generated by the cryptographic module, a two-step process allows the message to be retrieved from the module: 1. The module notifies the client program that a protocol message is available to be retrieved via the CICM module event listener facility (this requires a CICM::ModuleEventListener:: C_MODULE_KEY_PROTO_MESSAGE to have been previously registered by the client program). The listener facility provides an opaque Lanz & Novikov Expires January 26, 2012 [Page 41] Internet-Draft CICM Key Management July 2011 buffer as part of the notification that is passed to the module in the following step to identify the specific protocol message involved. 2. The CICM::KeyProtocolReceiver::get_from_module method is used to retrieve the message from the module. If the initial message is generated by some other party, the CICM:: KeyProtocolSender::put_into_module method is used to convey the message into the module. Any key protocol-related key fill device interactions are outside the scope of the API. Individual protocol events do not require a transaction identifier. Instead, each message itself indicates where it is to be forwarded (i.e. which module or other participant is to receive the message). This means that the client program must be capable of determining which module to associate with a given message, possibly by examining metadata conveyed with the message. 6.1. Participants in the Interaction There are three types of participants in a protocol session using the key protocol functionality: o The cryptographic modules themselves. Note that although these methods work with modules individually, there may in fact be several modules involved in a single protocol session, e.g., to deliver the same key material to several modules available to a host or in a net. o The other participants (generally key management infrastructure components) that also take an active part in the session, i.e., those that generate and/or consume messages exchanged in the session (perhaps with status indications embedded in the messages). All active participants, to the extent they find necessary, maintain and update internal status as the session continues. o The intermediary client program that conveys the messages among the active participants in the session (the cryptographic modules themselves and the other active participants in the session). Note that a module may generate a message for transmission to another module as part of the protocol session. The CICM API is the interface between the intermediary client programs and the cryptographic modules. All exchanges for a specific Lanz & Novikov Expires January 26, 2012 [Page 42] Internet-Draft CICM Key Management July 2011 protocol session between a given module and other modules or other active participants (Party 1, ..., Party N) are mediated by the intermediary client program using CICM. Although the client program does not directly participate in the protocol session, the client program may be asked during the negotiation process to display identifying information about the remote party in the protocol to a human user who must determine if the remote party is the expected remote party in the protocol and, if so, must positively acknowledge this assertion to allow the protocol to continue. Some protocol sessions will not require this peer validation interaction (e.g., validation of the peer using a trust anchor is deemed sufficient or an external trusted display handles the user interaction). Except for recognizing the specific role of the cryptographic modules themselves, assignment of roles in the protocol to the active participants is out of scope for this document. 6.2. Return Status, Condition, and Session Status The key protocol interfaces convey messages between modules and the intermediary client program but do not conduct the actual protocol session. However, the client program still needs to know something about the state of the session, so the key protocol methods impart three types of status information: o Status return value indicates the status of the method call itself. In the event of a failure, it gives an indication of what the failure was. Note that the returned value does not indicate the state of the protocol session itself: It could report a faulty call (e.g., an invalid protocol identifier) even when the protocol session is still making progress, and it could report a successful exchange with the cryptographic module even when the module decides that the session has reached an error condition. o The returned condition indication summarizes for the client program the state of the session, perhaps to be used along with other information to suggest what the client program should do next as part of the current protocol session. o The current or resulting status of the protocol session is embedded in the message conveyed between the client program and the active participants. The client program typically will not interpret the contents of this message; instead, it will simply convey the message to the appropriate active participants, who may then interpret the status in the message and take the appropriate next step in the protocol. Lanz & Novikov Expires January 26, 2012 [Page 43] Internet-Draft CICM Key Management July 2011 6.3. Generic Scenario The following diagram presents a generic scenario for a key protocol session. This diagram does not show message exchanges with any other active participants, since they are out of scope for the API. Note that, although responses from the module to the intermediary client program are represented as arrows in the diagram, in fact, the module actually conveys the response only when the client program explicitly asks or is prompted by an event to ask for it. Intermediary Client Program Module | | | A1: start key protocol | |----------------------------------------------->| | | | M1: key protocol start C_PROTOCOL_SEND_OKAY | |<===============================================| | | | A2: send protocol message | |----------------------------------------------->| | | | M2: message C_PROTOCOL_SEND_OKAY, more pending | |<===============================================| | | ... (protocol continues) ... | | | An: send protocol message | |----------------------------------------------->| | Mn: message C_PROTOCOL_SEND_OKAY, protocol done| |<===============================================| | | Figure 1. Generic Scenario for Key Protocol Session Initiated by a Key Infrastructure Component The notional key infrastructure-initiated message exchanges are as follows: o Event "A1": Start key protocol - The client program receives the first protocol message from a key infrastructure component and sends it to the module using KeyProtocolSender::put_into_module. The returned condition indicates that the protocol session is C_PROTOCOL_SEND_OKAY. o Event "M1": Successful start to key protocol - The client program requests the module's response using KeyProtocolReceiver:: get_from_module. This response is the module's first message in this exchange and includes the current status of the session. Lanz & Novikov Expires January 26, 2012 [Page 44] Internet-Draft CICM Key Management July 2011 Multiple queries could respond with a BUSY condition before a C_PROTOCOL_SEND_OKAY condition is finally returned. The C_PROTOCOL_SEND_OKAY condition indicates that the session is in progress and a response message has been returned. The client program is responsible for forwarding the resulting response message to another active protocol participant. o Event "A2": Send protocol message - The client program forwards the next message in the protocol sequence received from the infrastructure component to the module using the KeyProtocolSender::put_into_module method. The returned condition indicates that the protocol session is C_PROTOCOL_SEND_OKAY. o Event "M2": Message C_PROTOCOL_SEND_OKAY, more pending - The module provides another message in this exchange using KeyProtocolReceiver::get_from_module. The returned condition indicates that the protocol session is C_PROTOCOL_SEND_OKAY and a responding message has been returned. o Event "An": Send protocol message - The client program forwards what is ultimately the last message in the protocol sequence to the module using KeyProtocolSender::put_into_module. o Event "Mn": Message C_PROTOCOL_SEND_OKAY, protocol done - The module provides the corresponding last message in this exchange when the client program queries the module using KeyProtocolReceiver::get_from_module. The returned condition indicates that the protocol session is DONE and the last responding message in this protocol session has been returned. As shown here, the module determines (or at least reports to the client program) when the protocol session is done. Another active participant could plausibly make this determination. 6.4. Key Agreement Example Using Diffie-Hellman Protocol The following example depicts a notional key infrastructure ("Entity A") initiating an authenticated Diffie-Hellman Discrete Logarithm (DH-DL) key agreement protocol with a cryptographic module ("Entity B"). A host running a client program using CICM for interactions with the module interposes itself between the key infrastructure and the module. Lanz & Novikov Expires January 26, 2012 [Page 45] Internet-Draft CICM Key Management July 2011 Entity A Client Key Protocol Key Protocol Entity B (g,p,certA) Program Sender Receiver (g,p,certB) | | | | | generates a | | | | | | | | | calculates | | | | A = g^a mod p | | | | | | | | | |[g,p,a,certA] | | | | |------------->| | | | | put_into_module([g,p,a,certA]) | | | |------------->| [g,p,a,certA] | | | |------------------------->| | | | ok | | | |<=========================| | C_PROTOCOL_SEND_OKAY | | | |<=============| | | | | get_from_module() | | | |--------------------------->| | | | | |----------->| | | | | | | | | | generates b | | | | | | | | | calculates | | | | B = g^b mod p | | | | | | | | | [B,certB] | | | [B,certB] |<===========| | [B,certB] |<===========================| | |<=============| | | | | | | | | calculates | | | calculates K = B^a mod p | | | K = A^b mod p | | | | | Figure 2. Example of a Two-key Diffie-Hellman Discrete Logarithm (DH-DL) Key Agreement Protocol Initiated by a Key Infrastructure The following are the steps required to use CICM in the protocol example between a notional key infrastructure ("Entity A") and a cryptographic module ("Entity B"): 1. The following are prepositioned at both communicating elements: * Domain parameters g and p. * Digital certificate. Lanz & Novikov Expires January 26, 2012 [Page 46] Internet-Draft CICM Key Management July 2011 * Signature verification key required to validate the certificate of the other entity. 2. "Entity A" generates random value a. 3. "Entity A" calculates A=g^a mod p. 4. "Entity A" signs the value A calculated above using its static private key whose corresponding static public key is contained in its certificate. 5. "Entity A" sends the signed value A and cert-A to the client program on the intermediary host as an opaque binary buffer. 6. The client program on the intermediary host calls KeyProtocolSender::put_into_module to send the opaque binary buffer received by the client program to the module; if a CICM:: KeyProtocolSender::C_PROTOCOL_SEND_DISPLAY condition is returned from this call, the following steps SHOULD be performed (the steps do not appear in the diagram): A. "Entity A" calls CICM::Negotiator::get_remote_info to retrieve information about the remote peer; this information (including name/organization and classification level) are extracted from cert-B and returned in CICM::PeerInfo. B. The client program on the intermediary host displays the identifying information returned above in CICM::PeerInfo to a human user and asks for positive acknowledgement that the entity initiating the protocol is in fact a legal entity to initiate the protocol. C. If the human user does not recognize the remote entity and declines to give positive acknowledgement, the client program abandons the protocol. In this example, positive acknowledgement is given, and the client program calls CICM::KeyProtocolReceiver::get_from_module to request a protocol response. 7. "Entity B" generates random value b. 8. "Entity B" calculates B=g^b mod p, using parameters g and p that it previously agreed it would use when initiating a protocol exchange with "Entity A." 9. "Entity B" signs the value B calculated above using its static private key whose corresponding static public key is contained in its certificate. Lanz & Novikov Expires January 26, 2012 [Page 47] Internet-Draft CICM Key Management July 2011 10. "Entity B" returns an opaque binary buffer containing its signed value B and cert-B to the caller of KeyProtocolReceiver:: get_from_module with a condition of DONE. 11. The client program on the intermediary host sends the opaque binary buffer to "Entity A". 12. Both entities verify their peer's certificate is valid. 13. "Entity A" calculates K=B^a mod p. 14. "Entity B" calculates K=A^b mod p. 15. Both entities now share a symmetric key K. 6.5. Protocol Support Examples As previously stated, these methods support a wide range of key management protocols. The following is a notional list of such protocols with a description of their intended usage: o Key agreement/distribution protocols - Key material can be distributed and keys can be agreed upon using the DH-DL, EC-DH, EC-MQV, or related protocols. o Remote key functions - Messages containing key-related commands (i.e., zeroize, rekey) requiring authentication by the module prior to execution may be presented using these functions. o Trust anchor management protocols - Trust anchor management commands and data may be sent as opaque data elements which are interpreted by the module in a protocol-specific manner. o Key revocation messages - Opaque data elements identifying certificates associated with keys which have been revoked or accepted. The ability to handle a list of revoked keys allows a module to prevent further usage of these keys, including performing key agreement with an entity that is known to have been compromised or no longer possesses the roles or affiliations described in the certificate. Lanz & Novikov Expires January 26, 2012 [Page 48] Internet-Draft CICM Key Management July 2011 6.6. Interface CICM::KeyProtocolSender Interface CICM::KeyProtocolSender interface KeyProtocolSender : CICM::Negotiator { CICM::KeyProtocolSender supports sending key management protocol- related messages into a module. 6.6.1. CICM::KeyProtocolSender Inheritance CICM::KeyProtocolSender inherits from: CICM::Negotiator. 6.6.2. CICM::KeyProtocolSender Types and Constants Type CICM::KeyProtocolSender::Condition typedef CICM::UInt32 Condition; Condition values summarize for the client program the state of the session. This information can be used along with other information to suggest what the client program should do next as part of the current protocol session. Constant CICM::KeyProtocolSender::C_PROTOCOL_SEND_OKAY const CICM::KeyProtocolSender::Condition C_PROTOCOL_SEND_OKAY = 0x00006045; Denotes that the session is in progress and a response message is available. Constant CICM::KeyProtocolSender::C_PROTOCOL_SEND_DONE const CICM::KeyProtocolSender::Condition C_PROTOCOL_SEND_DONE = 0x00006046; Denotes that the session terminated successfully. Constant CICM::KeyProtocolSender::C_PROTOCOL_SEND_ERROR const CICM::KeyProtocolSender::Condition C_PROTOCOL_SEND_ERROR = 0x00006049; Denotes that the session terminated with an error condition. Constant CICM::KeyProtocolSender::C_PROTOCOL_SEND_DISPLAY const CICM::KeyProtocolSender::Condition C_PROTOCOL_SEND_DISPLAY = 0x0000604A; As with the C_PROTOCOL_SEND_OKAY condition, denotes that the session is in progress and a response message is available, but additionally denotes that identification information extracted from the remote certificate is available via a call to the CICM::Negotiator:: get_remote_info method; the information retrieved from a call to this method must be displayed to a human user on the host and validated before the protocol should be allowed to continue. Note that a trusted display may be employed by the module for the same purpose but, because no API interaction would be involved, the Lanz & Novikov Expires January 26, 2012 [Page 49] Internet-Draft CICM Key Management July 2011 C_PROTOCOL_SEND_DISPLAY condition would not be returned. Constant CICM::KeyProtocolSender::C_PROTOCOL_SEND_ABORTED const CICM::KeyProtocolSender::Condition C_PROTOCOL_SEND_ABORTED = 0x0000604C; Denotes that the human user reviewing the remote peer information chose to reject it and abort the protocol. Constant CICM::KeyProtocolSender::C_PROTOCOL_SEND_MESSAGE_INVALID const CICM::KeyProtocolSender::Condition C_PROTOCOL_SEND_MESSAGE_INVALID = 0x0000604F; Denotes that the conveyed message was found to be invalid for the protocol. This event does not terminate the protocol session. Constant CICM::KeyProtocolSender::C_PROTOCOL_SEND_MESSAGE_INTEGRITY const CICM::KeyProtocolSender::Condition C_PROTOCOL_SEND_MESSAGE_INTEGRITY = 0x00006051; Denotes that the conveyed message failed one or more integrity checks used in the protocol. This event does not terminate the protocol session. Constant CICM::KeyProtocolSender::C_PROTOCOL_SEND_PROTOCOL_VIOLATION const CICM::KeyProtocolSender::Condition C_PROTOCOL_SEND_PROTOCOL_VIOLATION = 0x00006052; Denotes that a message or attempted action unexpected at the current point in the protocol session was noted. This event does not terminate the protocol session. 6.6.3. CICM::KeyProtocolSender Methods Method CICM::KeyProtocolSender::put_into_module() CICM::Status put_into_module( in CICM::ProtocolId protocol, in CICM::Buffer message, out CICM::KeyProtocolSender::Condition condition ); Initiate or recommence a key management protocol session, forwarding a message to the cryptographic module. If the C_PROTOCOL_SEND_DISPLAY condition results, the get_remote_info method should be called to retrieve identity information about the remote peer for display to and validation by the responsible user before the protocol negotiation is allowed to continue. Remarks: The format of the conveyed message is not defined by CICM. If the client program must be capable of generating the message, then the Implementation Conformance Statement (see Conformance and Lanz & Novikov Expires January 26, 2012 [Page 50] Internet-Draft CICM Key Management July 2011 Extensions in [CICM]) MUST reference a standard format or define a module developer-specific format implemented by the module for this datatype. Parameters: [in] protocol Designate the protocol to be followed for this session; the same value must be used for this parameter for all calls to this method or to get_from_module, as part of the same protocol session. [in] message Message conveyed to the module as part of the current protocol session. [out] condition Condition of the current protocol session; the calling client program must interpret this value to determine what its next action must be. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT, S_NEGOTIATION_ABORTED, S_NEGOTIATION_FAILURE, S_CERT_LOCAL_INVALID, S_CERT_LOCAL_EXPIRED, S_CERT_REMOTE_INVALID, S_CERT_REMOTE_EXPIRED, S_CERT_REMOTE_PATH, S_PROTO_INVALID, S_PROTO_INCOMPATIBLE, S_PROTO_UNDETERMINED See also: CICM::KeyProtocolSender::put_into_module_algo for the version of this method that accepts an algorithm. Method CICM::KeyProtocolSender::put_into_module_algo() CICM::Status put_into_module_algo( in CICM::ProtocolId protocol, in CICM::Buffer message, in CICM::SymEncrAlgorithmId algorithm, out CICM::KeyProtocolSender::Condition condition ); Initiate or recommence a key management protocol session, forwarding a message to the cryptographic module. If the C_PROTOCOL_SEND_DISPLAY condition results, the get_remote_info method should be called to retrieve identity information about the remote peer for display to and validation by the responsible user before the protocol negotiation is allowed to continue. This method differs from KeyProtocolSender::put_into_module in that it enables the caller Lanz & Novikov Expires January 26, 2012 [Page 51] Internet-Draft CICM Key Management July 2011 to specify the desired algorithm of the resulting symmetric key. Remarks: The format of the conveyed message is not defined by CICM. If the client program must be capable of generating the message, then the Implementation Conformance Statement (see Conformance and Extensions in [CICM]) MUST reference a standard format or define a module developer-specific format implemented by the module for this datatype. Parameters: [in] protocol Designate the protocol to be followed for this session; the same value must be used for this parameter for all calls to this method or to get_from_module, as part of the same protocol session. [in] message Message conveyed to the module as part of the current protocol session. [in] algorithm Algorithm/mode of resulting symmetric key. [out] condition Condition of the current protocol session; the calling client program must interpret this value to determine what its next action must be. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_ALGO_INVALID, S_ALGO_INCOMPATIBLE, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT, S_NEGOTIATION_ABORTED, S_NEGOTIATION_FAILURE, S_CERT_LOCAL_INVALID, S_CERT_LOCAL_EXPIRED, S_CERT_REMOTE_INVALID, S_CERT_REMOTE_EXPIRED, S_CERT_REMOTE_PATH, S_PROTO_INVALID, S_PROTO_INCOMPATIBLE, S_PROTO_UNDETERMINED See also: CICM::KeyProtocolSender::put_into_module for the version of this method that does not require an algorithm. Lanz & Novikov Expires January 26, 2012 [Page 52] Internet-Draft CICM Key Management July 2011 6.7. Interface CICM::KeyProtocolReceiver Interface CICM::KeyProtocolReceiver interface KeyProtocolReceiver { CICM::KeyProtocolReceiver supports receiving key management protocol- related messages from a module. CICM::KeyProtocolReceiver constructs the CICM::SymKey interface. 6.7.1. CICM::KeyProtocolReceiver Types and Constants Type CICM::KeyProtocolReceiver::Condition typedef CICM::UInt32 Condition; Condition values summarize for the client program the state of the session. This information can be used along with other information to suggest what the client program should do next as part of the current protocol session. Constant CICM::KeyProtocolReceiver::C_PROTOCOL_RECEIVE_OKAY const CICM::KeyProtocolReceiver::Condition C_PROTOCOL_RECEIVE_OKAY = 0x00006034; Denotes that the session is in progress and a response message has been returned. Constant CICM::KeyProtocolReceiver::C_PROTOCOL_RECEIVE_DONE const CICM::KeyProtocolReceiver::Condition C_PROTOCOL_RECEIVE_DONE = 0x00006037; Denotes that the session terminated successfully. Constant CICM::KeyProtocolReceiver::C_PROTOCOL_RECEIVE_BUSY const CICM::KeyProtocolReceiver::Condition C_PROTOCOL_RECEIVE_BUSY = 0x00006038; Denotes that the session is in progress but no response message or error indication is available at the current time; in this case, the client program must make additional calls to CICM:: KeyProtocolReceiver::get_from_module to determine when the response message has become available and retrieve the message. Constant CICM::KeyProtocolReceiver::C_PROTOCOL_RECEIVE_ERROR const CICM::KeyProtocolReceiver::Condition C_PROTOCOL_RECEIVE_ERROR = 0x0000603B; Denotes that the session terminated with an error condition and a response message has been returned. Lanz & Novikov Expires January 26, 2012 [Page 53] Internet-Draft CICM Key Management July 2011 Constant CICM::KeyProtocolReceiver::C_PROTOCOL_RECEIVE_ABORTED const CICM::KeyProtocolReceiver::Condition C_PROTOCOL_RECEIVE_ABORTED = 0x0000603D; Denotes that the human user reviewing the remote peer information chose to reject it and abort the protocol. Constant CICM::KeyProtocolReceiver:: C_PROTOCOL_RECEIVE_MESSAGE_INVALID const CICM::KeyProtocolReceiver::Condition C_PROTOCOL_RECEIVE_MESSAGE_INVALID = 0x0000603E; Denotes that the conveyed message was found to be invalid for the protocol. This event does not terminate the protocol session. Constant CICM::KeyProtocolReceiver:: C_PROTOCOL_RECEIVE_MESSAGE_INTEGRITY const CICM::KeyProtocolReceiver::Condition C_PROTOCOL_RECEIVE_MESSAGE_INTEGRITY = 0x00006040; Denotes that the conveyed message failed one or more integrity checks used in the protocol. This event does not terminate the protocol session. Constant CICM::KeyProtocolReceiver::C_PROTOCOL_RECEIVE_VIOLATION const CICM::KeyProtocolReceiver::Condition C_PROTOCOL_RECEIVE_VIOLATION = 0x00006043; Denotes that a message or attempted action unexpected at the current point in the protocol session was noted. This event does not terminate the protocol session. 6.7.2. CICM::KeyProtocolReceiver Methods Method CICM::KeyProtocolReceiver::abort() CICM::Status abort(); Abort negotiation. Remarks: This method may be called at any point in the negotiation process for any reason. However, it must be called in the event the identification information for the remote peer does not correspond to the expected peer. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT, S_NEGOTIATION_NOT_IN_PROGRESS Lanz & Novikov Expires January 26, 2012 [Page 54] Internet-Draft CICM Key Management July 2011 Method CICM::KeyProtocolReceiver::get_from_module() CICM::Status get_from_module( in CICM::ProtocolId protocol, out CICM::Buffer message, out CICM::KeyProtocolReceiver::Condition condition ); Initiate or recommence a key management protocol session, soliciting a response from the cryptographic module. Remarks: The format of the conveyed message is not defined by CICM. If the client program must be capable of interpreting the contents of the message, then the Implementation Conformance Statement (see Conformance and Extensions in [CICM]) MUST reference a standard format or define a module developer-specific format implemented by the module for this datatype. Parameters: [in] protocol Designate the protocol to be followed for this session; the same value must be used for this parameter for all calls to this method or to CICM::KeyProtocolSender:: put_into_module, as part of the same protocol session. [out] message Message returned from the module as part of the current protocol session; message may be of length zero. [out] condition Condition of the current protocol session; the calling client program must interpret this value to determine what its next action must be. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT, S_NEGOTIATION_ABORTED, S_NEGOTIATION_FAILURE, S_CERT_LOCAL_INVALID, S_CERT_LOCAL_EXPIRED, S_CERT_REMOTE_INVALID, S_CERT_REMOTE_EXPIRED, S_CERT_REMOTE_PATH, S_PROTO_INVALID, S_PROTO_INCOMPATIBLE, S_PROTO_UNDETERMINED Lanz & Novikov Expires January 26, 2012 [Page 55] Internet-Draft CICM Key Management July 2011 Method CICM::KeyProtocolReceiver::get_key() CICM::Status get_key( out CICM::SymKey key_ref ); At successful conclusion of a key agreement/distribution protocol session (when the returned condition is C_PROTOCOL_RECEIVE_DONE), this method is called to retrieve a reference to the key resulting from the session. Remarks: Note that, in those cases where the protocol session does not result in a key (e.g., a key revocation message, key white list or black list is presented to the module via this interface), calling this method will result in an CICM::S_INVALID_STATE error. Parameters: [out] key_ref Reference to key resulting from a successful protocol session. Returns: S_OK, S_GENERAL_ERROR, S_NON_FUNCTIONAL, S_OPERATION_FAILED, S_POLICY_VIOLATION, S_MODULE_RESOURCES, S_HOST_RESOURCES, S_INVALID_STATE, S_ALARM_STATE, S_MODULE_NOT_AVAILABLE, S_TIMEOUT, S_NOT_AUTHENTICATED, S_NOT_AUTHORIZED, S_TOKEN_NOT_PRESENT, S_TOKEN_ADMIN_NOT_PRESENT, S_NEGOTIATION_IN_PROGRESS, S_NEGOTIATION_NOT_IN_PROGRESS 7. IANA Considerations [RFC Editor: Please remove this section prior to publication.] This document has no IANA actions. 8. Security Considerations 8.1. Authorization The use of cryptographic key material is often limited to a set of authorized users. Authorization may be revoked by administrative means not defined by CICM or, in the extreme case, by zeroizing the key. The Key Protocol capabilities can also be used to manage key white Lanz & Novikov Expires January 26, 2012 [Page 56] Internet-Draft CICM Key Management July 2011 lists and black lists which may limit authorized access to cryptographic material. 8.2. Authentication The operations defined in this document require properly authorized and authenticated users in order to create, manage, import, export, or manipulate cryptographic key material. 8.3. Entity Authentication When using the Key Protocol mechanism, the module will typically authenticate that the party with which it is communicating is the party which is intended. When the module receives the certificate of the communicating party, this information is extracted and provided in a CICM::PeerInfo object which must be positively identified before the protocol continues forward. Key Protocol also provides the capability to store revocation lists which may prevent the module from performing key agreement with an entity that is known to have to have been compromised or no longer possesses the roles or affiliations described in the certificate. 8.4. Confidentiality A common use of cryptographic key material is to provide confidentiality between two communicating entities. See [CICM-CM] for the details of different confidential communications channels. 8.5. Data Integrity Asymmetric keys are often used to provide data integrity capabilities. See [CICM-CM] for channels that provide data integrity. 8.6. Inappropriate Usage CICM defines a set of error codes (S_KEY_USED_INVALID, S_KEY_USED_EXPIRED, S_KEY_USED_CLASSIFICATION, S_KEY_INVALID, S_KEY_EXPIRED, S_KEY_INCOMPATIBLE, S_KEY_CLASSIFICATION) to mitigate against the inappropriate key usage. Additionally, CICM provides the Key::state and Key::classification attributes as well as the SymKey::validate_key_usage() and AsymKey:: validate_key_usage() methods to provide information about the appropriate uses for each key. Lanz & Novikov Expires January 26, 2012 [Page 57] Internet-Draft CICM Key Management July 2011 9. References 9.1. Normative References [CICM] Lanz, D. and L. Novikov, "Common Interface to Cryptographic Modules (CICM) [RFC Editor: Please update the RFC reference and date prior to publication.]", January 2011. [CICM-CM] Lanz, D. and L. Novikov, "Common Interface to Cryptographic Modules (CICM) Channel Management [RFC Editor: Please update the RFC reference and date prior to publication.]", January 2011. [CICM-KM] Lanz, D. and L. Novikov, "Common Interface to Cryptographic Modules (CICM) Key Management [RFC Editor: Please update the RFC reference and date prior to publication.]", January 2011. [IDL] International Standards Organization, "Information technology -- Open Distributed Processing -- Interface Definition Language", ISO/IEC 14750:1999(E), March 1999. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. 9.2. Informative References [CICM-LM] Lanz, D. and L. Novikov, "Common Interface to Cryptographic Modules (CICM) Logical Model [RFC Editor: Please update the RFC reference and date prior to publication.]", January 2011. [CORBA] Object Management Group, "Common Object Request Broker Architecture (CORBA) Specification, Version 3.1", January 2008. [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC Text on Security Considerations", BCP 72, RFC 3552, July 2003. Appendix A. IDL Definitions module CICM { typedef CICM::CharString KeyId; interface Key { typedef CICM::UInt32 State; Lanz & Novikov Expires January 26, 2012 [Page 58] Internet-Draft CICM Key Management July 2011 const CICM::Key::State C_KEY_INVALID = 0x00006010; const CICM::Key::State C_KEY_VALID_WRAPPED = 0x00006013; const CICM::Key::State C_KEY_VALID_UNWRAPPED = 0x00006015; typedef CICM::UInt32 UsageStatus; const CICM::Key::UsageStatus C_KEY_USAGE_ALLOWED = 0x00006016; const CICM::Key::UsageStatus C_KEY_USAGE_FORBIDDEN = 0x00006019; attribute CICM::CharString identifier; attribute CICM::UInt32 location; attribute CICM::CharString alias; attribute CICM::Classification classification; attribute CICM::CharString caveat; attribute CICM::CharString authority; readonly attribute CICM::Key::State state; CICM::Status wrap( in CICM::Key kek, in CICM::KeyWrapAlgorithmId algorithm ); CICM::Status unwrap( in CICM::Key kek, in CICM::KeyWrapAlgorithmId algorithm ); CICM::Status export( out CICM::Buffer key_material ); CICM::Status export_via_fill_interface( in CICM::LocalPort fill_port ); CICM::Status zeroize(); }; interface SymKey : CICM::Key { typedef CICM::UInt32 Usage; const CICM::SymKey::Usage C_USAGE_GENERATE_KEYSTREAM = 0x0000601A; const CICM::SymKey::Usage C_USAGE_KEY_PRODUCTION_KEY = 0x0000601C; const CICM::SymKey::Usage C_USAGE_MESSAGE_AUTHENTICATION_CODE = 0x0000601F; const CICM::SymKey::Usage C_USAGE_SYM_DATA_ENCIPHERMENT = 0x00006020; const CICM::SymKey::Usage Lanz & Novikov Expires January 26, 2012 [Page 59] Internet-Draft CICM Key Management July 2011 C_USAGE_SYM_KEY_ENCIPHERMENT = 0x00006023; readonly attribute CICM::UInt32 update_count; CICM::Status update(); CICM::Status update_with_algo( in CICM::SymEncrAlgorithmId algorithm ); CICM::Status wrap_and_copy( in CICM::Key kek, in CICM::KeyWrapAlgorithmId algorithm, out CICM::SymKey wrapped_key ); CICM::Status unwrap_and_copy( in CICM::Key kek, in CICM::KeyWrapAlgorithmId algorithm, out CICM::SymKey unwrapped_key ); CICM::Status validate_key_usage( in CICM::SymKey::Usage usage_type, out CICM::Key::UsageStatus valid ); }; interface AsymKey : CICM::Key { typedef CICM::UInt32 Usage; const CICM::AsymKey::Usage C_USAGE_ASYM_DATA_ENCIPHERMENT = 0x00006001; const CICM::AsymKey::Usage C_USAGE_ASYM_KEY_ENCIPHERMENT = 0x00006002; const CICM::AsymKey::Usage C_USAGE_CERT_SIGN = 0x00006004; const CICM::AsymKey::Usage C_USAGE_CRL_SIGN = 0x00006007; const CICM::AsymKey::Usage C_USAGE_DIGITAL_SIGNATURE = 0x00006008; const CICM::AsymKey::Usage C_USAGE_INFRA_KEY_AGREEMENT = 0x0000600B; const CICM::AsymKey::Usage C_USAGE_P2P_KEY_AGREEMENT = 0x0000600D; const CICM::AsymKey::Usage Lanz & Novikov Expires January 26, 2012 [Page 60] Internet-Draft CICM Key Management July 2011 C_USAGE_SEED = 0x0000600E; CICM::Status wrap_and_copy( in CICM::Key kek, in CICM::KeyWrapAlgorithmId algorithm, out CICM::AsymKey wrapped_key ); CICM::Status unwrap_and_copy( in CICM::Key kek, in CICM::KeyWrapAlgorithmId algorithm, out CICM::AsymKey unwrapped_key ); CICM::Status validate_key_usage( in CICM::AsymKey::Usage usage_type, out CICM::Key::UsageStatus valid ); }; interface SymKeyIterator : CICM::Iterator { CICM::Status get_next( out CICM::SymKey sym_key_ref ); }; interface AsymKeyIterator : CICM::Iterator { CICM::Status get_next( out CICM::AsymKey asym_key_ref ); }; interface KeyProtocolSender : CICM::Negotiator { typedef CICM::UInt32 Condition; const CICM::KeyProtocolSender::Condition C_PROTOCOL_SEND_OKAY = 0x00006045; const CICM::KeyProtocolSender::Condition C_PROTOCOL_SEND_DONE = 0x00006046; const CICM::KeyProtocolSender::Condition C_PROTOCOL_SEND_ERROR = 0x00006049; const CICM::KeyProtocolSender::Condition C_PROTOCOL_SEND_DISPLAY = 0x0000604A; const CICM::KeyProtocolSender::Condition C_PROTOCOL_SEND_ABORTED = 0x0000604C; const CICM::KeyProtocolSender::Condition C_PROTOCOL_SEND_MESSAGE_INVALID = 0x0000604F; Lanz & Novikov Expires January 26, 2012 [Page 61] Internet-Draft CICM Key Management July 2011 const CICM::KeyProtocolSender::Condition C_PROTOCOL_SEND_MESSAGE_INTEGRITY = 0x00006051; const CICM::KeyProtocolSender::Condition C_PROTOCOL_SEND_PROTOCOL_VIOLATION = 0x00006052; CICM::Status put_into_module( in CICM::ProtocolId protocol, in CICM::Buffer message, out CICM::KeyProtocolSender::Condition condition ); CICM::Status put_into_module_algo( in CICM::ProtocolId protocol, in CICM::Buffer message, in CICM::SymEncrAlgorithmId algorithm, out CICM::KeyProtocolSender::Condition condition ); }; interface KeyProtocolReceiver { typedef CICM::UInt32 Condition; const CICM::KeyProtocolReceiver::Condition C_PROTOCOL_RECEIVE_OKAY = 0x00006034; const CICM::KeyProtocolReceiver::Condition C_PROTOCOL_RECEIVE_DONE = 0x00006037; const CICM::KeyProtocolReceiver::Condition C_PROTOCOL_RECEIVE_BUSY = 0x00006038; const CICM::KeyProtocolReceiver::Condition C_PROTOCOL_RECEIVE_ERROR = 0x0000603B; const CICM::KeyProtocolReceiver::Condition C_PROTOCOL_RECEIVE_ABORTED = 0x0000603D; const CICM::KeyProtocolReceiver::Condition C_PROTOCOL_RECEIVE_MESSAGE_INVALID = 0x0000603E; const CICM::KeyProtocolReceiver::Condition C_PROTOCOL_RECEIVE_MESSAGE_INTEGRITY = 0x00006040; const CICM::KeyProtocolReceiver::Condition C_PROTOCOL_RECEIVE_VIOLATION = 0x00006043; CICM::Status abort(); CICM::Status get_from_module( Lanz & Novikov Expires January 26, 2012 [Page 62] Internet-Draft CICM Key Management July 2011 in CICM::ProtocolId protocol, out CICM::Buffer message, out CICM::KeyProtocolReceiver::Condition condition ); CICM::Status get_key( out CICM::SymKey key_ref ); }; interface SymKeyManager { readonly attribute CICM::SymKeyIterator symkey_iterator; readonly attribute CICM::KeyProtocolSender key_protocol_sender; readonly attribute CICM::KeyProtocolReceiver key_protocol_receiver; CICM::Status get_key_by_id( in CICM::KeyId key_id, out CICM::SymKey key_ref ); CICM::Status get_key_by_phys_location( in CICM::UInt32 phys_location, out CICM::SymKey key_ref ); CICM::Status get_key_last_filled( out CICM::SymKey key_ref ); CICM::Status import_key( in CICM::Buffer key_material, out CICM::SymKey key_ref ); CICM::Status import_key_into_phys_location( in CICM::Buffer key_material, in CICM::UInt32 phys_location, out CICM::SymKey key_ref ); CICM::Status import_key_via_fill( in CICM::LocalPort fill_port, out CICM::SymKey key_ref ); CICM::Status import_key_via_fill_into_phys_location( in CICM::LocalPort fill_port, in CICM::UInt32 phys_location, out CICM::SymKey key_ref ); CICM::Status generate_key( in CICM::SymEncrAlgorithmId algorithm, out CICM::SymKey key_ref ); CICM::Status derive_key( in CICM::CharString password, Lanz & Novikov Expires January 26, 2012 [Page 63] Internet-Draft CICM Key Management July 2011 in CICM::Buffer salt, in CICM::UInt32 iteration_count, in CICM::HashAlgorithmId hash_algorithm, in CICM::SymEncrAlgorithmId algorithm, out CICM::SymKey key_ref ); CICM::Status derive_deterministic_key( in CICM::SymKey key_prod_key, in CICM::CharString shared_secret, in CICM::SymEncrAlgorithmId algorithm, out CICM::SymKey key_ref ); }; interface AsymKeyManager { readonly attribute CICM::AsymKeyIterator asymkey_iterator; CICM::Status get_key_by_id( in CICM::KeyId key_id, out CICM::AsymKey key_ref ); CICM::Status get_key_by_phys_location( in CICM::UInt32 phys_location, out CICM::AsymKey key_ref ); CICM::Status get_key_last_filled( out CICM::AsymKey key_ref ); CICM::Status import_key( in CICM::Buffer key_material, out CICM::AsymKey key_ref ); CICM::Status import_key_into_phys_location( in CICM::Buffer key_material, in CICM::UInt32 phys_location, out CICM::SymKey key_ref ); CICM::Status import_key_via_fill( in CICM::LocalPort fill_port, out CICM::AsymKey key_ref ); CICM::Status import_key_via_fill_into_phys_location( in CICM::LocalPort fill_port, in CICM::UInt32 phys_location, out CICM::AsymKey key_ref ); CICM::Status generate_key_pair( in CICM::AsymEncrAlgorithmId algorithm, out CICM::AsymKey key_ref ); Lanz & Novikov Expires January 26, 2012 [Page 64] Internet-Draft CICM Key Management July 2011 }; interface KeyDatabase { CICM::Status zeroize(); CICM::Status reencrypt(); }; }; Authors' Addresses Daniel J. Lanz The MITRE Corporation Email: dlanz@mitre.org Lev Novikov The MITRE Corporation Email: lnovikov@mitre.org Lanz & Novikov Expires January 26, 2012 [Page 65]