Common Interface to Cryptographic Modules (CICM) Key Management
draft-lanz-cicm-km-00

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 July 12, 2011.

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
    1.1.  Requirements Language
    1.2.  Definition Language
    1.3.  Conformance and Extension Language
2.  CICM Dependencies
    2.1.  Namespaces
    2.2.  Types
    2.3.  Interfaces
3.  General Key Concepts
    3.1.  Creating and Establishing Keys
    3.2.  Exporting Keys
    3.3.  Destroying Keys
    3.4.  Locating Keys
    3.5.  Protecting Keys
    3.6.  Identifiers
    3.7.  Interface CICM::Key
    3.8.  Interface CICM::KeyDatabase
4.  Asymmetric Keys
    4.1.  Interface CICM::AsymKeyManager
    4.2.  Interface CICM::AsymKey
    4.3.  Interface CICM::AsymKeyIterator
5.  Symmetric Keys
    5.1.  Interface CICM::SymKeyManager
    5.2.  Interface CICM::SymKey
    5.3.  Interface CICM::SymKeyIterator
6.  Key Protocol
    6.1.  Participants in the Interaction
    6.2.  Return Status, Condition, and Session Status
    6.3.  Generic Scenario
    6.4.  Key Agreement Example Using Diffie-Hellman Protocol
    6.5.  Protocol Support Examples
    6.6.  Interface CICM::KeyProtocolSender
    6.7.  Interface CICM::KeyProtocolReceiver
7.  IANA Considerations
8.  Security Considerations
    8.1.  Authorization
    8.2.  Authentication
    8.3.  Entity Authentication
    8.4.  Confidentiality
    8.5.  Data Integrity
    8.6.  Inappropriate Usage
9.  References
    9.1.  Normative References
    9.2.  Informative References
Appendix A.  IDL Definitions
§  Authors' Addresses

1.  Introduction

This document defines the key management functions for the Common Interface to Cryptographic Modules (CICM) as defined in [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.). The underlying logical model and terminology is defined in [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.).

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] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.).

1.2.  Definition Language

This document uses the Interface Definition Language (IDL) [IDL] (International Standards Organization, “Information technology — Open Distributed Processing — Interface Definition Language,” March 1999.) 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] (Object Management Group, “Common Object Request Broker Architecture (CORBA) Specification, Version 3.1,” January 2008.) between programs in different address spaces or on different devices. In other words, any specific protocol is strictly OPTIONAL. See Definition Language in [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.) 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] (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.) 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] (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.).

2.2.  Types

The following type definitions are defined in [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::UInt32

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

CICM::SymEncrAlgorithmId

CICM::HashAlgorithmId

CICM::KeyWrapAlgorithmId

CICM::ProtocolId

2.3.  Interfaces

The interface CICM::Iterator is defined in [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::Negotiator is defined in [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.).

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] (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.)) 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:

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] (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.)) 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.

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

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

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

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.

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] (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.)) 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.

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] (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.)) 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:

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

[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

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:

[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

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.

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.

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:

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

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 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] (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.)) 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.

[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] (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.)) 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.

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:

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

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.

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:

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

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:

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

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

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

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:

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

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

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

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:

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] (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.)) 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 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] (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.)) 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.

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:

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

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] (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.)) 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

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 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] (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.) 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] (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.) 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

9.2. Informative References

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