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

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]:

The type definitions for the following identifiers are defined in [CICM-CM]:

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

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.

3.7.2. CICM::Key Attributes

Attribute CICM::Key::identifier

attribute CICM::CharString identifier;

Unique global identifier for this key.

Remarks:

Warning:

Attribute CICM::Key::location

attribute CICM::UInt32 location;

Module-specific physical storage location for this key.

Warning:

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.

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:

Returns:

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:

Returns:

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:

Parameters:

Returns:

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:

Parameters:

Returns:

Method CICM::Key::zeroize()

CICM::Status zeroize();

Zeroize the selected key.

Remarks:

Returns:

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:

Returns:

Method CICM::KeyDatabase::reencrypt()

CICM::Status reencrypt();

Re-encrypt the module key database.

Remarks:

Returns:

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:

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:

Parameters:

Returns:

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:

Parameters:

Returns:

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:

Parameters:

Returns:

See also:

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:

Warning:

Parameters:

Returns:

See also:

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:

Warning:

Parameters:

Returns:

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:

Warning:

Parameters:

Returns:

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:

Warning:

Parameters:

Returns:

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:

Returns:

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.

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:

Returns:

See also:

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:

Returns:

See also:

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:

Parameters:

Returns:

See also:

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.

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:

Parameters:

Returns:

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:

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:

Parameters:

Returns:

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:

Parameters:

Returns:

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:

Parameters:

Returns:

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:

Warning:

Parameters:

Returns:

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:

Warning:

Parameters:

Returns:

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:

Warning:

Parameters:

Returns:

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:

Warning:

Parameters:

Returns:

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:

Returns:

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:

Returns:

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:

Parameters:

Returns:

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.

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.

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:

Returns:

See also:

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:

Parameters:

Returns:

See also:

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:

Returns:

See also:

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:

Returns:

See also:

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:

Parameters:

Returns:

See also:

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:

Parameters:

Returns:

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::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:

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 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:

The CICM API is the interface between the intermediary client programs and the cryptographic modules. All exchanges for a specific 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:

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:

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.

  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:
  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):
    1. "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.
    2. 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.
    3. 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.
  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:

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 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:

Parameters:

Returns:

See also:

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 to specify the desired algorithm of the resulting symmetric key.

Remarks:

Parameters:

Returns:

See also:

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.

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:

Returns:

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:

Parameters:

Returns:

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:

Parameters:

Returns:

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

9. References

9.1. Normative References

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
[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-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.
[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.
[IDL] International Standards Organization, "Information technology — Open Distributed Processing — Interface Definition Language", ISO/IEC 14750:1999(E), March 1999.

9.2. Informative References

[RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC Text on Security Considerations", BCP 72, RFC 3552, July 2003.
[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.

Appendix A. IDL Definitions 

module CICM {
  typedef CICM::CharString KeyId;

  interface Key {
    typedef CICM::UInt32 State;
    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
      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
      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;

    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(
      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,
      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 );
  };

  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