Common Interface to Cryptographic Modules

This memo presents a programming interface to standardize the way software programs manage cryptographic modules and utilize cryptographic services offered by modules. Although a number of interfaces for commercial environments have been standardized and are in use, this is the first generic cryptographic interface to be developed that supports cryptographic modules separating two security domains and is thus ideal for the high assurance marketplace. The interface has been designed to also allow less demanding environments to take advantage of its features.

Requirements Language

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

1. Introduction
    1.1. Background
    1.2. Audience
    1.3. Scope of the Specification
    1.4. Use Cases
        1.4.1. Data-in-Transit
        1.4.2. Data-at-Rest
        1.4.3. Single Security Domain
    1.5. Assumptions
    1.6. Specification Organization
    1.7. Acknowledgements
2. Using the Specification
    2.1. Specification Categories
    2.2. Module Management
        2.2.1. Managing Module Authentication
        2.2.2. Managing Software Packages
        2.2.3. Managing Logs
        2.2.4. Managing Tests
        2.2.5. Managing Module Events
        2.2.6. Managing Keys and Channels
    2.3. Key Management
        2.3.1. Creating and Establishing Keys
        2.3.2. Exporting Keys
        2.3.3. Channel Management
3. Normative Specification
    3.1. Introduction
        3.1.1. Conventions
        3.1.2. Normative Statements
    3.2. Fundamental Definitions
        3.2.1. Namespace CICM
        3.2.2. Fundamental Types
        3.2.3. Fundamental Interfaces
    3.3. Module Management
        3.3.1. Managing Hardware Access Tokens
        3.3.2. Managing Users
        3.3.3. Managing Login
        3.3.4. Managing Software Packages
        3.3.5. Managing Logs
        3.3.6. Managing Tests
        3.3.7. Managing Module Events
    3.4. Key Management
        3.4.1. General Key Concepts
        3.4.2. Asymmetric Keys
        3.4.3. Symmetric Keys
        3.4.4. Key Protocol
    3.5. Channel Management
        3.5.1. Channel Abstractions
        3.5.2. Conduit Abstractions
        3.5.3. Stream Abstractions
        3.5.4. Controller Abstractions
        3.5.5. Channel Negotiation
        3.5.6. Encryption Channel Management
        3.5.7. Decryption Channel Management
        3.5.8. Duplex Channel Management
        3.5.9. Bypass (Send) Channel Managment
        3.5.10. Bypass (Read) Channel Management
        3.5.11. Encryption with Selective Bypass Channel Management
        3.5.12. Decryption with Selective Bypass Channel Management
        3.5.13. Random, Pseudorandom and Keystream Channel Management
        3.5.14. Integrity Channel Management
        3.5.15. Single-Domain Channel Management
        3.5.16. Channel Event Management
        3.5.17. Channel Groups
4. Conformance and Extensions
    4.1. Conformance
        4.1.1. Implementation Conformance Statement Contents
        4.1.2. Implementation Data Specification Contents
        4.1.3. Generating Unique Identifiers
        4.1.4. Conformance Verification
    4.2. Extensions
        4.2.1. Extending an Interface
        4.2.2. Extending Codes
5. IANA Considerations
6. Security Considerations
7. Normative References
Appendix A. Status Codes
Appendix B. Terms
Appendix C. IDL Definitions
§ Authors' Addresses

1. Introduction

1.1. Background

Sensitive data is increasingly under attack, whether in transit or at rest. The computer security community has responded to these threats by using cryptography to secure sensitive data. To counter the growing number and types of threats against systems processing sensitive data, module vendors have engineered a diverse set of cryptographic modules.

Systems that require cryptographic protection may utilize various cryptographic services including data encryption, signature generation, hashing, and keystream generation. Cryptographic modules providing these services and the key material they hold must be managed. All of these services have proprietary interfaces that differ significantly among module types, leading to the following problems:

To address these problems, the Common Interface to Cryptographic Modules (CICM) specification offers module developers a set of standard interfaces for the set of operations supported by high assurance cryptographic modules. Although many Application Programming Interfaces (APIs) intended for commercial cryptography are available, the CICM specification was designed for high assurance environments, but may be used in other environments as well.

Modules do not require changes to support the use of CICM. A module-specific abstraction layer between the library implementing CICM interfaces and the module performs the needed translations between the CICM model of a module and the model presented by a specific module. This abstraction component may be provided by the module developer, a module embedder/integrator, or another interested party. This arrangement is analogous to manufacturers of computer peripheral devices providing platform or operating system-specific drivers for their peripheral devices.

CICM is defined using Interface Definition Language (IDL), a specification language that describes a software interface in a language-neutral way. IDL compilers can generate a functionally equivalent CICM interface binding for common programming languages. The use of IDL in CICM is not intended to either prescribe or preclude a particular communications protocol such as General Inter-ORB Protocol (GIOP) between programs in different address spaces or on different devices.

Software developers who require the services of cryptographic modules to perform cryptographic operations use a CICM library in their desired language binding for the specific module from which they intend to access cryptographic services. The specification currently does not specify normative bindings for specific programming languages, although bindings for common languages can be generated from the IDL provided with the specification. However, normative bindings for one or more popular programming languages will be made available in a future release of the specification.

The benefits of using the CICM standard interfaces to access cryptographic services include:

1.2. Audience

The CICM specification is written for computer programmers, software engineers, and technical architects with a background in data security and cryptography. Knowledge of object-oriented programming concepts is useful when reading IDL definitions. Software engineers may use the specification when developing software that integrates with cryptographic modules. Technical architects may use the specification when designing systems that incorporate cryptographic modules to secure data within the system or between systems.

Although the specification is targeted to software developers who will access module services using a compliant implementation, it also addresses module developers and others who implement library and other support software.

1.3. Scope of the Specification

CICM interfaces provide a common way to access the following services offered by cryptographic modules:

Each of the above services is discussed in detail in Section 2 of the specification and is introduced normatively in Section 3.

1.4. Use Cases

A significant characteristic that differentiates CICM from other cryptographic interfaces is its ability to support cryptographic modules that separate two security domains. The use cases that follow capture this fundamental element of CICM interface design. These use cases can be divided into two basic types:

The data-in-transit and data-at-rest use cases illustrated below incorporate multiple security domains, while the final use case depicts a transformation within a single domain.

1.4.1. Data-in-Transit

The figure below shows a hardware device with an embedded cryptographic module providing encryption and decryption services between a secure and non-secure network. The secure side protocol logic subsystems access cryptographic services using CICM. In this use case, the High Assurance IP Encryptor (HAIPE) device utilizes CICM to enable the internal protocol logic of the device to access cryptographic services; the network to which the HAIPE device is connected does not interface to the protocol encryptor using CICM.

A second data-in-transit use case shows a tactical secure radio with an embedded cryptographic module providing encryption and decryption services between a local host and a radio frequency environment. The functional blocks that make up the tactical secure radio are logically identical to those in the first example.

1.4.2. Data-at-Rest

The figure below shows a cryptographic module providing encryption services for data stored on a disk and decryption services for data read from a disk. A file system driver accesses cryptographic services using CICM standard interfaces. This use case could apply to a laptop computer that contains encrypted data; it would prevent access to sensitive data from a lost or stolen laptop.

1.4.3. Single Security Domain

The following figure shows a cryptographic transform within a single security domain (it assumes that the transform does not change the classification of the data). The plaintext is conveyed to the module, transformed by an encryption algorithm, and results in ciphertext. This information is then returned to the same domain from which the plaintext originated. Other natural examples of a single domain use case include signing, which results in a digital signature; hashing, which results in a hash value; and keystream generation, which results in keystream data.

1.5. Assumptions

1.6. Specification Organization

This specification contains normative and informative (non-normative) material. The normative material is prescriptive and provides information that is necessary to claim conformance to the specification. The informative material is for informational purposes; it assists the reader in the understanding and use of the specification but does not contain provisions required for conformance.

Section 1 and Section 2 provide introductory material and are non-normative. Section 3 presents the namespaces, interfaces, methods, and attributes that comprise the specification, and is normative. Section 4, Conformance and Extensions, provides the specification conformance statement and is normative. Appendix A lists the status codes referred to within the document and is normative. Appendix B lists the terms used within the document and is non-normative.

1.7. Acknowledgements

Many individuals participated in the development and review of the CICM specification. The CICM development team consists of Ronald Albuquerque, Samuel Cardman, Greg Carrier, James Cottrell, Shirley Kawamoto, Daniel Lanz, Brent Midwood, Lev Novikov, Brian O'Hanlon, Rick Page, Adam Pennington, and Nguyen Thai. The document production team consists of Mark Dwyer, Amanda Lind, and Brian Parrish.

The CICM team wishes to thank the following individuals for participating in a review of the specification:

2. Using the Specification

2.1. Specification Categories

This section describes CICM support for capabilities made available by cryptographic modules to systems that depend upon high assurance cryptography.

2.2. Module Management

CICM's most fundamental element and its technique for abstracting modules is the CryptoModule interface. This interface provides the means to manage individual modules, and to access channel and key interfaces. Individual CryptoModule instances are accessible from the CICMRoot interface, enabling a single CICM library instance to provide access to multiple cryptographic modules available from a particular host.

The CryptoModule interface defines attributes that enable a caller to retrieve information about a module, including the module manufacturer, serial number, and version numbers. This interface also defines specialized attributes called managers that provide access to the services made available by the module. CryptoModule supports the managers described in the sections below.

2.2.1. Managing Module Authentication

Modules may require a host or user to authenticate to the module before the module will enter an operational state, allowing it to accept commands and perform cryptographic transformations. In some cases, a specialized, removable hardware component will perform or participate in the authentication. This hardware component is termed a hardware access token in CICM nomenclature, although other communities may use different terminology. Most implementations utilizing hardware access tokens will transfer key material between the token and module, independent of the API. In cases where access tokens are not supported, a user may provide authentication credentials to the module via the API. In still other cases, support for multi-factor authentication will require a token and a user login. Note that the user and token holder may be different entities.

CICM provides interfaces that can be used separately or in combination with one another as appropriate for the system using them and for the authentication mechanisms offered by the module that is utilized by the system. Methods to manage module/token associations are available for systems where hardware access tokens are supported. Login methods and related user management methods are supported for systems that require user login.

2.2.1.1. Managing Hardware Access Tokens

The token manager defines methods that support associating a token with a module, disassociating a token from a module, and disassociating a module from a token. The manager also supports retrieving a list of token associations on a module and module associations on a token.

2.2.1.2. Managing Users

The user manager defines methods that support adding users to and removing users from a module user database, and associating a user with a module-defined role. The manager also supports listing the user database, and the roles defined and supported by the module.

2.2.1.3. Logging in to a Module from a Host

The login manager defines methods that enable a user configured on a module to login to and logout from a module.

2.2.2. Managing Software Packages

The package manager defines methods that support importing and managing the executable images that reside on a cryptographic module. These methods enable module software/firmware packages to be imported and other software package management operations to be performed, including retrieving a list of packages, and activating or deleting a specific package.

The package manager enables packages to be imported into a module in segments rather as an atomic unit. This supports modules that must make special provisions to import executable images due to internal storage space limitations.

2.2.3. Managing Logs

Modules generate log entries as they operate. The log manager defines methods that support retrieving individual log entries or extracting an entire log from a module. Additionally, clients may clear individual log entries or the entire module log.

2.2.4. Managing Tests

Modules may incorporate built-in tests to validate that module functionality is operating as designed. Some tests may be externally initiated. The test manager defines methods that support host-initiated module tests.

2.2.5. Managing Module Events

The event manager defines methods that support registering/unregistering module-generated event notifications received by a client program. Clients can register custom-developed callback procedures, called listeners , for specific module events. When the condition associated with a specific listener presents itself, the registered listener is called.

2.2.6. Managing Keys and Channels

Channel and key management interfaces are made available via managers in the CryptoModule interface. The asymmetric and symmetric key manager attributes allow for access to asymmetric keysets and symmetric keys, respectively, and the key database manager offers the ability to zeroize a module and reencrypt the module key database. The channel manager attribute allows channels to be created and used.

2.3. Key Management

Cryptographic modules utilize key material under their protection as one input to perform a cryptographic transformation. Keys

CICM supports separate IDL interfaces for symmetric keys and asymmetric keysets. An asymmetric keyset 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.

The asymmetric and symmetric key manager attributes allow for access to asymmetric keysets and symmetric keys, respectively.

2.3.1. Creating and Establishing Keys

Keys may be moved into a module in one of several scenarios. Each scenario is described in detail below.

2.3.1.1. No Host Interaction Key Fill

Specialized hardware devices designed to transfer key from a key infrastructure component to a specific cryptographic module may fill key into a module without host involvement and thus no API interaction. In some cases, this process does not support transferring key metadata with a key. This requires host and API interaction to apply metadata to the key inside the module upon completion of the fill.

2.3.1.2. Client Program-Initiated

In some cases, key fill devices require host interaction to initiate a key fill. The API enables a key storage location to be specified or key tagging information to be associated with the filled key prior to the initiation of the fill.

Keys may be imported via the key import method or derived using a text-based secret provided by the user of the client program. Keys also may be generated directly on the module. Each case results in a persistent key.

A key also is implicitly established each time a channel is created using an asymmetric keyset and upon renegotiation. Keys resulting from channel-based key agreement are ephemeral; they are not generally managed outside of a channel. Ephemeral keys also may be destroyed when a channel is destroyed.

2.3.1.3. Module/Key Infrastructure Initiated

A facility to operate a key agreement protocol with an infrastructure component is supported. This facility also enables key material or key revocation information to be authenticated by one of the module's trust anchors, and then loaded into the module.

2.3.2. Exporting Keys

Methods to export key material out of a module are supported. A module may require wrapping the key material prior to export or may disallow this operation.

2.3.2.1. Locating and Retrieving Information about a Key

A method to locate a specific key on a module based upon identification information associated with the key is supported. In addition, the entire key database may be listed.

2.3.2.2. Applying Metadata to Keys

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.

2.3.2.3. Performing Operations on Keys

A number of management operations on keys are supported. Keys may be wrapped (cryptographically protected) in preparation for export, or may be unwrapped after import. Keys may be zeroized, either individually or as the set of all key material on the module. Specialized operations to perform key conversions and updates also are available.

2.3.2.4. Enabling Remote Management

The specification enables support for various key management-related protocol messages including remote key functions (e.g., remote zeroize or rekey), infrastructure-initiated key revocation, and trust anchor management.

2.3.3. Channel Management

The CICM channel is the fundamental construct under which one or more related cryptographic transforms are performed, and within which all details and attributes associated with the transform are encapsulated, including the path through the module. Most channels accept data from a port in the local security domain, transform the data, and output the result on a port in another security domain. A channel also may perform transformations within a single security domain, or may accept data for transformation in one domain and output the result in another. The channel type determines which ports must be specified when a channel is created.

Figure 6. Local and Remote Port Nomenclature for Channels that Operate in Two Security Domains

Three classes of objects are fundamental to the creation and use of CICM channels. A controller is used to configure and control a channel. A stream enables data to be sent to a module to be transformed, and transformed data to be received using a controller as a foundation. A conduit is the sum of a controller and a stream. Thus, the term channel is only an abstraction representing the logical path through the module on which cryptographic transformations are performed.

This division of responsibility makes channels very flexible. One client program can be responsible for creating and managing channels with a controller, and another can send data over this preconfigured channel for transformation using a stream. In some environments, data to be transformed never enters the host to pass through the API. Instead, it is clocked directly through the module. In this situation, a controller is configured, but no stream is configured since it would never be used. In other cases, a client program is required to configure the channel and pass data through the channel it configured. In this case, the client program configures a conduit, which incorporates a controller and a stream.

Both controllers and conduits accept symmetric keys, requiring that the client program configuring the channel and its remote peer share the same secret key. Alternatively, all peers may hold their own respective asymmetric keysets, requiring a key negotiation which, upon successful completion, results in each peer holding an ephemeral symmetric key. CICM supports a negotiator IDL interface for this purpose. A successful negotiation results in a negotiated controller or conduit.

CICM also supports hybrid channel types. A channel that simultaneously supports encryption and signature, resulting in both ciphertext and a final signature value, is a hybrid channel.

Each of the types above differs in the way it is configured, its configuration options, and how it handles the cryptographic transformation of data. Consider the following examples portraying the diversity of the channel types:

This diversity results from the fundamental characteristics of the cryptographic primitives that are being abstracted. The channel manager defines the methods that support creating conduits, controllers, streams, and negotiators for each of the channel services listed above.

Interfaces for channel services are organized into 10 namespaces for modularity and as a mechanism to group similar channel types together. A namespace is an abstract container that holds related interfaces.

The CICM channel manager provides the ability to perform the functions described in the following sections.

2.3.3.1. Creating Channels

Selecting among these options enables the client program developer to determine what channel interface to use.

Consider the following example of a client program configuring a channel to perform encryption using an asymmetric keyset:

Given the above information, creating the appropriate type of negotiator from the ChannelManager is straightforward:

The above call results in the initiation of a key agreement protocol negotiation with its remote peer. To ensure that it is the expected peer, a human user at the client may validate information extracted from the peer's certificate. If the module uses a trusted display, it directly communicates the peer information to the display. Based upon user input at the display, host-independent negotiation is continued or aborted. If no trusted display is available, the client program requests information about the remote peer, displays it at the host for user confirmation, and provides positive confirmation via the API that the peer is valid, allowing the negotiation to continue.

The following example shows the display interactions required to retrieve a negotiated controller:

The resulting negotiated controller can be used to control and manage the channel.

2.3.3.1.1. Encryption and Decryption

CICM defines interfaces to support encryption and decryption between two security domains or within a single security domain. Additional variants are defined including hybrid channels that can concurrently compute integrity values. Another set of variants provides methods to perform encryption/decryption with selective bypass.

If an asymmetric keyset is used to create a channel, a negotiation process is initiated, which results in a negotiated channel. Negotiated versions of hybrid channels also are available. For those negotiator versions that combine encryption with integrity value generation, negotiation applies only to the encryption key specified when the channel is negotiated, not the signature or MAC key.

Channel-based multiple key wrap/unwrap support is provided via a special channels for that purpose.

CICM also supports encryption/decryption channels that operate in coprocessor mode . These channels accept their input and return their output as part of the same method call. Where relevant, the integrity value or verification status (verified/not verified) is returned when the final block of the input has been presented for transformation.

Duplex channel configurations that use the same key to perform encrypt and decrypt transformations also are supported. Negotiated versions of the duplex channel also are available.

2.3.3.1.2. Bypass

Bypass channels capable of defining a path through a module and then bypassing data from one security domain to a different domain are supported. Selective bypass also is supported on encryption and decryption channels.

2.3.3.1.3. Integrity

Interfaces to compute and validate integrity values using asymmetric key-derived digital signatures or symmetric key-derived MACs are available. A variant on the sign and verify interfaces accepts a previously generated hash value in place of a message.

2.3.3.1.4. Hashing

A channel to calculate a fixed-length cryptographic hash from an input message is available. Keyed hashes are supported by MAC channels.

2.3.3.1.5. Keystream Generation

2.3.3.1.6. Random Data

Separate interfaces are defined to retrieve random or pseudorandom data from a module.

2.3.3.2. Managing Channels

Only conduits and controllers (not streams) can manage channels. Negotiators also can manage the negotiation aspects of a channel.

The management operations that can be performed on a channel are specific to each channel type, but the following general operations are supported:

Managing state vectors is an important channel management capability. CICM provides a method to explicitly generate a state vector for those algorithms/modes that require a random initialization vector (IV), although modules may alternatively generate an IV as a byproduct of channel creation. CICM also provides a method to set the state vector on a channel. This may be used to:

2.3.3.3. Using Channels

Only conduits and streams (not controllers) can send data for transformation and receive cryptographically transformed data on a channel.

The data operations that can be performed on a channel or stream are specific to each channel type, but the following general operations are supported:

Although it is possible for multiple client programs to use the same stream, the specification provides no facilities to coordinate the parties participating in the communication.

Certain channel services support receiving an "answer" from a channel. For example, signature and hashing channels accept variable amounts of data for transformation before returning a final, constant-sized "answer" (a signature or a hash) to the caller. Composite channels require sending/receiving data and receiving a final "answer" after a discrete unit of data has been transformed.

The figure below depicts the use of a hybrid channel. Plaintext is sent through the CICM API for transformation. The module performs encrypt and sign transformations on the plaintext data. Ciphertext resulting from the encrypt transform emits from the module in a different security domain than the one in which it originated. When it is finished presenting data for transformation, the client program requests the signature that results from the transaction via the API.

Consider the following hybrid channel example where a client program configures a channel to simultaneously encrypt and sign data. The encryption operation utilizes a symmetric key, and the signature operation utilizes an asymmetric keyset. Cleartext is sent into the channel for transformation, and the resulting ciphertext emits in another security domain. When all data for transformation has been presented to the channel, the caller calls the associated "end" method to generate and retrieve the signature calculated over the plaintext.

Each type of channel supports a specific set of channel data operations. Channel types and the data operations they support are listed below:

For example, channels for encryption and bypass can send data. Channels for decryption, bypass, keystream generation, and random data generation can receive data. Duplex and coprocessor channels can send and receive data.

2.3.3.4. Grouping Channels

Controllers and conduits can be grouped to enable certain characteristics to be shared. One characteristic may be the state vector associated with the channels. This supports environments where two or more channels with related security rules supporting a single operation are used within a system. Whenever a shared characteristic is changed on a controller or conduit in a group, the effect of this change is applied to all controllers/conduits in the group.

2.3.3.5. Receiving Notification of Channel Events

The specification defines methods that support managing module event notifications. Similar support is available at the granularity of an individual conduit/controller. Conduits and controllers define methods that support registering/unregistering channel-specific module-generated event notifications captured by a client program. Clients can register custom-developed callback procedures called listeners for specific channel events. When the condition associated with a specific listener presents itself, the registered listener is called.

2.3.3.6. Destroying Channels

Conduits and controllers may be destroyed when their services are no longer needed. A channel is destroyed without regard for users who may have pending operations on the channel. Any ephemeral keys associated with the channel also may be destroyed. A stream ceases to function when its associated controller is destroyed. A destroyed channel is removed from any channel groups to which it belongs without effect upon other controllers/conduits in the group.

3. Normative Specification

The namespaces, interfaces, datatypes, methods, and attributes that comprise the specification are presented in a prescriptive manner. The conventions used within the section are presented first. The subsections that follow introduce the API partitioned into its three major categories:

For each category, each namespace is described followed by the interfaces contained within it. The datatype, method, and attribute definitions then follow each interface definition.

3.1. Introduction

3.1.1. Conventions

Understanding the design of the API and the IDL interfaces that compose CICM requires an understanding of the conventions used in this normative specification. The conventions used are introduced below.

3.1.1.1. Diagrams

3.1.1.2. IDL Definitions

Throughout this specification, normative definitions are presented using the following format:

This same format is used to provide definitions for types, constants, attributes, interfaces, and namespaces.

3.1.2. Normative Statements

A number of concerns fundamental to the remainder of the normative specification are listed below.

3.1.2.1. Endianness

Endianness is the byte ordering used to represent data stored in a computer or transmitted between computers. CICM requires a big-endian ordering of bytes.

3.1.2.2. Blocking and Non-blocking Calls

All CICM methods block (wait for the operation defined by the method) to complete before returning, unless they are explicitly defined as non-blocking. For example, the CICM::Encrypt::Stream::encrypt method blocks when sending data on a stream to be encrypted, while its sibling CICM::Encrypt::Stream::encrypt_non_blocking is identified not only in its name as non-blocking, but also clearly within the documentation for the method.

3.1.2.3. IDL Language Mapping Conventions

Memory responsibilities and calling conventions shall follow the appropriate IDL language mapping conventions.

3.2. Fundamental Definitions

3.2.1. Namespace CICM

3.2.2. Fundamental Types

3.2.2.1. General Types

Byte sequence, encapsulating the sequence of bytes, the length of the sequence, and the amount of allocated space.

3.2.2.2. Identifiers

3.2.2.3. Status Codes

3.2.2.4. Classifications

3.2.2.5. Algorithms

Value that indicates that the encryption algorithm is implicit in the key being provided to the module.

Value that indicates that the signature algorithm is implicit in the key being provided to the module.

Unique key wrap algorithm identifier, incorporating both the algorithm and the mode.

Value that indicates that the key wrap algorithm is implicit in the key being provided to the module.

Unique symmetric encryption algorithm identifier, incorporating both the algorithm and the mode.

Value that indicates that the encryption algorithm is implicit in the key being provided to the module.

Value that indicates that the MAC algorithm is implicit in the key being provided to the module.

Value that indicates that the key agreement protocol is implicit in the message being provided to the module.

3.2.2.6. Ports

3.2.2.7. State Vector

State vector, used to represent initialization vectors, synchronization vectors, counter values, and time-of-day values.

3.2.2.8. Integrity Buffers

3.2.3. Fundamental Interfaces

3.2.3.1. Interface CICM::CICMRoot

CICMRoot serves as the entry point to the CICM API and enables a specific cryptographic module of potentially many modules available to a host to be selected.

3.2.3.1.1. CICM::CICMRoot Methods

3.2.3.2. Interface CICM::CryptoModule

CICM::CryptoModule contains attributes that provide access to module-specific information and attributes that enable access to module managers, through which nearly all interface functionality is accessed.

3.2.3.2.1. CICM::CryptoModule Attributes

Current date/time. Intended for use only with module services that require coarse-grained time (e.g., timestamp on a log), not for time-of-day encryption.

3.2.3.2.2. CICM::CryptoModule Methods

3.2.3.3. Interface CICM::Iterator

3.2.3.3.1. CICM::Iterator Types and Constants

3.2.3.3.2. CICM::Iterator Methods

Used with get_next() to determine if one or more additional elements are available to be retrieved.

3.3. Module Management

3.3.1. Managing Hardware Access Tokens

Cryptographic modules may rely upon hardware access tokens for two primary functions: to allow subjects (e.g., administrators or users in possession of a token) to be identified and authenticated so that privileges can be enforced and audit log entries can identify the subject; and to unlock all or some subset of cryptographic services. A hardware access token may be associated with a number of specific modules, and a module may likewise be associated with a number of specific tokens. The token management functions below enable tokens and modules to be associated with and disassociated from one another, and allow existing associations to be listed.

The removal of an association between a token and a module is straightforward if both the token and the module are available. However, if either the token or module are unavailable, or if a different module than the one originally associated with the token is used to remove an association from a token, the disassociation is less straightforward.

If a module requires that an administrative token be inserted prior to the token to which the association/disassociation will apply, the methods below may return an CICM::S_TOKEN_NOT_PRESENT or CICM::S_TOKEN_ADMIN_NOT_PRESENT status.

Modules that do not support hardware tokens may instead provide similar support via CICM::LoginManager. Modules may use CICM::LoginManager in tandem with tokens to support multi-factor authentication. See the Managing Module Authentication subsection in Section 2 for additional information.

3.3.1.1. Interface CICM::TokenManager

CICM::TokenManager supports associating and disassociating modules and tokens. It is accessed from CICM::CryptoModule via the CICM::CryptoModule::token_manager attribute. CICM::TokenManager constructs the CICM::ModuleAssnIterator and CICM::TokenAssnIterator interfaces.

3.3.1.1.1. CICM::TokenManager Attributes

Returns an iterator to enable each module identifier associated with the current token to be retrieved.

Returns an iterator to enable each token identifier associated with the current module to be retrieved.

3.3.1.1.2. CICM::TokenManager Methods

Disassociate the module and currently-inserted hardware access token when the associated module and token are both present and both recognize the association.

Remove association information from the currently-inserted hardware access token when the associated module is not present.

Remove association information from the module on which this method is being executed when the associated token is not present.

3.3.1.2. Interface CICM::TokenAssnIterator

CICM::TokenAssnIterator supports retrieving each token record from the token association list in the module.

3.3.1.2.1. CICM::TokenAssnIterator Inheritance

3.3.1.2.2. CICM::TokenAssnIterator Methods

3.3.1.3. Interface CICM::ModuleAssnIterator

CICM::ModuleAssnIterator supports retrieving each module record from the module association list in the token.

3.3.1.3.1. CICM::ModuleAssnIterator Inheritance

3.3.1.3.2. CICM::ModuleAssnIterator Methods

Returns a reference to the next module record from the module association list in the token.

3.3.2. Managing Users

These interfaces enable the management of users in support of password-based login. See the Managing Module Authentication subsection in Section 2 for additional information.

3.3.2.1. Interface CICM::UserManager

CICM::UserManager supports adding a user/password, modifying a user's password, and removing users; and associating and disassociating users from a role. It is accessed from CICM::CryptoModule via the CICM::CryptoModule::user_manager attribute. CICM::UserManager constructs the CICM::UserIdIterator and CICM::RoleIdIterator interfaces.

3.3.2.1.1. CICM::UserManager Attributes

Returns an iterator to enable an identifier for each user in the module user database to be retrieved.

Returns an iterator to enable an identifier for each role supported by the module to be retrieved.

3.3.2.1.2. CICM::UserManager Methods

3.3.2.2. Interface CICM::UserIdIterator

3.3.2.2.1. CICM::UserIdIterator Inheritance

3.3.2.2.2. CICM::UserIdIterator Methods

3.3.2.3. Interface CICM::RoleIdIterator

3.3.2.3.1. CICM::RoleIdIterator Inheritance

3.3.2.3.2. CICM::RoleIdIterator Methods

3.3.3. Managing Login

These interfaces support a user configured on a module to login to a module using a password and, optionally, additional authentication data. See the Managing Module Authentication subsection in Section 2 for additional information.

Modules that support hardware tokens may use the login manager in tandem with the CICM::TokenManager to support multi-factor authentication.

3.3.3.1. Interface CICM::LoginManager

CICM::LoginManager supports user login to a module. It is accessed from CICM::CryptoModule via the CICM::CryptoModule::login_manager attribute. CICM::LoginManager constructs the CICM::Login interface. The LoginManager relies upon the CICM::UserManager to manage the users that are specified to the login methods.

3.3.3.1.1. CICM::LoginManager Methods

Login to the module with username/password, but provide additional (potentially host-stored) authentication data to the module for use in the authentication process.

3.3.3.2. Interface CICM::Login

CICM::Login results from a successful user login to a module and enables the user to log out from the module.

3.3.3.2.1. CICM::Login Methods

3.3.4. Managing Software Packages

These interfaces support software, FPGA images, policy databases, configuration parameters, or other types of executable or interpretable code to be imported into and removed from a module.

3.3.4.1. Interface CICM::PackageManager

CICM::PackageManager supports the management of module software packages. It is accessed from CICM::CryptoModule via the CICM::CryptoModule::package_manager attribute. CICM::PackageManager constructs the CICM::PackageImporter, CICM::PackageIterator, and CICM::Package interfaces.

3.3.4.1.1. CICM::PackageManager Attributes

Returns an iterator to enable a reference to each package loaded on the module to be retrieved.

3.3.4.1.2. CICM::PackageManager Methods

Initiate the process of importing a package into the module, specifying a reference to the key that will be used by CICM::PackageImporter to decrypt each package segment.

Retrieve a reference to a package based upon a unique identifier associated with that package.

3.3.4.2. Interface CICM::PackageImporter

CICM::PackageImporter supports importing software packages, segment by segment. CICM::PackageImporter is constructed by the CICM::PackageManager::import_package and CICM::PackageManager::import_package_with_key methods and may not be instantiated independently. CICM::PackageImporter constructs the CICM::Package interface.

3.3.4.2.1. CICM::PackageImporter Methods

Declare the package import complete and retrieve a reference to the resulting package object.

Abort a package import, resetting this CICM::PackageImporter instance, allowing a new package import session to begin.

3.3.4.3. Interface CICM::Package

CICM::Package serves as a reference to a package previously loaded into a module, and supports activating, deactivating, and deleting the package. CICM::Package is constructed by the CICM::PackageManager::get_package_by_id and CICM::PackageImporter::complete methods and may not be instantiated independently.

3.3.4.3.1. CICM::Package Types and Constants

3.3.4.3.2. CICM::Package Attributes

3.3.4.3.3. CICM::Package Methods

3.3.4.4. Interface CICM::PackageIterator

CICM::PackageIterator supports retrieving a reference to each software package available on a module. CICM::PackageIterator constructs the CICM::Package interface.

3.3.4.4.1. CICM::PackageIterator Inheritance

3.3.4.4.2. CICM::PackageIterator Methods

3.3.5. Managing Logs

3.3.5.1. Interface CICM::LogManager

CICM::LogManager supports retrieving or destroying an entire module log, or retrieving or deleting individual log entries. It is accessed from CICM::CryptoModule via the CICM::CryptoModule::log_manager attribute. CICM::LogManager constructs the CICM::LogEntryIterator interface.

3.3.5.1.1. CICM::LogManager Attributes

Returns an iterator to enable a reference to each module CICM::LogEntry to be retrieved.

3.3.5.1.2. CICM::LogManager Methods

3.3.5.2. Interface CICM::LogEntry

CICM::LogEntry serves as a reference to an individual log entry in the module log, and supports retrieving information about an individual log entry and deleting an individual log entry.

3.3.5.2.1. CICM::LogEntry Attributes

3.3.5.2.2. CICM::LogEntry Methods

3.3.5.3. Interface CICM::LogEntryIterator

CICM::LogEntryIterator supports retrieving a reference to each log entry in the module log. CICM::LogEntryIterator constructs the CICM::LogEntry interface.

3.3.5.3.1. CICM::LogEntryIterator Inheritance

3.3.5.3.2. CICM::LogEntryIterator Methods

3.3.6. Managing Tests

These interfaces support the initiation of module internal tests by client programs.

3.3.6.1. Interface CICM::TestManager

CICM::TestManager supports initiating client program-invoked module built-in tests. It is accessed from CICM::CryptoModule via the CICM::CryptoModule::test_manager attribute.

3.3.6.1.1. CICM::TestManager Types and Constants

3.3.6.1.2. CICM::TestManager Methods

Run module built-in tests specifying module-specific test parameters and receiving module-specific results or data for later evaluation from the test run.

3.3.7. Managing Module Events

In certain cases it may be necessary for a module to asynchronously notify a client program of an event. Client programs can register to receive module notifications using CICM::ModuleEventManager. This manager enables a client program to register a listener (callback) method designed to handle a specific condition. The event method prototype provided by the client program is defined in CICM::ModuleEventListener. CICM::ModuleEventListener also defines the conditions that may result in a notification, including: hardware requires attention, alarm, key expired, and health test failure.

In certain cases, a single event on a module may result in the generation of multiple notification messages. For example, CICM::ModuleEventListener::C_MODULE_ALARM may be followed by a CICM::ModuleEventListener::C_MODULE_NOT_READY_FOR_TRAFFIC.

3.3.7.1. Interface CICM::ModuleEventManager

CICM::ModuleEventManager supports registering and unregistering user-defined module event listeners (CICM::ModuleEventListener) for specific module events. It is accessed from CICM::CryptoModule via the CICM::CryptoModule::event_manager attribute.

3.3.7.1.1. CICM::ModuleEventManager Methods

3.3.7.2. Interface CICM::ModuleEventListener

CICM::ModuleEventListener is unlike other CICM interfaces in that the interface is implemented by the developer of the client program to service a specific module event and is then registered via the CICM::ModuleEventManager.

3.3.7.2.1. CICM::ModuleEventListener Types and Constants

Specific key has expired; the module can optionally include identifying information about the specific key that expired in the event_data buffer that is provided with the event itself.

Specific key is within some system-defined delta of hard expiration; the module can optionally include identifying information about the specific key that is about to expire in the event_data buffer that is provided with the event itself.

Key protocol message is available; see the Key Protocol Management documentation for additional information.

Rekey of a specific key is required; the module can optionally include identifying information about the specific key to be rekeyed in the event_data buffer that is provided with the event itself.

Module internal test has failed; the module can optionally include identifying information about the specific test that failed in the event_data buffer that is provided with the event itself.

3.3.7.2.2. CICM::ModuleEventListener Methods

Method implemented by client program that is called by the host runtime system to notify that a specific module event has occurred.

3.4. Key Management

3.4.1. General Key Concepts

3.4.1.1. Interface CICM::Key

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

Figure 19. Interface Inheritance Diagram for AsymKey and SymKey, Depicting Key Creation Methods

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

Figure 20. Interface Relationship and Inheritance Diagram Depicting Key Zeroization

3.4.1.1.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 Section 4, Conformance and Extensions) must reference a standard format or define a module developer-specific format implemented by the module for this datatype.

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

Figure 22. Interface Inheritance Diagram for AsymKey and SymKey, Depicting Key Protection Methods

3.4.1.1.6. CICM::Key Types and Constants

3.4.1.1.7. CICM::Key Attributes

Key caveat, a protective marking or distribution/handling instruction that may augment classification level.

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.4.1.1.8. CICM::Key Methods

Instruct module to wrap key, destroying the original unwrapped key and replacing it with the newly wrapped key.

Instruct module to unwrap key, destroying the original wrapped key and replacing it with the newly unwrapped key.

Export key material from a cryptographic module via a port representing a key fill interface.

3.4.1.2. Interface CICM::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.4.1.2.1. CICM::KeyDatabase Methods

3.4.2. Asymmetric Keys

3.4.2.1. Interface CICM::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.

3.4.2.1.1. CICM::AsymKeyManager Attributes

Returns an iterator to enable a reference to each asymmetric keyset in the module key database to be retrieved.

3.4.2.1.2. CICM::AsymKeyManager Methods

Retrieves a reference to the asymmetric keyset corresponding to the specified infrastructure-specific identifier.

Retrieves a reference to the asymmetric keyset corresponding to the specified module physical storage location.

Retrieves a reference to the asymmetric keyset corresponding to the keyset most recently filled via a key fill device.

Import key material into a specific physical key location in a cryptographic module.

Initiate the import of key material into a specific key physical location via a key fill interface.

Generate an asymmetric key pair compatible with the characteristics of the specified algorithm.

3.4.2.2. Interface CICM::AsymKey

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.

3.4.2.2.1. CICM::AsymKey Inheritance

3.4.2.2.2. CICM::AsymKey Types and Constants

3.4.2.2.3. CICM::AsymKey Methods

Instruct module to wrap keyset, resulting in two keysets, the original unwrapped keyset and the newly wrapped keyset.

Instruct module to unwrap key, resulting in two keys, the original wrapped key and the newly unwrapped key.

3.4.2.3. Interface CICM::AsymKeyIterator

CICM::AsymKeyIterator supports retrieving a reference to each usable asymmetric key on a module. CICM::AsymKeyIterator constructs the CICM::AsymKey interface.

3.4.2.3.1. CICM::AsymKeyIterator Inheritance

3.4.2.3.2. CICM::AsymKeyIterator Methods

3.4.3. Symmetric Keys

3.4.3.1. Interface CICM::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.

3.4.3.1.1. CICM::SymKeyManager Attributes

Returns an iterator to enable a reference to each symmetric key in the module key database to be retrieved.

CICM::KeyProtocolSender supports sending key management protocol-related messages into a module.

CICM::KeyProtocolReceiver supports receiving key management protocol-related messages from a module. CICM::KeyProtocolReceiver constructs the CICM::SymKey interface.

3.4.3.1.2. CICM::SymKeyManager Methods

Retrieves a reference to the symmetric key corresponding to the specified infrastructure-specific identifier.

Retrieves a reference to the symmetric key corresponding to the specified module physical storage location.

Retrieves a reference to the symmetric key corresponding to the key most recently filled via a key fill device.

Import key material or seed key for pseudorandom data generation into a cryptographic module.

Import key material or seed key for pseudorandom data generation into a specific physical key location in a cryptographic module.

Initiate the import of key material into a specific key physical location via a key fill interface.

Generate a symmetric key compatible with the characteristics of the specified algorithm.

Derives a symmetric key from a password and other parameters using a password-based key derivation function (PBKDF).

Derives a symmetric key using a distributed deterministic key generation scheme.

3.4.3.2. Interface CICM::SymKey

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.

3.4.3.2.1. CICM::SymKey Inheritance

3.4.3.2.2. CICM::SymKey Types and Constants

3.4.3.2.3. CICM::SymKey Attributes

3.4.3.2.4. CICM::SymKey Methods

Cryptographically update the key using the key's native algorithm. The update modifies the existing key.

Cryptographically update the key using the specified key update algorithm. The update modifies the existing key.

Instruct module to wrap key, resulting in two keys, the original unwrapped key and the newly wrapped key.

Instruct module to unwrap key, resulting in two keys, the original wrapped key and the newly unwrapped key.

3.4.3.3. Interface CICM::SymKeyIterator

CICM::SymKeyIterator supports retrieving a reference to each usable symmetric key on a module. CICM::SymKeyIterator constructs the CICM::SymKey interface.

3.4.3.3.1. CICM::SymKeyIterator Inheritance

3.4.3.3.2. CICM::SymKeyIterator Methods

3.4.4. Key Protocol

The key management capabilities described here support certain key management protocols, including key establishment/distribution protocols such as Diffie-Hellman, EC-DH, and EC-MQV; trust anchor management protocols; the importation of key white lists (acceptable keys) or black lists (revoked keys or keys restricted administratively); and the execution of remote key functions. These key protocol IDL interfaces initiate a key agreement protocol between two or more entities to establish a secret key over an insecure communications channel. CICM channel negotiators (CICM::Negotiator) similarly initiate a key agreement protocol with a remote entity, but this typically results in an ephemeral key, in contrast to these key protocol interfaces which result in a persistent symmetric key that can be used by a variety of key management and channel management functions.

For the purposes of these key protocol-related interfaces, a client program using the CICM API is only an intermediary in a key management protocol being conducted between a cryptographic module and other participants in a protocol session. In this role, a client program determines which module(s) should be involved and conveys the protocol messages, but otherwise does not participate in the protocol session. The client may be responsible for determining which key agreement protocol to use as well as for the reliable transport of messages passed between the peer entities. The interactions that comprise a protocol session in its entirety may entail a number of exchanges among the participants in the protocol. Any results from calls to key protocol methods during the course of the protocol exchange must be communicated to the appropriate peer entity by the caller. The progress, success, or failure of the protocol session is determined by the modules and other active participants in the interaction.

CICM key protocol functionality is exported via two independent objects: CICM::KeyProtocolSender for protocol messages inbound to the module and CICM::KeyProtocolReceiver for messages outbound from the module. Access to each respective object is available via CICM::SymKeyManager::key_protocol_sender and CICM::SymKeyManager::key_protocol_receiver.

The key protocol methods support protocol sessions that may be long-term interactions potentially extending over several invocations of the controlling client program. To allow for this possibility, KeyProtocolReceiver::get_from_module may be used to "query" a module to determine if a response is ready and, if so, to retrieve response traffic (including current session status information) from the module. Thus, a single response from the module may take the form of a number of queries by the client program, with any productive response deferred until the module is ready:

In the example above, the client program expects either a "condition" update from the module as part of the protocol session, or the most recent results from the active session. Thus, the client program queries the module periodically until it is ready to produce a response.

The traffic relayed by these functions is part of a specific protocol session. The protocol governing this session is specified with the protocol parameter, either the value CICM::IMPLICIT_PROTOCOL_ID, denoting that the message itself indicates the protocol, or a unique protocol identifier designating the protocol directly. If the protocol parameter is CICM::IMPLICIT_PROTOCOL_ID but the message does not indicate the protocol, then the method fails, returning the CICM::S_PROTO_UNDETERMINED error status.

The initial message in a protocol exchange can be generated either by the cryptographic module or some other party, including some party in a key management infrastructure or the client program itself. If the initial message is generated by the cryptographic module, a two-step process allows the message to be retrieved from the module:

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.

3.4.4.1. Participants in the Interaction

There are three types of participants in a protocol session using the key protocol functionality:

The CICM API is the interface between the intermediary client programs and the cryptographic modules. All exchanges for a specific protocol session between a given module and other modules or other active participants (Party 1, ..., Party N) are mediated by the intermediary client program using CICM. Although the client program does not directly participate in the protocol session, the client program may be asked during the negotiation process to display identifying information about the remote party in the protocol to a human user who must determine if the remote party is the expected remote party in the protocol and, if so, must positively acknowledge this assertion to allow the protocol to continue. Some protocol sessions will not require this peer validation interaction (e.g., validation of the peer using a trust anchor is deemed sufficient or an external trusted display handles the user interaction).

Except for recognizing the specific role of the cryptographic modules themselves, assignment of roles in the protocol to the active participants is out of scope for this document.

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

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

Figure 25. Generic Scenario for Key Protocol Session Initiated by a Key Infrastructure Component

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

Figure 26. 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"):

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

3.4.4.6. Interface CICM::KeyProtocolSender

CICM::KeyProtocolSender supports sending key management protocol-related messages into a module.

3.4.4.6.1. CICM::KeyProtocolSender Inheritance

3.4.4.6.2. CICM::KeyProtocolSender Types and Constants

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.

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.

Denotes that the human user reviewing the remote peer information chose to reject it and abort the protocol.

Denotes that the conveyed message was found to be invalid for the protocol. This event does not terminate the protocol session.

Denotes that the conveyed message failed one or more integrity checks used in the protocol. This event does not terminate the protocol session.

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.

3.4.4.6.3. CICM::KeyProtocolSender Methods

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.

3.4.4.7. Interface CICM::KeyProtocolReceiver

CICM::KeyProtocolReceiver supports receiving key management protocol-related messages from a module. CICM::KeyProtocolReceiver constructs the CICM::SymKey interface.

3.4.4.7.1. CICM::KeyProtocolReceiver Types and Constants

Denotes that the session is in progress and a response message has been returned.

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.

Denotes that the session terminated with an error condition and a response message has been returned.

Denotes that the human user reviewing the remote peer information chose to reject it and abort the protocol.

Denotes that the conveyed message was found to be invalid for the protocol. This event does not terminate the protocol session.

Denotes that the conveyed message failed one or more integrity checks used in the protocol. This event does not terminate the protocol session.

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.

3.4.4.7.2. CICM::KeyProtocolReceiver Methods

Initiate or recommence a key management protocol session, soliciting a response from the cryptographic module.

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.

3.5. Channel Management

3.5.1. Channel Abstractions

3.5.1.1. Interface CICM::ChannelManager

CICM::ChannelManager supports the creation and negotiation of cryptographic channels. It is accessed from CICM::CryptoModule via the CICM::CryptoModule::channel_manager attribute. CICM::ChannelManager enables a variety of different channel types to be constructed.

3.5.1.1.1. CICM::ChannelManager Inheritance

CICM::ChannelManager inherits from: CICM::Answer::ChannelManager, CICM::BypassRead::ChannelManager, CICM::BypassWrite::ChannelManager, CICM::Coprocessor::ChannelManager, CICM::Decrypt::ChannelManager, CICM::DecryptBypass::ChannelManager, CICM::Duplex::ChannelManager, CICM::Emit::ChannelManager, CICM::Encrypt::ChannelManager and CICM::EncryptBypass::ChannelManager.

3.5.1.1.2. CICM::ChannelManager Methods

3.5.1.2. Interface CICM::Channel

Defines the logical path through the module. Interface from which all conduit, streams and controllers inherit. Channels are created via the CICM::ChannelManager interface.

3.5.1.2.1. CICM::Channel Attributes

3.5.1.3. Interface CICM::Conduit

Interface from which all other conduits are inherited. A conduit is a combination of a stream and controller.

3.5.1.3.1. CICM::Conduit Inheritance

3.5.1.4. Interface CICM::Controller

Interface from which all other controllers are inherited. Controls general characteristics of a cryptographic transformation, but does not provide data to be transformed.

3.5.1.4.1. CICM::Controller Inheritance

3.5.1.4.2. CICM::Controller Methods

3.5.1.5. Interface CICM::Stream

Interface from which all streams inherit. Streams manage the flow of data on a channel, but not its attributes.

3.5.1.5.1. CICM::Stream Inheritance

3.5.2. Conduit Abstractions

3.5.2.1. Interface CICM::AbstractMACConduit

3.5.2.1.1. CICM::AbstractMACConduit Inheritance

3.5.2.1.2. CICM::AbstractMACConduit Attributes

3.5.2.1.3. CICM::AbstractMACConduit Methods

Direct the module to compute and output the MAC value, and reset the channel to accept additional data.

3.5.2.2. Interface CICM::AbstractSignConduit

3.5.2.2.1. CICM::AbstractSignConduit Inheritance

3.5.2.2.2. CICM::AbstractSignConduit Attributes

3.5.2.2.3. CICM::AbstractSignConduit Methods

Direct the module to compute and output the signature, and reset the conduit to accept additional data.

3.5.2.3. Interface CICM::AbstractVerifyConduit

3.5.2.3.1. CICM::AbstractVerifyConduit Inheritance

3.5.2.3.2. CICM::AbstractVerifyConduit Types and Constants

3.5.2.4. Interface CICM::AbstractMACVerifyConduit

3.5.2.4.1. CICM::AbstractMACVerifyConduit Inheritance

3.5.2.4.2. CICM::AbstractMACVerifyConduit Attributes

3.5.2.4.3. CICM::AbstractMACVerifyConduit Methods

Direct the module to compute and output the MAC verification status, and reset the channel to accept additional data for verification.

3.5.2.5. Interface CICM::AbstractSigVerifyConduit

3.5.2.5.1. CICM::AbstractSigVerifyConduit Inheritance

3.5.2.5.2. CICM::AbstractSigVerifyConduit Attributes

3.5.2.5.3. CICM::AbstractSigVerifyConduit Methods

Direct the module to compute and output the verification status, and reset the channel to accept additional data for verification.

3.5.3. Stream Abstractions

3.5.3.1. Interface CICM::WriteStream

3.5.3.1.1. CICM::WriteStream Inheritance

3.5.3.1.2. CICM::WriteStream Types and Constants

3.5.3.2. Interface CICM::ReadStream

3.5.3.2.1. CICM::ReadStream Inheritance

3.5.3.2.2. CICM::ReadStream Types and Constants

3.5.4. Controller Abstractions

3.5.4.1. Interface CICM::MultiDomainController

Interface from which any other multi-domain-related controller or conduit inherits.

3.5.4.1.1. CICM::MultiDomainController Inheritance

3.5.4.1.2. CICM::MultiDomainController Attributes

3.5.4.2. Interface CICM::SymKeyController

3.5.4.2.1. CICM::SymKeyController Inheritance

3.5.4.2.2. CICM::SymKeyController Attributes

3.5.4.2.3. CICM::SymKeyController Methods

Cryptographically update the key associated with this controller using the key's native algorithm.

Cryptographically update the key associated with this controller using the specified algorithm.

3.5.4.3. Interface CICM::AsymKeyController

3.5.4.3.1. CICM::AsymKeyController Inheritance

3.5.4.3.2. CICM::AsymKeyController Attributes

3.5.4.4. Interface CICM::NegotiatedController

Interface from which all other negotiated controllers inherit. A controller that uses a negotiated key.

3.5.4.4.1. CICM::NegotiatedController Inheritance

CICM::NegotiatedController inherits from: CICM::MultiDomainController, CICM::AsymKeyController and CICM::Negotiator.

3.5.4.4.2. CICM::NegotiatedController Attributes

3.5.4.4.3. CICM::NegotiatedController Methods

3.5.4.5. Interface CICM::SetVectorController

3.5.4.5.1. CICM::SetVectorController Inheritance

3.5.4.5.2. CICM::SetVectorController Attributes

3.5.4.5.3. CICM::SetVectorController Methods

3.5.4.6. Interface CICM::GenVectorController

3.5.4.6.1. CICM::GenVectorController Inheritance

3.5.4.6.2. CICM::GenVectorController Methods

3.5.4.7. Interface CICM::ResyncController

3.5.4.7.1. CICM::ResyncController Inheritance

3.5.4.7.2. CICM::ResyncController Methods

Resynchronize the channel, using the specified synchronization vector (required by certain operating modes to initiate a resync).

3.5.5. Channel Negotiation

3.5.5.1. Negotiating Channels and Controllers

When creating an encryption or decryption channel using an asymmetric keyset, a negotiation process must be initiated between the two communicating entities, resulting in an ephemeral symmetric key held by each entity. The following details the steps in the negotiation process:

3.5.5.2. Interface CICM::Negotiator

CICM::Negotiator is an abstraction inherited by controllers and CICM::KeyProtocolSender to assist in the management of the negotiation process.

3.5.5.2.1. CICM::Negotiator Methods

Retrieve remote peer identification information. The peer information must be displayed to the local user to enable determination to be made as to whether negotiation should continue or be aborted. If the decision is made to abort negotiation, the CICM::Negotiator::abort_negotiation method must be called to destroy any protocol session state.

Abort negotiation or renegotiation. This method must be called in the event the identification information for the remote host does not correspond to the expected host.

3.5.5.3. Interface CICM::PeerInfo

3.5.5.3.1. CICM::PeerInfo Attributes

Highest security classification level at which the remote entity participating in the key agreement protocol is capable of communicating.

Message to be displayed regarding the remote entities' participation in key agreement protocol.

3.5.6. Encryption Channel Management

The CICM::Encrypt namespace contains interfaces that support encryption operations between two independent security domains.

3.5.6.1. Interface CICM::Encrypt::ChannelManager

CICM::Encrypt::ChannelManager is an abstraction inherited by CICM::ChannelManager that supports the creation of encryption negotiators, conduits, controllers, and streams. See CICM::ChannelManager for additional information.

3.5.6.1.1. CICM::Encrypt::ChannelManager Methods

Initiate a negotiation to establish a shared key with a peer. The channel that results will encrypt a stream of data.

Initiate a negotiation to establish a shared key with a peer. The channel that results will MAC and encrypt a stream of data.

Initiate a negotiation to establish a shared key with a peer. The channel that results will sign and encrypt a stream of data.

Initiate a negotiation to establish a shared key with a peer, resulting in a controller to manage an encryption channel.

Create stream associated with previously created controller to accept data for transformation.

3.5.6.2. Interface CICM::Encrypt::Stream

CICM::Encrypt::Stream supports encryption operations between two independent security domains. The resulting stream is capable of accepting data for transformation, but not managing the channel. It is created by calling CICM::ChannelManager::get_encrypt_stream.

3.5.6.2.1. CICM::Encrypt::Stream Inheritance

3.5.6.2.2. CICM::Encrypt::Stream Methods

Registers a buffer of data to be sent to the module for encryption and then immediately returns control to the caller. The length of the data is encapsulated in the buffer parameter. The caller may use the CICM::Encrypt::Stream::encrypt_poll method to proactively poll the channel to determine the status of the operation. The caller is responsible for maintaining any necessary metadata associated with the transaction_id parameter. Memory responsibilities and calling conventions shall follow the appropriate IDL language mapping conventions.

Returns the status of the non-blocking encryption operation specified by the transaction_id parameter. Memory responsibilities and calling conventions shall follow the appropriate IDL language mapping conventions.

3.5.6.3. Interface CICM::Encrypt::KeyWrapStream

CICM::Encrypt::KeyWrapStream is an abstraction that allows key material to be presented to a stream for wrapping prior to passing into a different security domain.

3.5.6.3.1. CICM::Encrypt::KeyWrapStream Inheritance

3.5.6.3.2. CICM::Encrypt::KeyWrapStream Methods

3.5.6.4. Interface CICM::Encrypt::Controller

CICM::Encrypt::Controller supports encryption operations between two independent security domains. The resulting controller is capable of managing the channel, but not accepting data for transformation. It is created by calling CICM::ChannelManager::create_encrypt_controller.

3.5.6.4.1. CICM::Encrypt::Controller Inheritance

CICM::Encrypt::Controller inherits from: CICM::MultiDomainController, CICM::SymKeyController, CICM::GenVectorController and CICM::ResyncController.

3.5.6.5. Interface CICM::Encrypt::NegotiatedController

CICM::Encrypt::NegotiatedController is the negotiated version of CICM::Encrypt::Controller. It is the result of a successful negotiation by CICM::Encrypt::ControllerNegotiator.

3.5.6.5.1. CICM::Encrypt::NegotiatedController Inheritance

CICM::Encrypt::NegotiatedController inherits from: CICM::NegotiatedController, CICM::GenVectorController and CICM::ResyncController.

3.5.6.6. Interface CICM::Encrypt::Conduit

CICM::Encrypt::Conduit supports encryption operations between two independent security domains. The resulting conduit is capable of both managing the channel and accepting data for transformation. It is created by calling CICM::ChannelManager::create_encrypt_conduit.

3.5.6.6.1. CICM::Encrypt::Conduit Inheritance

CICM::Encrypt::Conduit inherits from: CICM::Conduit, CICM::Encrypt::Controller and CICM::Encrypt::Stream.

3.5.6.7. Interface CICM::Encrypt::NegotiatedConduit

CICM::Encrypt::NegotiatedConduit is the negotiated version of CICM::Encrypt::Conduit. It is the result of a successful negotiation by CICM::Encrypt::Negotiator.

3.5.6.7.1. CICM::Encrypt::NegotiatedConduit Inheritance

CICM::Encrypt::NegotiatedConduit inherits from: CICM::Conduit, CICM::Encrypt::NegotiatedController and CICM::Encrypt::Stream.

3.5.6.8. Interface CICM::Encrypt::WithMACConduit

CICM::Encrypt::WithMACConduit supports encryption operations between two independent security domains with the receipt of a MAC value in the initiating domain. The resulting conduit is capable of both managing the channel and accepting data for transformation. It is created by calling CICM::ChannelManager::create_encrypt_with_mac_conduit.

3.5.6.8.1. CICM::Encrypt::WithMACConduit Inheritance

CICM::Encrypt::WithMACConduit inherits from: CICM::AbstractMACConduit and CICM::Encrypt::Conduit.

3.5.6.9. Interface CICM::Encrypt::WithMACNegotiatedConduit

CICM::Encrypt::WithMACNegotiatedConduit is the negotiated version of CICM::Encrypt::WithMACConduit. It is the result of a successful negotiation by CICM::Encrypt::WithMACNegotiator.

3.5.6.9.1. CICM::Encrypt::WithMACNegotiatedConduit Inheritance

CICM::Encrypt::WithMACNegotiatedConduit inherits from: CICM::AbstractMACConduit and CICM::Encrypt::NegotiatedConduit.

3.5.6.10. Interface CICM::Encrypt::WithSignConduit

CICM::Encrypt::WithSignConduit supports encryption operations between two independent security domains with the receipt of a signature value in the initiating domain. The resulting conduit is capable of both managing the channel and accepting data for transformation. It is created by calling CICM::ChannelManager::create_encrypt_with_sign_conduit.

3.5.6.10.1. CICM::Encrypt::WithSignConduit Inheritance

CICM::Encrypt::WithSignConduit inherits from: CICM::AbstractSignConduit and CICM::Encrypt::Conduit.

3.5.6.11. Interface CICM::Encrypt::WithSignNegotiatedConduit

CICM::Encrypt::WithSignNegotiatedConduit is the negotiated version of CICM::Encrypt::WithSignConduit. It is the result of a successful negotiation by CICM::Encrypt::WithSignNegotiator.

3.5.6.11.1. CICM::Encrypt::WithSignNegotiatedConduit Inheritance

CICM::Encrypt::WithSignNegotiatedConduit inherits from: CICM::AbstractSignConduit and CICM::Encrypt::NegotiatedConduit.

3.5.6.12. Interface CICM::Encrypt::KeyWrapConduit

CICM::Encrypt::KeyWrapConduit supports key wrapping operations between two independent security domains. The resulting conduit is capable of both managing the channel and accepting keys for transformation. It is created by calling CICM::ChannelManager::create_key_wrap_conduit.

3.5.6.12.1. CICM::Encrypt::KeyWrapConduit Inheritance

CICM::Encrypt::KeyWrapConduit inherits from: CICM::Encrypt::Controller and CICM::Encrypt::KeyWrapStream.

3.5.6.13. Interface CICM::Encrypt::ControllerNegotiator

CICM::Encrypt::ControllerNegotiator initiates a negotiation to establish a shared key with a remote entity that is used to support encryption operations between two independent security domains. The result of a successful negotiation is a CICM::Encrypt::NegotiatedController which is capable of managing the channel, but not accepting data for transformation. CICM::Encrypt::ControllerNegotiator is created by calling CICM::ChannelManager::negotiate_encrypt_controller.

3.5.6.13.1. CICM::Encrypt::ControllerNegotiator Inheritance

3.5.6.13.2. CICM::Encrypt::ControllerNegotiator Methods

3.5.6.14. Interface CICM::Encrypt::Negotiator

CICM::Encrypt::Negotiator initiates a negotiation to establish a shared key with a remote entity that is used to support encryption operations between two independent security domains. The result of a successful negotiation is a CICM::Encrypt::NegotiatedConduit which is capable of both managing the channel and accepting data for transformation. CICM::Negotiator is created by calling CICM::Encrypt::ChannelManager::negotiate_encrypt_conduit.

3.5.6.14.1. CICM::Encrypt::Negotiator Inheritance

3.5.6.14.2. CICM::Encrypt::Negotiator Methods

3.5.6.15. Interface CICM::Encrypt::WithMACNegotiator

CICM::Encrypt::WithMACNegotiator initiates a negotiation to establish a shared key with a remote entity that is used to support encryption operations between two independent security domains. Additionally, a message authentication code is received in the initiating domain. The result of a successful negotiation is a CICM::Encrypt::WithMACNegotiatedConduit which is capable of both managing the channel and accepting data for transformation. CICM::Encrypt::WithMACNegotiator is created by calling CICM::ChannelManager::negotiate_encrypt_with_mac_conduit.

3.5.6.15.1. CICM::Encrypt::WithMACNegotiator Inheritance

3.5.6.15.2. CICM::Encrypt::WithMACNegotiator Methods

3.5.6.16. Interface CICM::Encrypt::WithSignNegotiator

CICM::Encrypt::WithSignNegotiator initiates a negotiation to establish a shared key with a remote entity that is used to support encryption operations between two independent security domains. Additionally, a signature value is received in the initiating domain. The result of a successful negotiation is a CICM::Encrypt::WithSignNegotiatedConduit which is capable of both managing the channel and accepting data for transformation. CICM::Encrypt::WithSignNegotiator is created by calling CICM::ChannelManager::negotiate_encrypt_with_sign_conduit.

3.5.6.16.1. CICM::Encrypt::WithSignNegotiator Inheritance

3.5.6.16.2. CICM::Encrypt::WithSignNegotiator Methods

3.5.7. Decryption Channel Management

The CICM::Decrypt namespace contains interfaces that support decryption operations between two independent security domains.

3.5.7.1. Interface CICM::Decrypt::ChannelManager

CICM::Decrypt::ChannelManager is an abstraction inherited by CICM::ChannelManager that supports the creation of decryption negotiators, conduits, controllers, and streams. See CICM::ChannelManager for additional information.

3.5.7.1.1. CICM::Decrypt::ChannelManager Methods

Creates a negotiator that, upon successful negotiation, results in a CICM::Decrypt::NegotiatedConduit.

Creates a negotiator that, upon successful negotiation, results in a CICM::Decrypt::MACNegotiatedConduit.

Initiate a negotiation to establish a shared key with a peer. The channel that results will decrypt and verify a stream of data.

Initiate a negotiation to establish a shared key with a peer, resulting in a controller to manage a decryption channel.

Create channel to unwrap a key. This type of channel may be used to bulk unwrap key material originating at a key infrastructure component or from a peer cryptographic module. Note that, to unwrap individual keys already in the module, use CICM::Symkey::unwrap or CICM::Asymkey::unwrap.

Create stream associated with previously created controller to receive transformed data.

3.5.7.2. Interface CICM::Decrypt::Stream

CICM::Decrypt::Stream supports decryption operations between two independent security domains. The resulting stream is capable of accepting transformed data, but not managing the channel. It is created by calling CICM::ChannelManager::get_decrypt_stream.

3.5.7.2.1. CICM::Decrypt::Stream Inheritance

3.5.7.2.2. CICM::Decrypt::Stream Methods

Read plaintext data off of decrypt channel stream. The method blocks until data becomes available.

Registers a buffer into which plaintext resulting from the decryption operation will be copied, and then immediately returns control to the caller. The size of the allocated buffer and length of the resulting plaintext is encapsulated in the buffer parameter. The caller may use the CICM::Decrypt::Stream::decrypt_poll method to proactively poll the channel to determine the status of the operation. The caller is responsible for maintaining any necessary metadata associated with the transaction_id parameter. Memory responsibilities and calling conventions shall follow the appropriate IDL language mapping conventions.

Returns the status of the non-blocking decryption operation specified by the transaction_id parameter. Upon completion of the operation, the caller must use the metadata associated with the transaction_id parameter to determine which buffer has been populated. Memory responsibilities and calling conventions shall follow the appropriate IDL language mapping conventions.

3.5.7.3. Interface CICM::Decrypt::KeyUnwrapStream

CICM::Decrypt::KeyUnwrapStream is an abstraction that allows unwrapped key material received from another domain to be retrieved.

3.5.7.3.1. CICM::Decrypt::KeyUnwrapStream Inheritance

3.5.7.3.2. CICM::Decrypt::KeyUnwrapStream Methods

Read one unwrapped symmetric key off of channel stream and return a reference to the key. The method blocks until a key becomes available.

Read one unwrapped asymmetric key off of channel stream and return a reference to the key. The method blocks until a key becomes available.

3.5.7.4. Interface CICM::Decrypt::Controller

CICM::Decrypt::Controller supports decryption operations between two independent security domains. The resulting controller is capable of managing the channel, but not accepting transformed data. It is created by calling CICM::ChannelManager::create_decrypt_controller.

3.5.7.4.1. CICM::Decrypt::Controller Inheritance

CICM::Decrypt::Controller inherits from: CICM::MultiDomainController, CICM::SymKeyController, CICM::SetVectorController and CICM::ResyncController.

3.5.7.5. Interface CICM::Decrypt::NegotiatedController

CICM::Decrypt::NegotiatedController is the negotiated version of CICM::Decrypt::Controller. It is the result of a successful negotiation by CICM::Decrypt::ControllerNegotiator.

3.5.7.5.1. CICM::Decrypt::NegotiatedController Inheritance

CICM::Decrypt::NegotiatedController inherits from: CICM::NegotiatedController, CICM::SetVectorController and CICM::ResyncController.

3.5.7.6. Interface CICM::Decrypt::Conduit

CICM::Decrypt::Conduit supports decryption operations between two independent security domains. The resulting conduit is capable of both managing the channel and accepting transformed data. It is created by calling CICM::ChannelManager::create_decrypt_conduit.

3.5.7.6.1. CICM::Decrypt::Conduit Inheritance

CICM::Decrypt::Conduit inherits from: CICM::Conduit, CICM::Decrypt::Controller and CICM::Decrypt::Stream.

3.5.7.7. Interface CICM::Decrypt::NegotiatedConduit

CICM::Decrypt::NegotiatedConduit is the negotiated version of CICM::Decrypt::Conduit. It is the result of a successful negotiation by CICM::Decrypt::Negotiator.

3.5.7.7.1. CICM::Decrypt::NegotiatedConduit Inheritance

CICM::Decrypt::NegotiatedConduit inherits from: CICM::Conduit, CICM::Decrypt::NegotiatedController and CICM::Decrypt::Stream.

3.5.7.8. Interface CICM::Decrypt::WithMACConduit

CICM::Decrypt::WithMACConduit supports decryption operations between two independent security domains with the receipt of an indication as to whether MAC verification succeeded or failed in the initiating domain. The resulting conduit is capable of both managing the channel and accepting data for transformation. It is created by calling CICM::ChannelManager::create_decrypt_with_mac_conduit.

3.5.7.8.1. CICM::Decrypt::WithMACConduit Inheritance

CICM::Decrypt::WithMACConduit inherits from: CICM::AbstractMACVerifyConduit and CICM::Decrypt::Conduit.

3.5.7.9. Interface CICM::Decrypt::WithMACNegotiatedConduit

CICM::Decrypt::WithMACNegotiatedConduit is the negotiated version of CICM::Decrypt::WithMACConduit. It is the result of a successful negotiation by CICM::Decrypt::WithMACNegotiator.

3.5.7.9.1. CICM::Decrypt::WithMACNegotiatedConduit Inheritance

CICM::Decrypt::WithMACNegotiatedConduit inherits from: CICM::AbstractMACVerifyConduit and CICM::Decrypt::NegotiatedConduit.

3.5.7.10. Interface CICM::Decrypt::WithVerifyConduit

CICM::Decrypt::WithVerifyConduit supports decryption operations between two independent security domains with the receipt of an indication as to whether signature verification succeeded or failed in the initiating domain. The resulting conduit is capable of both managing the channel and accepting transformed data. It is created by calling CICM::ChannelManager::create_decrypt_with_verify_conduit.

3.5.7.10.1. CICM::Decrypt::WithVerifyConduit Inheritance

CICM::Decrypt::WithVerifyConduit inherits from: CICM::AbstractSigVerifyConduit and CICM::Decrypt::Conduit.

3.5.7.11. Interface CICM::Decrypt::WithVerifyNegotiatedConduit

CICM::Decrypt::WithVerifyNegotiatedConduit is the negotiated version of CICM::Decrypt::WithVerifyConduit. It is the result of a successful negotiation by CICM::Decrypt::WithVerifyNegotiator.

3.5.7.11.1. CICM::Decrypt::WithVerifyNegotiatedConduit Inheritance

CICM::Decrypt::WithVerifyNegotiatedConduit inherits from: CICM::AbstractSigVerifyConduit and CICM::Decrypt::NegotiatedConduit.

3.5.7.12. Interface CICM::Decrypt::KeyUnwrapConduit

CICM::Decrypt::KeyUnwrapConduit supports key unwrapping operations between two independent security domains. The resulting conduit is capable of both managing the channel and accepting transformed keys. It is created by calling CICM::ChannelManager::create_key_unwrap_conduit.

3.5.7.12.1. CICM::Decrypt::KeyUnwrapConduit Inheritance

CICM::Decrypt::KeyUnwrapConduit inherits from: CICM::Decrypt::Controller and CICM::Decrypt::KeyUnwrapStream.

3.5.7.13. Interface CICM::Decrypt::Negotiator

CICM::Decrypt::Negotiator initiates a negotiation to establish a shared key with a remote entity that is used to support encryption operations between two independent security domains. The result of a successful negotiation is a CICM::Decrypt::NegotiatedConduit which is capable of both managing the channel and accepting data for transformation. CICM::Decrypt::Negotiator is created by calling CICM::ChannelManager::negotiate_decrypt_conduit.

3.5.7.13.1. CICM::Decrypt::Negotiator Inheritance

3.5.7.13.2. CICM::Decrypt::Negotiator Methods

3.5.7.14. Interface CICM::Decrypt::ControllerNegotiator

CICM::Decrypt::ControllerNegotiator initiates a negotiation to establish a shared key with a remote entity that is used to support decryption operations between two independent security domains. The result of a successful negotiation is a CICM::Decrypt::NegotiatedController which is capable of managing the channel, but not accepting data for transformation. CICM::Decrypt::ControllerNegotiator is created by calling CICM::ChannelManager::negotiate_decrypt_controller.

3.5.7.14.1. CICM::Decrypt::ControllerNegotiator Inheritance

3.5.7.14.2. CICM::Decrypt::ControllerNegotiator Methods

3.5.7.15. Interface CICM::Decrypt::WithMACNegotiator

CICM::Decrypt::WithMACNegotiator initiates a negotiation to establish a shared key with a remote entity that is used to support decryption operations between two independent security domains. Additionally, a message authentication code is received in the initiating domain. The result of a successful negotiation is a CICM::Decrypt::WithMACNegotiatedConduit which is capable of both managing the channel and accepting data for transformation. CICM::Decrypt::WithMACNegotiator is created by calling CICM::ChannelManager::negotiate_decrypt_with_mac_conduit.

3.5.7.15.1. CICM::Decrypt::WithMACNegotiator Inheritance

3.5.7.15.2. CICM::Decrypt::WithMACNegotiator Methods

3.5.7.16. Interface CICM::Decrypt::WithVerifyNegotiator

CICM::Decrypt::WithVerifyNegotiator initiates a negotiation to establish a shared key with a remote entity that is used to support decryption operations between two independent security domains. Additionally, an indication as to whether verification succeeded or failed is received in the initiating domain. The result of a successful negotiation is a CICM::Decrypt::WithVerifyNegotiatedConduit which is capable of both managing the channel and accepting data for transformation. CICM::Decrypt::WithVerifyNegotiator is created by calling CICM::ChannelManager::negotiate_decrypt_with_verify_conduit.

3.5.7.16.1. CICM::Decrypt::WithVerifyNegotiator Inheritance

3.5.7.16.2. CICM::Decrypt::WithVerifyNegotiator Methods

3.5.8. Duplex Channel Management

The CICM::Duplex namespace contains interfaces that support encryption/decryption operations between two independent security domains.

3.5.8.1. Interface CICM::Duplex::ChannelManager

CICM::Duplex::ChannelManager is an abstraction inherited by CICM::ChannelManager that supports the creation of encryption/decryption negotiators, conduits, controllers, and streams. See CICM::ChannelManager for additional information.

3.5.8.1.1. CICM::Duplex::ChannelManager Methods

Initiate a negotiation to establish a shared key with a peer, resulting in a conduit that results will encrypt/decrypt data.

Initiate a negotiation to establish a shared key with a peer, resulting in a controller to manage a duplex channel.

Create stream associated with previously created controller to accept data for transformation.

3.5.8.2. Interface CICM::Duplex::Stream

CICM::Duplex::Stream supports encryption/decryption operations between two independent security domains. The resulting stream is capable of accepting data for transformation and receiving transformed data, but not managing the channel. It is created by calling CICM::ChannelManager::get_duplex_stream.

3.5.8.2.1. CICM::Duplex::Stream Inheritance

CICM::Duplex::Stream inherits from: CICM::Encrypt::Stream and CICM::Decrypt::Stream.

3.5.8.3. Interface CICM::Duplex::Controller

CICM::Duplex::Controller supports encryption/decryption operations between two independent security domains. The resulting controller is capable of managing the channel, but not accepting data for transformation and receiving transformed data. It is created by calling CICM::ChannelManager::create_duplex_controller.

3.5.8.3.1. CICM::Duplex::Controller Inheritance

CICM::Duplex::Controller inherits from: CICM::Encrypt::Controller and CICM::Decrypt::Controller.

3.5.8.4. Interface CICM::Duplex::NegotiatedController

CICM::Duplex::NegotiatedController is the negotiated version of CICM::Duplex::Controller. It is the result of a successful negotiation by CICM::Duplex::ControllerNegotiator.

3.5.8.4.1. CICM::Duplex::NegotiatedController Inheritance

CICM::Duplex::NegotiatedController inherits from: CICM::Encrypt::NegotiatedController and CICM::Decrypt::NegotiatedController.

3.5.8.5. Interface CICM::Duplex::Conduit

CICM::Duplex::Conduit supports encryption/decryption operations between two independent security domains. The resulting conduit is capable of both managing the channel and accepting data for transformation and receiving transformed data. It is created by calling CICM::ChannelManager::create_duplex_conduit.

3.5.8.5.1. CICM::Duplex::Conduit Inheritance

CICM::Duplex::Conduit inherits from: CICM::Conduit, CICM::Duplex::Controller and CICM::Duplex::Stream.

3.5.8.6. Interface CICM::Duplex::NegotiatedConduit

CICM::Duplex::NegotiatedConduit is the negotiated version of CICM::Duplex::Conduit. It is the result of a successful negotiation by CICM::Duplex::Negotiator.

3.5.8.6.1. CICM::Duplex::NegotiatedConduit Inheritance

CICM::Duplex::NegotiatedConduit inherits from: CICM::Duplex::NegotiatedController and CICM::Duplex::Stream.

3.5.8.7. Interface CICM::Duplex::ControllerNegotiator

CICM::Duplex::ControllerNegotiator initiates a negotiation to establish a shared key with a remote entity that is used to support encryption/decryption operations between two independent security domains. The result of a successful negotiation is a CICM::Duplex::NegotiatedController which is capable of managing the channel, but not accepting data for transformation. CICM::Duplex::ControllerNegotiator is created by calling CICM::ChannelManager::negotiate_duplex_controller.

3.5.8.7.1. CICM::Duplex::ControllerNegotiator Inheritance

3.5.8.7.2. CICM::Duplex::ControllerNegotiator Methods

3.5.8.8. Interface CICM::Duplex::Negotiator

CICM::Duplex::Negotiator initiates a negotiation to establish a shared key with a remote entity that is used to support encryption/decryption operations between two independent security domains. The result of a successful negotiation is a CICM::Duplex::NegotiatedConduit which is capable of both managing the channel and accepting data for transformation. CICM::Duplex::Negotiator is created by calling CICM::ChannelManager::negotiate_duplex_conduit.

3.5.8.8.1. CICM::Duplex::Negotiator Inheritance

3.5.8.8.2. CICM::Duplex::Negotiator Methods

3.5.9. Bypass (Send) Channel Managment

The CICM::BypassWrite namespace contains channels that support full bypass write operations between two independent security domains.

3.5.9.1. Interface CICM::BypassWrite::ChannelManager

CICM::BypassWrite::ChannelManager is an abstraction inherited by CICM::ChannelManager that supports the creation of full bypass conduits, controllers, and streams for writing. See CICM::ChannelManager for additional information.

3.5.9.1.1. CICM::BypassWrite::ChannelManager Methods

Returns the stream corresponding to a pre-existing controller on the given local port.

3.5.9.2. Interface CICM::BypassWrite::Stream

CICM::BypassWrite::Stream supports full bypass between two independent security domains. The resulting stream is capable of accepting data for bypass, but not managing the channel. It is created by calling CICM::ChannelManager::get_bypass_write_stream.

3.5.9.2.1. CICM::BypassWrite::Stream Inheritance

3.5.9.2.2. CICM::BypassWrite::Stream Methods

Write bypass data to a channel stream. The method blocks until the data has been sent.

Registers a buffer of data to be sent to the module for bypass and then immediately returns control to the caller. The length of the data is encapsulated in the buffer parameter. The caller may use the CICM::BypassWrite::Stream::write_bypass_poll method to proactively poll the channel to determine the status of the operation. The caller is responsible for maintaining any necessary metadata associated with the transaction_id parameter. Memory responsibilities and calling conventions shall follow the appropriate IDL language mapping conventions.

Returns the status of the non-blocking bypass operation specified by the transaction_id parameter. Memory responsibilities and calling conventions shall follow the appropriate IDL language mapping conventions.

3.5.9.3. Interface CICM::BypassWrite::Controller

CICM::BypassWrite::Controller supports full bypass between two independent security domains. The resulting controller is capable of managing the channel, but not accepting data for bypass. It is created by calling CICM::ChannelManager::create_bypass_write_controller.

3.5.9.3.1. CICM::BypassWrite::Controller Inheritance

3.5.9.4. Interface CICM::BypassWrite::Conduit

CICM::BypassWrite::Conduit supports full bypass between two security domains. The resulting conduit is capable of both managing the channel and accepting data for bypass. It is created by calling CICM::ChannelManager::create_bypass_write_conduit.

3.5.9.4.1. CICM::BypassWrite::Conduit Inheritance

CICM::BypassWrite::Conduit inherits from: CICM::Conduit, CICM::BypassWrite::Controller and CICM::BypassWrite::Stream.

3.5.10. Bypass (Read) Channel Management

The CICM::BypassRead namespace contains channels that support full bypass read operations between two independent security domains.

3.5.10.1. Interface CICM::BypassRead::ChannelManager

CICM::BypassRead::ChannelManager is an abstraction inherited by CICM::ChannelManager that supports the creation of full bypass conduits, controllers, and streams for reading. See CICM::ChannelManager for additional information.

3.5.10.1.1. CICM::BypassRead::ChannelManager Methods

Returns the stream corresponding to a pre-existing controller on the given local port.

3.5.10.2. Interface CICM::BypassRead::Stream

CICM::BypassRead::Stream supports full bypass between two independent security domains. The resulting stream is capable of accepting bypassed data, but not managing the channel. It is created by calling CICM::ChannelManager::get_bypass_read_stream.

3.5.10.2.1. CICM::BypassRead::Stream Inheritance

3.5.10.2.2. CICM::BypassRead::Stream Methods

Read bypass data off of channel stream. The method blocks until data becomes available.

Registers a buffer into which bypass data will be copied, and then immediately returns control to the caller. The size of the allocated buffer and length of the resulting bypassed data is encapsulated in the buffer parameter. The caller may use the CICM::BypassRead::Stream::read_bypass_poll method to proactively poll the channel to determine the status of the operation. The caller is responsible for maintaining any necessary metadata associated with the transaction_id parameter. Memory responsibilities and calling conventions shall follow the appropriate IDL language mapping conventions.

Returns the status of the non-blocking bypass operation specified by the transaction_id parameter. Upon completion of the operation, the caller must use the metadata associated with the transaction_id parameter to determine which buffer has been populated. Memory responsibilities and calling conventions shall follow the appropriate IDL language mapping conventions.

3.5.10.3. Interface CICM::BypassRead::Controller

CICM::BypassRead::Controller supports full bypass between two independent security domains. The resulting controller is capable of managing the channel, but not accepting bypassed data. It is created by calling CICM::ChannelManager::create_bypass_read_controller.

3.5.10.3.1. CICM::BypassRead::Controller Inheritance

3.5.10.4. Interface CICM::BypassRead::Conduit

CICM::BypassRead::Conduit supports full bypass between two independent security domains. The resulting conduit is capable of both managing the channel and accepting bypassed data. It is created by calling CICM::ChannelManager::create_bypass_read_conduit.

3.5.10.4.1. CICM::BypassRead::Conduit Inheritance

CICM::BypassRead::Conduit inherits from: CICM::Conduit, CICM::BypassRead::Controller and CICM::BypassRead::Stream.

3.5.11. Encryption with Selective Bypass Channel Management

The CICM::EncryptBypass namespace contains interfaces that support encryption with selective bypass operations between two indepenent security domains.

Figure 36. Interface Relationship Diagram for Encryption Channels with Selective Bypass

3.5.11.1. Interface CICM::EncryptBypass::ChannelManager

CICM::EncryptBypass::ChannelManager is an abstraction inherited by CICM::ChannelManager that supports the creation of encryption with selective bypass negotiators, conduits, controllers, and streams. See CICM::ChannelManager for additional information.

3.5.11.1.1. CICM::EncryptBypass::ChannelManager Methods

Initiate a negotiation to establish a shared key with a peer. The channel that results will selectively encrypt or bypass a stream of data.

Method CICM::EncryptBypass::ChannelManager::negotiate_encrypt_bypass_controller()

Initiate a negotiation to establish a shared key with a peer, resulting in a controller to manage an encrypt with bypass channel.

Create stream associated with previously created controller to accept data for transformation.

3.5.11.2. Interface CICM::EncryptBypass::Stream

CICM::EncryptBypass::Stream supports encryption and selective bypass operations between two independent security domains. The resulting stream is capable of accepting data for transformation, but not managing the channel. It is created by calling CICM::ChannelManager::get_encrypt_bypass_stream.

3.5.11.2.1. CICM::EncryptBypass::Stream Inheritance

CICM::EncryptBypass::Stream inherits from: CICM::Encrypt::Stream and CICM::BypassWrite::Stream.

3.5.11.3. Interface CICM::EncryptBypass::NegotiatedController

CICM::EncryptBypass::NegotiatedController is the negotiated version of CICM::EncryptBypass::Controller. It is the result of a successful negotiation by CICM::EncryptBypass::ControllerNegotiator.

3.5.11.3.1. CICM::EncryptBypass::NegotiatedController Inheritance

CICM::EncryptBypass::NegotiatedController inherits from: CICM::Encrypt::NegotiatedController.

3.5.11.4. Interface CICM::EncryptBypass::Controller

CICM::EncryptBypass::Controller supports encryption and selective bypass operations between two independent security domains. The resulting controller is capable of managing the channel, but not accepting data for transformation/bypass. It is created by calling CICM::ChannelManager::create_encrypt_bypass_controller.

3.5.11.4.1. CICM::EncryptBypass::Controller Inheritance

3.5.11.5. Interface CICM::EncryptBypass::Conduit

CICM::EncryptBypass::Conduit supports encryption and selective bypass operations between two independent security domains. The resulting conduit is capable of both managing the channel and accepting data for transformation/bypass. It is created by calling CICM::ChannelManager::create_encrypt_bypass_conduit.

3.5.11.5.1. CICM::EncryptBypass::Conduit Inheritance

CICM::EncryptBypass::Conduit inherits from: CICM::Encrypt::Conduit and CICM::EncryptBypass::Stream.

3.5.11.6. Interface CICM::EncryptBypass::NegotiatedConduit

CICM::EncryptBypass::NegotiatedConduit is the negotiated version of CICM::EncryptBypass::Conduit. It is the result of a successful negotiation by CICM::EncryptBypass::Negotiator.

3.5.11.6.1. CICM::EncryptBypass::NegotiatedConduit Inheritance

CICM::EncryptBypass::NegotiatedConduit inherits from: CICM::Encrypt::NegotiatedController and CICM::EncryptBypass::Stream.

3.5.11.7. Interface CICM::EncryptBypass::ControllerNegotiator

CICM::EncryptBypass::ControllerNegotiator initiates a negotiation to establish a shared key with a remote entity that is used to support encryption and selective bypass operations between two independent security domains. The result of a successful negotiation is a CICM::EncryptBypass::NegotiatedController which is capable of managing the channel, but not accepting data for transformation/bypass. CICM::EncryptBypass::ControllerNegotiator is created by calling CICM::ChannelManager::negotiate_encrypt_bypass_controller.

3.5.11.7.1. CICM::EncryptBypass::ControllerNegotiator Inheritance

3.5.11.7.2. CICM::EncryptBypass::ControllerNegotiator Methods

Complete negotiation and retrieve a negotiated encrypt bypass control-only channel.

3.5.11.8. Interface CICM::EncryptBypass::Negotiator

CICM::EncryptBypass::Negotiator initiates a negotiation to establish a shared key with a remote entity that is used to support encryption and bypass operations between two independent security domains. Additionally, selective bypass is supported on the same conduit. The result of a successful negotiation is a CICM::EncryptBypass::NegotiatedConduit which is capable of both managing the channel and accepting data for transformation/bypass. CICM::EncryptBypass::Negotiator is created by calling CICM::ChannelManager::negotiate_encrypt_bypass_conduit.

3.5.11.8.1. CICM::EncryptBypass::Negotiator Inheritance

3.5.11.8.2. CICM::EncryptBypass::Negotiator Methods

3.5.12. Decryption with Selective Bypass Channel Management

The CICM::DecryptBypass namespace contains interfaces that support decryption with selective bypass operations between two independent security domains.

Figure 37. Interface Relationship Diagram for Decryption Channels with Selective Bypass

3.5.12.1. Interface CICM::DecryptBypass::ChannelManager

CICM::DecryptBypass::ChannelManager is an abstraction inherited by CICM::ChannelManager that supports the creation of decryption with selective bypass negotiators, conduits, controllers, and streams. See CICM::ChannelManager for additional information.

3.5.12.1.1. CICM::DecryptBypass::ChannelManager Methods

Initiate a negotiation to establish a shared key with a peer. The channel that results will selectively decrypt or bypass a stream of data.

Method CICM::DecryptBypass::ChannelManager::negotiate_decrypt_bypass_controller()

Initiate a negotiation to establish a shared key with a peer, resulting in a controller to manage a decrypt with bypass channel.

Create stream associated with previously created controller to receive transformed data.

3.5.12.2. Interface CICM::DecryptBypass::Stream

CICM::DecryptBypass::Stream supports decryption and selective bypass operations between two independent security domains. The resulting stream is capable of accepting transformed/bypassed data, but not managing the channel. It is created by calling CICM::ChannelManager::get_decrypt_bypass_stream.

3.5.12.2.1. CICM::DecryptBypass::Stream Inheritance

3.5.12.3. Interface CICM::DecryptBypass::Controller

CICM::DecryptBypass::Controller supports decryption and selective bypass operations between two independent security domains. The resulting controller is capable of managing the channel, but not accepting transformed/bypassed data. It is created by calling CICM::ChannelManager::create_decrypt_bypass_controller.

3.5.12.3.1. CICM::DecryptBypass::Controller Inheritance

3.5.12.4. Interface CICM::DecryptBypass::NegotiatedController

CICM::DecryptBypass::NegotiatedController is the negotiated version of CICM::DecryptBypass::Controller. It is the result of a successful negotiation by CICM::DecryptBypass::ControllerNegotiator.

3.5.12.4.1. CICM::DecryptBypass::NegotiatedController Inheritance

CICM::DecryptBypass::NegotiatedController inherits from: CICM::Decrypt::NegotiatedController.

3.5.12.5. Interface CICM::DecryptBypass::Conduit

CICM::DecryptBypass::Conduit supports decryption and selective bypass operations between two independent security domains. The resulting conduit is capable of both managing the channel and accepting transformed/bypassed data. It is created by calling CICM::ChannelManager::create_decrypt_bypass_conduit.

3.5.12.5.1. CICM::DecryptBypass::Conduit Inheritance

CICM::DecryptBypass::Conduit inherits from: CICM::Decrypt::Conduit, CICM::DecryptBypass::Controller and CICM::DecryptBypass::Stream.

3.5.12.6. Interface CICM::DecryptBypass::NegotiatedConduit

CICM::DecryptBypass::NegotiatedConduit is the negotiated version of CICM::DecryptBypass::Conduit. It is the result of a successful negotiation by CICM::DecryptBypass::Negotiator.

3.5.12.6.1. CICM::DecryptBypass::NegotiatedConduit Inheritance

CICM::DecryptBypass::NegotiatedConduit inherits from: CICM::Decrypt::NegotiatedConduit, CICM::DecryptBypass::NegotiatedController and CICM::DecryptBypass::Stream.

3.5.12.7. Interface CICM::DecryptBypass::ControllerNegotiator

CICM::DecryptBypass::ControllerNegotiator initiates a negotiation to establish a shared key with a remote entity that is used to support encryption and selective bypass operations between two independent security domains. The result of a successful negotiation is a CICM::DecryptBypass::NegotiatedController which is capable of managing the channel, but not accepting data for transformation. CICM::DecryptBypass::ControllerNegotiator is created by calling CICM::ChannelManager::negotiate_decrypt_bypass_controller.

3.5.12.7.1. CICM::DecryptBypass::ControllerNegotiator Inheritance

3.5.12.7.2. CICM::DecryptBypass::ControllerNegotiator Methods

Complete negotiation and retrieve a negotiated control-only decrypt bypass channel.

3.5.12.8. Interface CICM::DecryptBypass::Negotiator

CICM::DecryptBypass::Negotiator initiates a negotiation to establish a shared key with a remote entity that is used to support encryption operations between two independent security domains. Additionally, selective bypass is supported on the same conduit. The result of a successful negotiation is a CICM::DecryptBypass::NegotiatedConduit which is capable of both managing the channel and accepting data for transformation. CICM::DecryptBypass::Negotiator is created by calling CICM::ChannelManager::negotiate_decrypt_bypass_conduit.

3.5.12.8.1. CICM::DecryptBypass::Negotiator Inheritance

3.5.12.8.2. CICM::DecryptBypass::Negotiator Methods

3.5.13. Random, Pseudorandom and Keystream Channel Management

The CICM::Emit namespace contains interfaces that generate data originating in a cryptographic module such as random, pseudorandom, and keystream data.

Figure 38. Interface Relationship Diagram for Keystream Generation and Random Channels

3.5.13.1. Interface CICM::Emit::ChannelManager

CICM::Emit::ChannelManager is an abstraction inherited by CICM::ChannelManager that supports the creation of conduits and controllers to generate keystream, pseudorandom, and random data. See CICM::ChannelManager for additional information.

3.5.13.1.1. CICM::Emit::ChannelManager Methods

3.5.13.2. Interface CICM::Emit::GetStream

CICM::Emit::GetStream is an abstraction inherited by conduits in the CICM::Emit namespace that allows data to be read from the stream.

3.5.13.2.1. CICM::Emit::GetStream Inheritance

3.5.13.2.2. CICM::Emit::GetStream Methods

Reads a buffer of data from the module. The method blocks until data becomes available.

Registers a buffer into which transformed data will be copied, and then control immediately returns to the caller. The size of the allocated buffer and length of the resulting transformed data is encapsulated in the buffer parameter. The caller may use the CICM::Emit::GetStream::get_poll method to proactively poll the channel to determine the status of the operation. The caller is responsible for maintaining any necessary metadata associated with the transaction_id parameter. Memory responsibilities and calling conventions shall follow the appropriate IDL language mapping conventions.

Returns the status of the non-blocking get operation specified by the transaction_id parameter. Upon completion of the operation, the caller must use the metadata associated with the transaction_id parameter to determine which buffer has been populated. Memory responsibilities and calling conventions shall follow the appropriate IDL language mapping conventions.

3.5.13.3. Interface CICM::Emit::Controller

CICM::Emit::Controller is an abstraction from which all other controllers in the CICM::Emit namespace inherit.

3.5.13.3.1. CICM::Emit::Controller Inheritance

3.5.13.3.2. CICM::Emit::Controller Attributes

3.5.13.4. Interface CICM::Emit::RandomController

CICM::Emit::RandomController supports creating a channel to read random data from a module. The resulting controller is capable of managing the channel, but not reading random data. It is created by calling CICM::ChannelManager::create_random_controller.

3.5.13.4.1. CICM::Emit::RandomController Inheritance

3.5.13.5. Interface CICM::Emit::RandomConduit

CICM::Emit::RandomConduit supports reading random data from a module. The resulting conduit is capable of both managing the channel and reading random data. It is created by calling CICM::ChannelManager::create_random_conduit.

3.5.13.5.1. CICM::Emit::RandomConduit Inheritance

CICM::Emit::RandomConduit inherits from: CICM::Conduit and CICM::Emit::GetStream.

3.5.13.6. Interface CICM::Emit::PseudoRandomController

CICM::Emit::PseudoRandomController supports creating a channel to read pseudorandom data from a module. The resulting controller is capable of managing the channel, but not reading pseudorandom data. It is created by calling CICM::ChannelManager::create_pseudorandom_controller.

3.5.13.6.1. CICM::Emit::PseudoRandomController Inheritance

CICM::Emit::PseudoRandomController inherits from: CICM::SymKeyController and CICM::Emit::Controller.

3.5.13.7. Interface CICM::Emit::PseudoRandomConduit

CICM::Emit::PseudoRandomConduit supports reading pseudorandom data from a module. The resulting conduit is capable of both managing the channel and reading pseudorandom data. It is created by calling CICM::ChannelManager::create_pseudorandom_conduit.

3.5.13.7.1. CICM::Emit::PseudoRandomConduit Inheritance

CICM::Emit::PseudoRandomConduit inherits from: CICM::Conduit, CICM::SymKeyController and CICM::Emit::GetStream.

3.5.13.8. Interface CICM::Emit::KeyStreamGenController

CICM::Emit::KeyStreamGenController supports creating a channel to read keystream from a module. The resulting controller is capable of managing the channel, but not reading keystream. It is created by calling CICM::ChannelManager::create_key_stream_gen_controller.

3.5.13.8.1. CICM::Emit::KeyStreamGenController Inheritance

CICM::Emit::KeyStreamGenController inherits from: CICM::SymKeyController, CICM::GenVectorController and CICM::Emit::Controller.

3.5.13.9. Interface CICM::Emit::KeyStreamGenConduit

CICM::Emit::KeyStreamGenConduit supports reading keystream from a module. The resulting conduit is capable of both managing the channel and reading keystream. It is created by calling CICM::ChannelManager::create_key_stream_gen_conduit.

3.5.13.9.1. CICM::Emit::KeyStreamGenConduit Inheritance

CICM::Emit::KeyStreamGenConduit inherits from: CICM::Conduit, CICM::SymKeyController, CICM::GenVectorController and CICM::Emit::GetStream.

3.5.14. Integrity Channel Management

The CICM::Answer namespace contains interfaces that support cryptographic operations that return an "answer" such a hash or a signature within a single security domain.

3.5.14.1. Interface CICM::Answer::ChannelManager

CICM::Answer::ChannelManager is an abstraction inherited by CICM::ChannelManager that supports the creation of conduits to sign, MAC, and hash data. See CICM::ChannelManager for additional information.

3.5.14.1.1. CICM::Answer::ChannelManager Methods

Create conduit to calculate and generate a signature accepting a previously generated hash value as input.

Create conduit to verify a signature accepting a previously generated hash value as input.

3.5.14.2. Interface CICM::Answer::PutStream

3.5.14.2.1. CICM::Answer::PutStream Inheritance

3.5.14.2.2. CICM::Answer::PutStream Methods

3.5.14.3. Interface CICM::Answer::HashConduit

CICM::Answer::HashConduit supports hashing operations within a single security domain. It is created by calling CICM::ChannelManager::create_hash_conduit.

3.5.14.3.1. CICM::Answer::HashConduit Inheritance

CICM::Answer::HashConduit inherits from: CICM::Conduit and CICM::Answer::PutStream.

3.5.14.3.2. CICM::Answer::HashConduit Attributes

3.5.14.3.3. CICM::Answer::HashConduit Methods

Direct the module to compute and output the message digest value, and reset the conduit to accept additional data.

3.5.14.4. Interface CICM::Answer::MACConduit

CICM::Answer::MACConduit supports message authentication code operations within a single security domain. It is created by calling CICM::ChannelManager::create_mac_conduit.

3.5.14.4.1. CICM::Answer::MACConduit Inheritance

CICM::Answer::MACConduit inherits from: CICM::AbstractMACConduit and CICM::Answer::PutStream.

3.5.14.5. Interface CICM::Answer::MACVerifyConduit

CICM::Answer::MACVerifyConduit supports message authentication code verification operations within a single security domain. It is created by calling CICM::ChannelManager::create_mac_verify_conduit.

3.5.14.5.1. CICM::Answer::MACVerifyConduit Inheritance

CICM::Answer::MACVerifyConduit inherits from: CICM::AbstractMACVerifyConduit and CICM::Answer::PutStream.

3.5.14.6. Interface CICM::Answer::SignConduit

CICM::Answer::SignConduit supports signature operations within a single security domain. It is created by calling CICM::ChannelManager::create_sign_conduit.

3.5.14.6.1. CICM::Answer::SignConduit Inheritance

CICM::Answer::SignConduit inherits from: CICM::AbstractSignConduit and CICM::Answer::PutStream.

3.5.14.7. Interface CICM::Answer::SignHashConduit

CICM::Answer::SignHashConduit supports signature operations accepting a pre-generated hash value within a single security domain. It is created by calling CICM::ChannelManager::create_sign_hash_conduit.

3.5.14.7.1. CICM::Answer::SignHashConduit Inheritance

3.5.14.8. Interface CICM::Answer::VerifyConduit

CICM::Answer::VerifyConduit supports verification operations within a single security domain. It is created by calling CICM::ChannelManager::create_verify_conduit.

3.5.14.8.1. CICM::Answer::VerifyConduit Inheritance

CICM::Answer::VerifyConduit inherits from: CICM::AbstractSigVerifyConduit and CICM::Answer::PutStream.

3.5.14.9. Interface CICM::Answer::VerifyHashConduit

CICM::Answer::VerifyHashConduit supports verification operations accepting a pre-generated hash value within a single security domain. It is created by calling CICM::ChannelManager::create_verify_hash_conduit.

3.5.14.9.1. CICM::Answer::VerifyHashConduit Inheritance

3.5.15. Single-Domain Channel Management

The CICM::Coprocessor namespace contains interfaces that support encryption/decryption operations within a single security domain.

3.5.15.1. Interface CICM::Coprocessor::ChannelManager

CICM::Coprocessor::ChannelManager is an abstraction inherited by CICM::ChannelManager that supports the creation of conduits to encrypt and decrypt data within a single security domain. See CICM::ChannelManager for additional information.

3.5.15.1.1. CICM::Coprocessor::ChannelManager Methods

Method CICM::Coprocessor::ChannelManager::create_coprocessor_encrypt_with_mac_conduit()

Create conduit to MAC and encrypt a stream of data within a single security domain.

Method CICM::Coprocessor::ChannelManager::create_coprocessor_encrypt_with_sign_conduit()

Create conduit to sign and encrypt a stream of data within a single security domain.

Method CICM::Coprocessor::ChannelManager::create_coprocessor_decrypt_with_mac_conduit()

Create conduit to MAC verify and decrypt a stream of data within a single security domain.

Method CICM::Coprocessor::ChannelManager::create_coprocessor_decrypt_with_verify_conduit()

Create conduit to verify and decrypt a stream of data within a single security domain.

3.5.15.2. Interface CICM::Coprocessor::Stream

CICM::Coprocessor::Stream is an abstraction inherited by all conduits in the CICM::Coprocessor namespace.

3.5.15.2.1. CICM::Coprocessor::Stream Inheritance

3.5.15.2.2. CICM::Coprocessor::Stream Methods

Returns the final block of transformed data, if available. The method blocks until data becomes available.

3.5.15.3. Interface CICM::Coprocessor::EncryptConduit

CICM::Coprocessor::EncryptConduit supports encryption operations within a single security domain. The resulting conduit is capable of managing the channel, accepting data for transformation, and receiving the result. It is created by calling CICM::ChannelManager::create_coprocessor_encrypt_conduit.

3.5.15.3.1. CICM::Coprocessor::EncryptConduit Inheritance

CICM::Coprocessor::EncryptConduit inherits from: CICM::Conduit, CICM::SymKeyController, CICM::GenVectorController, CICM::ResyncController and CICM::Coprocessor::Stream.

3.5.15.3.2. CICM::Coprocessor::EncryptConduit Methods

Send plaintext to the module to be encrypted, receiving the ciphertext resulting from the transformation as the result.

3.5.15.4. Interface CICM::Coprocessor::EncryptWithMACConduit

CICM::Coprocessor::EncryptWithMACConduit supports encryption with MAC operations within a single security domain. The resulting conduit is capable of managing the channel, accepting data for transformation, and receiving the result (both ciphertext and a MAC value). It is created by calling CICM::ChannelManager::create_coprocessor_encrypt_with_mac_conduit.

3.5.15.4.1. CICM::Coprocessor::EncryptWithMACConduit Inheritance

CICM::Coprocessor::EncryptWithMACConduit inherits from: CICM::AbstractMACConduit and CICM::Coprocessor::EncryptConduit.

3.5.15.5. Interface CICM::Coprocessor::EncryptWithSignConduit

CICM::Coprocessor::EncryptWithSignConduit supports encryption with signature operations within a single security domain. The resulting conduit is capable of managing the channel, accepting data for transformation, and receiving the result (both ciphertext and a signature). It is created by calling CICM::ChannelManager::create_coprocessor_encrypt_with_sign_conduit.

3.5.15.5.1. CICM::Coprocessor::EncryptWithSignConduit Inheritance

CICM::Coprocessor::EncryptWithSignConduit inherits from: CICM::AbstractSignConduit and CICM::Coprocessor::EncryptConduit.

3.5.15.6. Interface CICM::Coprocessor::DecryptConduit

CICM::Coprocessor::DecryptConduit supports decryption operations within a single security domain. The resulting conduit is capable of managing the channel, accepting data for transformation, and receiving the result. It is created by calling CICM::ChannelManager::create_coprocessor_decrypt_conduit.

3.5.15.6.1. CICM::Coprocessor::DecryptConduit Inheritance

CICM::Coprocessor::DecryptConduit inherits from: CICM::Conduit, CICM::SymKeyController, CICM::SetVectorController, CICM::ResyncController and CICM::Coprocessor::Stream.

3.5.15.6.2. CICM::Coprocessor::DecryptConduit Methods

Send ciphertext to the module to be decrypted, receiving the plaintext resulting from the transformation as the result.

3.5.15.7. Interface CICM::Coprocessor::DecryptWithMACConduit

CICM::Coprocessor::DecryptWithMACConduit supports encryption with MAC verification operations within a single security domain. The resulting conduit is capable of managing the channel, accepting data for transformation, and receiving the result (both plaintext and an indication as to whether verification succeeded or failed). It is created by calling CICM::ChannelManager::create_coprocessor_decrypt_with_mac_conduit.

3.5.15.7.1. CICM::Coprocessor::DecryptWithMACConduit Inheritance

CICM::Coprocessor::DecryptWithMACConduit inherits from: CICM::AbstractMACVerifyConduit and CICM::Coprocessor::DecryptConduit.

3.5.15.8. Interface CICM::Coprocessor::DecryptWithVerifyConduit

CICM::Coprocessor::DecryptWithVerifyConduit supports encryption with signature verification operations within a single security domain. The resulting conduit is capable of managing the channel, accepting data for transformation, and receiving the result (both plaintext and an indication as to whether verification succeeded or failed). It is created by calling CICM::ChannelManager::create_coprocessor_decrypt_with_verify_conduit.

3.5.15.8.1. CICM::Coprocessor::DecryptWithVerifyConduit Inheritance

CICM::Coprocessor::DecryptWithVerifyConduit inherits from: CICM::AbstractSigVerifyConduit and CICM::Coprocessor::DecryptConduit.

3.5.16. Channel Event Management

3.5.16.1. Interface CICM::ChannelEventManager

CICM::ChannelEventManager supports registering and unregistering user-defined channel event listeners (CICM::ChannelEventListener) for specific channel events. It is accessed from any channel via its CICM::Channel::event_manager attribute.

3.5.16.1.1. CICM::ChannelEventManager Methods

3.5.16.2. Interface CICM::ChannelEventListener

CICM::ChannelEventListener is unlike other CICM interfaces in that the interface is implemented by the developer of the client program to service a specific channel event and is then registered via the CICM::ChannelEventManager.

3.5.16.2.1. CICM::ChannelEventListener Types and Constants

Cryptographic synchronization with remote peer has been lost; this may not be detectable by the cryptographic module.

Remote peer is no longer available; this may not be detectable by the cryptographic module.

3.5.16.2.2. CICM::ChannelEventListener Methods

Method implemented by client program that receives a message about a channel event that occurred. An opaque data field with additional information about the event in a module-specific format may optionally be provided with the event itself.

3.5.17. Channel Groups

3.5.17.1. Interface CICM::ControllerGroup

3.5.17.1.1. CICM::ControllerGroup Methods

4. Conformance and Extensions

4.1. Conformance

Many modules will not require the implementation of the full specification to support a module's capabilities. Thus, the CICM conformance model was developed to be flexible. This model does not normatively prescribe the implementation of specific functional subsets of the specification. Instead, CICM outlines a normative Implementation Conformance Statement (ICS) and associated documentation that SHALL be supplied with any conformant implementation.

The ICS guides the developer of a library for a specific module to record the implementation state and presence of extensions for each section of the specification. The gradations of the implementation state are relatively coarse: "implemented," "partially implemented," or "not implemented." Extensions are identified as interface extensions or status code extensions, and are recorded as "existing" or "not-existing." An analysis of the resulting matrix enables a software developer using the API or an architect designing a system integrating with a specific cryptographic module to quickly determine if a developer's library will meet user requirements. Those specification sections marked "partially implemented" or for which extensions are indicated may require additional analysis to determine what elements have been extended or are not implemented, and the resulting repercussions on the system utilizing the library.

CICM interfaces are organized into three major sections: module management, channel management, and key management. Each section is partitioned differently into logical subsections in the ICS. The module management section is partitioned into subsections by individual module managers. The channel management section is partitioned into subsections by channel type. And the key management section is partitioned into subsections by the type of key and class of operation performed on the key.

An Implementation Data Specification (IDS) based on the ICS also is required. For each implemented interface containing an opaque data parameter (module-specific or infrastructure-specific parameter not described in detail in the specification), the IDS requires a detailed specification of the data structure for each parameter.

An implementation conforms to the specification if it meets the following conditions:

4.1.1. Implementation Conformance Statement Contents

A library implementation conforming to the CICM specification SHALL be accompanied by an ICS. The ICS is generated by the module developer or implementer of a CICM-conformant library for a specific cryptographic module configuration (including any associated hardware/firmware/software) and SHALL contain the following information:

4.1.2. Implementation Data Specification Contents

The IDS serves as the detailed supporting documentation for the ICS. Conformance with the CICM specification requires that:

Note that the event listener callbacks (CICM::ModuleEventListener::event_occurred and CICM::ChannelEventListener::event_occurred) require that the event_data parameter be described for each event type implemented.

4.1.3. Generating Unique Identifiers

CICM does not provide a list of algorithms with their corresponding normative unique identifiers. Instead, normative guidance is provided for generating the identifiers for the different classes of algorithms defined in the specification and for key agreement protocols. These identifiers are used by software developers when specifying algorithms or protocols as parameters to CICM methods. This identifier generation guidance is intended to promote interoperability, and encourage the use of the same identifier for algorithms among vendors.

Three major components may be combined to form a unique algorithm identifier: an algorithm (ALGO), that may be precisely specified as an encryption algorithm (ENCRALGO), signature algorithm (SIGALGO), MAC algorithm (MACALGO), or hash algorithm (HASHALGO); a mode (MODE); and an encoding scheme (SCHEME), that may be precisely specified as an encryption scheme (ENCRSCHEME) or a signature scheme (SIGSCHEME). Note that some components above may not apply to certain algorithms. In addition, applicable modes and components need not always be specified. For encryption and signature algorithms, if a length is required, the length SHALL be appended to the algorithm without a dash ("-") delimiter. Otherwise, components are concatenated with a dash ("-").

Alternatively, an identifier can consist of a simple personality designation (PERSONALITY). The personality consists of a combination of parameters that comprise a logically complete crypto, and specifies a specific equipment type or configuration for which algorithm, mode, and any other parameters are implicit. The designation may contain dashes.

Certain algorithms may be appropriate for and thus listed under more than one algorithm class. Below are the classes of algorithms and format of the identifiers for each class:

Two major components may be combined to form a key agreement protocol identifier: the key agreement protocol including its version number (KEYAGREEPROTO) and the protocol's associated algorithm suite including its version number (ALGOSUITE). The following is the format for key agreement protocol identifiers.

Note that the resulting identifiers may not be compatible with those identifiers defined for other module developers' implementations. A client program utilizing an identifier corresponding to one algorithm for a specific module may be required to modify the identifier for the same algorithm for a different type of module. Discrepancies may be discovered through a brief review of the ICS "Supported Algorithms" section.

4.1.4. Conformance Verification

In the future, test assertions may be made available to allow results from different organizations to be compared, and to provide proof of conformance to the specification.

4.2. Extensions

An extension is a mechanism to define functionality beyond what is defined in the official specification. In the interest of promoting interoperability, extensions to the specification are discouraged except where necessary. Extensions to the specification enable module developers to add functionality unanticipated by the specification developers and to support proprietary features.

4.2.1. Extending an Interface

Developers may augment CICM interfaces by extending CICM IDL by adding new methods/attributes to existing interfaces or by deriving off existing CICM interfaces. Extensions SHALL be documented in the ICS.

4.2.2. Extending Codes

CICM codes are constants that share a single 32-bit space. A number of datatypes for different purposes correspond to ranges in this space. The "CICM" codes are normatively defined in the specification; the "extended" codes are module developer-defined extensions. The codes, with their corresponding ranges and uses, are as follows:

Normatively-defined CICM codes SHOULD be used whenever possible. If any of the extended codes above are defined, they SHALL be documented as specified below.

4.2.2.1. Extending Status Codes

The return value from CICM methods informs the caller of the status of the call. CICM does not utilize the IDL exception mechanism to report errors.

The specification normatively defines a set of error codes in the range of 0x00000000 - 0x00001000, which may not be modified or extended. A block of codes in the range of 0x00001001 - 0x00002000 are reserved for module developer-defined status codes. Any codes defined in this range SHALL be documented in the ICS.

4.2.2.2. Extending Module/Channel Event Codes

The specification supports registering and unregistering user-defined channel event listeners for specific module and channel events. Module events in the range of 0x00003001 - 0x00004000 and channel events in the range of 0x00004001 - 0x00005000 are normatively defined and may not be modified or extended. A block of module events in the range 0x00003001 - 0x00004000 and channel events in the range of 0x00005001 - 0x00006000 are reserved for module developer-defined events. Any codes defined in this range SHALL be documented in the ICS.

4.2.2.3. Extending Constants

A number of constants are normatively defined for specification use in the range of 0x00006001 - 0x00007000. Module developer-defined constants may be specified in the range of 0x00007001 - 0x00008000. Any constants defined in this range SHALL be documented in the ICS.

5. IANA Considerations

6. Security Considerations

7. Normative References

Appendix A. Status Codes

Each method defined in CICM returns a status value to inform the caller as to the outcome of the call. The documentation for each individual method lists the status codes that may be returned in the event a call to the method results in failure.

The status value CICM::S_OK is returned if a method completes successfully. The output parameters of any methods that return a status other than CICM::S_OK are invalid and SHALL NOT be referenced or used.

For additional information concerning extending status codes, see Section 4, Conformance and Extensions.

Appendix B. Terms

Appendix C. IDL Definitions

module CICM {
  typedef unsigned long UInt32;
  typedef boolean Bool;
  typedef string CharString;
  typedef sequence<octet> Buffer;

  typedef CICM::UInt32 Status;

  typedef CICM::UInt32 LocalPort;
  typedef CICM::UInt32 RemotePort;

  typedef CICM::Buffer MACBuffer;
  typedef CICM::Buffer SigBuffer;
  typedef CICM::Buffer HashBuffer;
  typedef CICM::Buffer Vector;

  typedef CICM::CharString ModuleId;
  typedef CICM::CharString KeyId;
  typedef CICM::UInt32 TransId;

  typedef CICM::CharString ModuleRecord;
  typedef CICM::CharString TokenRecord;

  typedef CICM::CharString PackageId;
  typedef CICM::CharString AsymEncrAlgorithmId;
  typedef CICM::CharString AsymSigAlgorithmId;
  typedef CICM::CharString SymEncrAlgorithmId;
  typedef CICM::CharString SymMacAlgorithmId;
  typedef CICM::CharString HashAlgorithmId;
  typedef CICM::CharString KeyWrapAlgorithmId;
  typedef CICM::CharString ProtocolId;
  typedef CICM::CharString UserId;
  typedef CICM::CharString RoleId;

  const CICM::LocalPort FILL_INTERFACE_PORT = 0xFFFFFFEE;
  const CICM::LocalPort IMPLICIT_LOCAL_PORT = 0xFFFFFFBB;
  const CICM::RemotePort IMPLICIT_REMOTE_PORT = 0xFFFFFF99;
  const CICM::AsymEncrAlgorithmId IMPLICIT_ASYM_ENCR_ALGO = "IMPLICIT";
  const CICM::AsymSigAlgorithmId IMPLICIT_ASYM_SIG_ALGO = "IMPLICIT";
  const CICM::SymEncrAlgorithmId IMPLICIT_SYM_ENCR_ALGO = "IMPLICIT";
  const CICM::KeyWrapAlgorithmId IMPLICIT_KEY_WRAP_ALGO = "IMPLICIT";
  const CICM::SymMacAlgorithmId IMPLICIT_SYM_MAC_ALGO = "IMPLICIT";
  const CICM::ProtocolId IMPLICIT_PROTOCOL_ID = "IMPLICIT";

  typedef CICM::UInt32 Classification;
  const CICM::Classification C_LEVEL_CONFIDENTIAL = 0x00006029;
  const CICM::Classification C_LEVEL_SECRET = 0x0000602A;
  const CICM::Classification C_LEVEL_TOP_SECRET = 0x0000602C;
  const CICM::Classification C_LEVEL_UNCLASSIFIED = 0x0000602F;

  const CICM::Status S_OK = 0x00000000;
  const CICM::Status S_GENERAL_ERROR = 0x00000003;
  const CICM::Status S_NON_FUNCTIONAL = 0x00000005;
  const CICM::Status S_OPERATION_FAILED = 0x00000006;
  const CICM::Status S_POLICY_VIOLATION = 0x00000009;
  const CICM::Status S_MODULE_RESOURCES = 0x0000000A;
  const CICM::Status S_HOST_RESOURCES = 0x0000000C;
  const CICM::Status S_INVALID_STATE = 0x0000000F;
  const CICM::Status S_ALARM_STATE = 0x00000011;
  const CICM::Status S_MODULE_NOT_AVAILABLE = 0x00000012;
  const CICM::Status S_TIMEOUT = 0x00000014;
  const CICM::Status S_NOT_AUTHENTICATED = 0x00000017;
  const CICM::Status S_NOT_AUTHORIZED = 0x00000018;
  const CICM::Status S_MODULE_DOES_NOT_EXIST = 0x0000001B;
  const CICM::Status S_MODULE_IN_USE = 0x0000001D;
  const CICM::Status S_NOT_AVAILABLE = 0x0000001E;
  const CICM::Status S_INVALID_VECTOR = 0x00000021;
  const CICM::Status S_INVALID_DATA_BUFFER = 0x00000022;
  const CICM::Status S_KEY_USED_INVALID = 0x00000024;
  const CICM::Status S_KEY_USED_EXPIRED = 0x00000027;
  const CICM::Status S_KEY_USED_CLASSIFICATION = 0x00000028;
  const CICM::Status S_KEY_USED_WRAPPED = 0x0000002B;
  const CICM::Status S_KEY_USED_CONTEXT = 0x0000002D;
  const CICM::Status S_KEY_USED_COMPONENT_NOT_AVAIL = 0x0000002E;
  const CICM::Status S_KEY_INVALID = 0x00000030;
  const CICM::Status S_KEY_EXPIRED = 0x00000033;
  const CICM::Status S_KEY_INCOMPATIBLE = 0x00000035;
  const CICM::Status S_KEY_CLASSIFICATION = 0x00000036;
  const CICM::Status S_KEY_WRAPPED = 0x00000039;
  const CICM::Status S_KEY_NOT_WRAPPED = 0x0000003A;
  const CICM::Status S_KEY_NOT_WRAPPABLE = 0x0000003C;
  const CICM::Status S_KEY_NOT_EXPORTABLE = 0x0000003F;
  const CICM::Status S_KEY_WRAPPED_EXISTS = 0x00000041;
  const CICM::Status S_KEY_UNWRAPPED_EXISTS = 0x00000042;
  const CICM::Status S_KEY_UPDATE_MAX = 0x00000044;
  const CICM::Status S_KEY_INVALID_ID = 0x00000047;
  const CICM::Status S_KEY_PHYSICAL_LOC = 0x00000048;
  const CICM::Status S_KEY_ILLEGAL_CONVERSION = 0x0000004B;
  const CICM::Status S_KEY_MALFORMED = 0x0000004D;
  const CICM::Status S_KEY_METADATA_MALFORMED = 0x0000004E;
  const CICM::Status S_KEY_NO_NEXT = 0x00000050;
  const CICM::Status S_KEY_WRONG_TYPE = 0x00000053;
  const CICM::Status S_KEY_FILL_DEVICE_NOT_CONNECTED = 0x00000055;
  const CICM::Status S_KEY_FILL_NOT_INITIATED = 0x00000056;
  const CICM::Status S_KEY_TRUST_ANCHOR = 0x00000059;
  const CICM::Status S_LOCAL_PORT_INVALID = 0x0000005A;
  const CICM::Status S_LOCAL_PORT_INCOMPATIBLE = 0x0000005C;
  const CICM::Status S_LOCAL_PORT_IN_USE = 0x0000005F;
  const CICM::Status S_REMOTE_PORT_INVALID = 0x00000060;
  const CICM::Status S_REMOTE_PORT_IN_USE = 0x00000063;
  const CICM::Status S_ALGO_INVALID = 0x00000065;
  const CICM::Status S_ALGO_INCOMPATIBLE = 0x00000066;
  const CICM::Status S_TOKEN_NOT_PRESENT = 0x00000069;
  const CICM::Status S_TOKEN_ADMIN_NOT_PRESENT = 0x0000006A;
  const CICM::Status S_TOKEN_ACCESS = 0x0000006C;
  const CICM::Status S_TOKEN_RESOURCES = 0x0000006F;
  const CICM::Status S_TOKEN_ASSOC_EXISTS = 0x00000071;
  const CICM::Status S_TOKEN_ASSOC_AT_MODULE = 0x00000072;
  const CICM::Status S_TOKEN_ASSOC_AT_TOKEN = 0x00000074;
  const CICM::Status S_TOKEN_ASSOC_NOT_EXIST = 0x00000077;
  const CICM::Status S_TOKEN_ASSOC_GENERAL = 0x00000078;
  const CICM::Status S_TOKEN_DISASSOC_GENERAL = 0x0000007B;
  const CICM::Status S_TOKEN_REC_NOT_FOUND = 0x0000007D;
  const CICM::Status S_TOKEN_TIMEOUT = 0x0000007E;
  const CICM::Status S_TOKEN_LAST_ASSOCIATED = 0x00000081;
  const CICM::Status S_PACKAGE_NOT_ACTIVATABLE = 0x00000082;
  const CICM::Status S_PACKAGE_ACTIVATED = 0x00000084;
  const CICM::Status S_PACKAGE_NOT_ACTIVE = 0x00000087;
  const CICM::Status S_PACKAGE_INVALID = 0x00000088;
  const CICM::Status S_PACKAGE_TYPE_INVALID = 0x0000008B;
  const CICM::Status S_PACKAGE_KEY_NOT_AVAILABLE = 0x0000008D;
  const CICM::Status S_PACKAGE_KEY_NOT_SPECIFIED = 0x0000008E;
  const CICM::Status S_LOG_ENTRY_INVALID = 0x00000090;
  const CICM::Status S_EVENT_REGISTERED = 0x00000093;
  const CICM::Status S_EVENT_NOT_REGISTERED = 0x00000095;
  const CICM::Status S_EVENT_NOT_SUPPORTED = 0x00000096;
  const CICM::Status S_TRUSTED_DISPLAY = 0x00000099;
  const CICM::Status S_NEGOTIATION_ABORTED = 0x0000009A;
  const CICM::Status S_NEGOTIATION_FAILURE = 0x0000009C;
  const CICM::Status S_NEGOTIATION_IN_PROGRESS = 0x0000009F;
  const CICM::Status S_NEGOTIATION_NOT_IN_PROGRESS = 0x000000A0;
  const CICM::Status S_NEGOTIATION_TIMEOUT = 0x000000A3;
  const CICM::Status S_CERT_LOCAL_INVALID = 0x000000A5;
  const CICM::Status S_CERT_LOCAL_EXPIRED = 0x000000A6;
  const CICM::Status S_CERT_REMOTE_INVALID = 0x000000A9;
  const CICM::Status S_CERT_REMOTE_EXPIRED = 0x000000AA;
  const CICM::Status S_CERT_REMOTE_PATH = 0x000000AC;
  const CICM::Status S_PROTO_INVALID = 0x000000AF;
  const CICM::Status S_PROTO_INCOMPATIBLE = 0x000000B1;
  const CICM::Status S_PROTO_UNDETERMINED = 0x000000B2;
  const CICM::Status S_CHANNEL_ERROR = 0x000000B4;
  const CICM::Status S_CHANNEL_PEER_RESET = 0x000000B7;
  const CICM::Status S_CHANNEL_MAX = 0x000000B8;
  const CICM::Status S_CHANNEL_NOT_FOUND = 0x000000BB;
  const CICM::Status S_CHANNEL_IO_ERROR = 0x000000BD;
  const CICM::Status S_CHANNEL_DATA_INVALID = 0x000000BE;
  const CICM::Status S_CHANNEL_DATA_INVALID_LEN = 0x000000C0;
  const CICM::Status S_CHANNEL_BUFFER_LEN = 0x000000C3;
  const CICM::Status S_CHANNEL_IN_GROUP = 0x000000C5;
  const CICM::Status S_CHANNEL_CLASSIFICATION = 0x000000C6;
  const CICM::Status S_BYPASS_DATARATE_EXCEEDED = 0x000000C9;
  const CICM::Status S_BYPASS_DATALIMIT_EXCEEDED = 0x000000CA;
  const CICM::Status S_INTEGRITY = 0x000000CC;
  const CICM::Status S_AUTHENTICATION_FAILED = 0x000000CF;
  const CICM::Status S_USER_AUTHENTICATED = 0x000000D1;
  const CICM::Status S_USERNAME_INVALID = 0x000000D2;
  const CICM::Status S_USER_EXISTS = 0x000000D4;
  const CICM::Status S_USER_INVALID = 0x000000D7;
  const CICM::Status S_ROLE_INVALID = 0x000000D8;
  const CICM::Status S_ROLE_ASSOCIATED = 0x000000DB;
  const CICM::Status S_ROLE_NOT_ASSOCIATED = 0x000000DD;
  const CICM::Status S_ROLE_MAX = 0x000000DE;
  const CICM::Status S_PASSWORD_INVALID = 0x000000E1;
  const CICM::Status S_PASSWORD_INVALID_CHAR = 0x000000E2;
  const CICM::Status S_PASSWORD_INVALID_LEN = 0x000000E4;
  const CICM::Status S_SALT_INVALID = 0x000000E7;
  const CICM::Status S_ITERATION_COUNT_INVALID = 0x000000E8;
  const CICM::Status S_INSUFFICIENT_ENTROPY = 0x000000EB;

  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 Package {
    typedef CICM::UInt32 PackageType;
    const CICM::Package::PackageType
      C_PACKAGE_ALGORITHM = 0x00006054;

    const CICM::Package::PackageType
      C_PACKAGE_CONFIG_PARAMS = 0x00006057;

    const CICM::Package::PackageType
      C_PACKAGE_FPGA_IMAGE = 0x00006058;

    const CICM::Package::PackageType
      C_PACKAGE_POLICY_DB = 0x0000605B;

    const CICM::Package::PackageType
      C_PACKAGE_SOFTWARE = 0x0000605D;

    readonly attribute CICM::PackageId id;

    CICM::Status activate();
    CICM::Status deactivate();
    CICM::Status delete();
  };

  interface PackageImporter {
    CICM::Status import_segment(
      in  CICM::Buffer package_data );

    CICM::Status complete(
      out CICM::Package package_ref );

    CICM::Status abort();
  };

  interface Login {
    CICM::Status logout();
  };

  interface LogEntry {
    readonly attribute CICM::UserId user_id;
    readonly attribute CICM::RoleId role_id;
    readonly attribute CICM::CharString message;
    readonly attribute CICM::CharString date_time;

    CICM::Status delete();
  };

  interface PeerInfo {
    readonly attribute CICM::CharString peer_name;
    readonly attribute CICM::Classification classification;
    readonly attribute CICM::CharString compartment;
    readonly attribute CICM::CharString message;
  };

  interface Negotiator {
    CICM::Status get_remote_info(
      out CICM::PeerInfo peer_info );

    CICM::Status abort_negotiation();
  };

  interface ModuleEventListener {
    typedef CICM::UInt32 ModuleEvent;
    const CICM::ModuleEventListener::ModuleEvent
      C_MODULE_ACCESS_TOKEN_INSERTED = 0x00002001;

    const CICM::ModuleEventListener::ModuleEvent
      C_MODULE_ACCESS_TOKEN_REMOVED = 0x00002002;

    const CICM::ModuleEventListener::ModuleEvent
      C_MODULE_ALARM = 0x00002004;

    const CICM::ModuleEventListener::ModuleEvent
      C_MODULE_FAILURE = 0x00002007;

    const CICM::ModuleEventListener::ModuleEvent
      C_MODULE_INSUFFICIENT_ENTROPY = 0x00002008;

    const CICM::ModuleEventListener::ModuleEvent
      C_MODULE_KEY_EXPIRED_HARD = 0x0000200B;

    const CICM::ModuleEventListener::ModuleEvent
      C_MODULE_KEY_EXPIRED_SOFT = 0x0000200D;

    const CICM::ModuleEventListener::ModuleEvent
      C_MODULE_KEY_FILL_COMPLETE = 0x0000200E;

    const CICM::ModuleEventListener::ModuleEvent
      C_MODULE_KEY_FILL_CONNECTED = 0x00002010;

    const CICM::ModuleEventListener::ModuleEvent
      C_MODULE_KEY_FILL_INITIATED = 0x00002013;

    const CICM::ModuleEventListener::ModuleEvent
      C_MODULE_KEY_MEMORY = 0x00002015;

    const CICM::ModuleEventListener::ModuleEvent
      C_MODULE_KEY_PROTO_MESSAGE = 0x00002016;

    const CICM::ModuleEventListener::ModuleEvent
      C_MODULE_LOG_FULL = 0x00002019;

    const CICM::ModuleEventListener::ModuleEvent
      C_MODULE_LOG_NEAR_FULL = 0x0000201A;

    const CICM::ModuleEventListener::ModuleEvent
      C_MODULE_LOGIN_FAILURE = 0x0000201C;

    const CICM::ModuleEventListener::ModuleEvent
      C_MODULE_NOT_READY_FOR_TRAFFIC = 0x0000201F;

    const CICM::ModuleEventListener::ModuleEvent
      C_MODULE_POWER_MGMT_ENTER = 0x00002020;

    const CICM::ModuleEventListener::ModuleEvent
      C_MODULE_POWER_MGMT_EXIT = 0x00002023;

    const CICM::ModuleEventListener::ModuleEvent
      C_MODULE_POWER_OFF = 0x00002025;

    const CICM::ModuleEventListener::ModuleEvent
      C_MODULE_POWER_OFF_FAILURE = 0x00002026;

    const CICM::ModuleEventListener::ModuleEvent
      C_MODULE_POWER_ON = 0x00002029;

    const CICM::ModuleEventListener::ModuleEvent
      C_MODULE_READY_FOR_TRAFFIC = 0x0000202A;

    const CICM::ModuleEventListener::ModuleEvent
      C_MODULE_REKEY_REQUEST = 0x0000202C;

    const CICM::ModuleEventListener::ModuleEvent
      C_MODULE_TEST_FAILURE = 0x0000202F;

    const CICM::ModuleEventListener::ModuleEvent
      C_MODULE_ZEROIZED = 0x00002031;

    void event_occurred(
      in  CICM::ModuleEventListener::ModuleEvent event,
      in  CICM::Buffer event_data );
  };

  interface ModuleEventManager {
    CICM::Status register(
      in  CICM::ModuleEventListener::ModuleEvent event,
      in  CICM::ModuleEventListener listener );

    CICM::Status unregister(
      in  CICM::ModuleEventListener::ModuleEvent event );
  };

  interface ChannelEventListener {
    typedef CICM::UInt32 ChannelEvent;
    const CICM::ChannelEventListener::ChannelEvent
      C_CHANNEL_DATA_AVAILABLE = 0x00004001;

    const CICM::ChannelEventListener::ChannelEvent
      C_CHANNEL_ERROR = 0x00004002;

    const CICM::ChannelEventListener::ChannelEvent
      C_CHANNEL_INSUFFICIENT_ENTROPY = 0x00004004;

    const CICM::ChannelEventListener::ChannelEvent
      C_CHANNEL_LOST_SYNC = 0x00004007;

    const CICM::ChannelEventListener::ChannelEvent
      C_CHANNEL_PEER_RESET = 0x00004008;

    void event_occurred(
      in  CICM::ChannelEventListener::ChannelEvent event,
      in  CICM::Buffer event_data );
  };

  interface ChannelEventManager {
    CICM::Status register(
      in  CICM::ChannelEventListener::ChannelEvent event,
      in  CICM::ChannelEventListener listener );

    CICM::Status unregister(
      in  CICM::ChannelEventListener::ChannelEvent event );
  };

  interface Channel {
    readonly attribute CICM::ChannelEventManager event_manager;
  };

  interface Stream : CICM::Channel {};

  interface WriteStream : CICM::Stream {
    typedef CICM::UInt32 WriteStatus;
    const CICM::WriteStream::WriteStatus C_WRITE_NOT_READY = 0x00006067;
    const CICM::WriteStream::WriteStatus C_WRITE_READY = 0x00006068;
  };

  interface ReadStream : CICM::Stream {
    typedef CICM::UInt32 ReadStatus;
    const CICM::ReadStream::ReadStatus C_READ_NOT_READY = 0x0000605E;
    const CICM::ReadStream::ReadStatus C_READ_READY = 0x00006061;
  };

  interface Controller : CICM::Channel {
    CICM::Status destroy();
  };

  interface MultiDomainController : CICM::Controller {
    readonly attribute CICM::LocalPort local_port;
    readonly attribute CICM::RemotePort remote_port;
  };

  interface SymKeyController : CICM::Controller {
    readonly attribute CICM::SymKey key;

    CICM::Status update_key();

    CICM::Status update_key_with_algo(
      in  CICM::SymEncrAlgorithmId algorithm );

    CICM::Status rollover_key();

    CICM::Status rollover_key_with_key(
      in  CICM::SymKey next_key );
  };

  interface AsymKeyController : CICM::Controller {
    readonly attribute CICM::AsymKey key;
  };

  interface NegotiatedController :
    CICM::MultiDomainController,
    CICM::AsymKeyController,
    CICM::Negotiator {

    readonly attribute CICM::Classification negotiated_grade;

    CICM::Status renegotiate();

    CICM::Status initiate_grade_change(
      in  CICM::Classification new_grade );

    CICM::Status acknowledge_grade_change();
  };

  interface SetVectorController : CICM::Controller {
    readonly attribute CICM::Vector vec;

    CICM::Status set_vector(
      in  CICM::Vector vec );

    CICM::Status set_vector_no_check(
      in  CICM::Vector vec );

    CICM::Status reset_vector();
  };

  interface GenVectorController : CICM::SetVectorController {
    CICM::Status generate_vector();
    CICM::Status generate_vector_existing_state();
  };

  interface ResyncController : CICM::Controller {
    CICM::Status resync();
    CICM::Status resync_with_sync_vector(
      in  CICM::Vector vec );
  };

  interface ControllerGroup {
    CICM::Status add(
      in CICM::Controller controller_ref );
  };

  interface Conduit :
    CICM::Controller,
    CICM::Stream {
  };

  interface AbstractMACConduit : CICM::Conduit {
    readonly attribute CICM::SymKey mac_key;
    readonly attribute CICM::SymMacAlgorithmId mac_algorithm;

    CICM::Status end_get_mac(
      out CICM::MACBuffer mac );
  };

  interface AbstractSignConduit : CICM::Conduit {
    readonly attribute CICM::AsymKey sign_key;
    readonly attribute CICM::AsymSigAlgorithmId sign_algorithm;

    CICM::Status end_get_signature(
      out CICM::SigBuffer signature );
  };

  interface AbstractVerifyConduit : CICM::Conduit {
    typedef CICM::UInt32 VerifyStatus;
    const CICM::AbstractVerifyConduit::VerifyStatus
      C_DATA_VERIFIED = 0x00006025;

    const CICM::AbstractVerifyConduit::VerifyStatus
      C_DATA_NOT_VERIFIED = 0x00006026;

  };

  interface AbstractMACVerifyConduit : CICM::AbstractVerifyConduit {
    readonly attribute CICM::SymKey verify_key;
    readonly attribute CICM::SymMacAlgorithmId verify_algorithm;

    CICM::Status end_get_verified(
      in  CICM::MACBuffer mac,
      out CICM::AbstractVerifyConduit::VerifyStatus status );
  };

  interface AbstractSigVerifyConduit : CICM::AbstractVerifyConduit {
    readonly attribute CICM::AsymKey verify_key;
    readonly attribute CICM::AsymSigAlgorithmId verify_algorithm;

    CICM::Status end_get_verified(
      in  CICM::SigBuffer signature,
      out CICM::AbstractVerifyConduit::VerifyStatus status );
  };

  module Encrypt {
    interface Stream : CICM::WriteStream {
      CICM::Status encrypt(
        in  CICM::Buffer buffer );

      CICM::Status encrypt_non_blocking(
        in  CICM::Buffer buffer,
        in  CICM::TransId transaction_id );

      CICM::Status encrypt_poll(
        in  CICM::TransId transaction_id,
        out CICM::WriteStream::WriteStatus status );
    };

    interface KeyWrapStream : CICM::Stream {
      CICM::Status wrap_key(
        in CICM::Key key_ref );
    };

    interface Controller :
      CICM::MultiDomainController,
      CICM::SymKeyController,
      CICM::GenVectorController,
      CICM::ResyncController {};

    interface NegotiatedController :
      CICM::NegotiatedController,
      CICM::GenVectorController,
      CICM::ResyncController {};

    interface Conduit :
      CICM::Conduit,
      CICM::Encrypt::Controller,
      CICM::Encrypt::Stream {};

    interface NegotiatedConduit :
      CICM::Conduit,
      CICM::Encrypt::NegotiatedController,
      CICM::Encrypt::Stream {};

    interface WithMACConduit :
      CICM::AbstractMACConduit,
      CICM::Encrypt::Conduit {};

    interface WithMACNegotiatedConduit :
      CICM::AbstractMACConduit,
      CICM::Encrypt::NegotiatedConduit {};

    interface WithSignConduit :
      CICM::AbstractSignConduit,
      CICM::Encrypt::Conduit {};

    interface WithSignNegotiatedConduit :
      CICM::AbstractSignConduit,
      CICM::Encrypt::NegotiatedConduit {};

    interface KeyWrapConduit :
      CICM::Encrypt::Controller,
      CICM::Encrypt::KeyWrapStream {};

    interface ControllerNegotiator : CICM::Negotiator {
      CICM::Status complete(
        out CICM::Encrypt::NegotiatedController controller_ref );
    };

    interface Negotiator : CICM::Negotiator {
      CICM::Status complete(
        out CICM::Encrypt::NegotiatedConduit conduit_ref );
    };

    interface WithMACNegotiator : CICM::Negotiator {
      CICM::Status complete(
        out CICM::Encrypt::WithMACNegotiatedConduit conduit_ref );
    };

    interface WithSignNegotiator : CICM::Negotiator {
      CICM::Status complete(
        out CICM::Encrypt::WithSignNegotiatedConduit conduit_ref );
    };

    interface ChannelManager {
      CICM::Status negotiate_encrypt_conduit(
        in  CICM::RemotePort remote_port,
        in  CICM::ProtocolId protocol,
        in  CICM::AsymKey key_ref,
        out CICM::Encrypt::Negotiator negotiator_ref );

      CICM::Status negotiate_encrypt_with_mac_conduit(
        in  CICM::RemotePort remote_port,
        in  CICM::ProtocolId protocol,
        in  CICM::SymKey mac_key_ref,
        in  CICM::AsymKey nego_key_ref,
        in  CICM::SymMacAlgorithmId mac_algorithm,
        out CICM::Encrypt::WithMACNegotiator negotiator_ref );

      CICM::Status negotiate_encrypt_with_sign_conduit(
        in  CICM::RemotePort remote_port,
        in  CICM::ProtocolId protocol,
        in  CICM::AsymKey sign_key_ref,
        in  CICM::AsymKey nego_key_ref,
        in  CICM::AsymSigAlgorithmId sign_algorithm,
        out CICM::Encrypt::WithSignNegotiator negotiator_ref );

      CICM::Status negotiate_encrypt_controller(
        in  CICM::LocalPort local_port,
        in  CICM::RemotePort remote_port,
        in  CICM::ProtocolId protocol,
        in  CICM::AsymKey key_ref,
        out CICM::Encrypt::ControllerNegotiator negotiator_ref );

      CICM::Status create_encrypt_conduit(
        in  CICM::RemotePort remote_port,
        in  CICM::SymKey key_ref,
        in  CICM::SymEncrAlgorithmId algorithm,
        out CICM::Encrypt::Conduit conduit_ref );

      CICM::Status create_encrypt_with_mac_conduit(
        in  CICM::RemotePort remote_port,
        in  CICM::SymKey mac_key_ref,
        in  CICM::SymKey encrypt_key_ref,
        in  CICM::SymMacAlgorithmId mac_algorithm,
        in  CICM::SymEncrAlgorithmId encr_algorithm,
        out CICM::Encrypt::WithMACConduit conduit_ref );

      CICM::Status create_encrypt_with_sign_conduit(
        in  CICM::RemotePort remote_port,
        in  CICM::AsymKey sign_key_ref,
        in  CICM::SymKey encrypt_key_ref,
        in  CICM::AsymSigAlgorithmId sign_algorithm,
        in  CICM::SymEncrAlgorithmId encr_algorithm,
        out CICM::Encrypt::WithSignConduit conduit_ref );
      CICM::Status create_key_wrap_conduit(
        in  CICM::RemotePort remote_port,
        in  CICM::SymKey kek_ref,
        in  CICM::KeyWrapAlgorithmId algorithm,
        out CICM::Encrypt::KeyWrapConduit conduit_ref );

      CICM::Status create_encrypt_controller(
        in  CICM::LocalPort local_port,
        in  CICM::RemotePort remote_port,
        in  CICM::SymKey key_ref,
        in  CICM::SymEncrAlgorithmId algorithm,
        out CICM::Encrypt::Controller controller_ref );

      CICM::Status get_encrypt_stream(
        in  CICM::LocalPort local_port,
        out CICM::Encrypt::Stream stream_ref );
    };
  };

  module Decrypt {
    interface Stream : CICM::ReadStream {
      CICM::Status decrypt(
        out CICM::Buffer buffer );

      CICM::Status decrypt_non_blocking(
        out CICM::Buffer buffer,
        in  CICM::TransId transaction_id );

      CICM::Status decrypt_poll(
        in  CICM::TransId transaction_id,
        out CICM::ReadStream::ReadStatus status );
    };

    interface KeyUnwrapStream : CICM::Stream {
      CICM::Status unwrap_sym_key(
        out CICM::SymKey key_ref );

      CICM::Status unwrap_asym_key(
        out CICM::AsymKey key_ref );
    };

    interface Controller :
      CICM::MultiDomainController,
      CICM::SymKeyController,
      CICM::SetVectorController,
      CICM::ResyncController {};

    interface NegotiatedController :
      CICM::NegotiatedController,
      CICM::SetVectorController,
      CICM::ResyncController {};

    interface Conduit :
      CICM::Conduit,
      CICM::Decrypt::Controller,
      CICM::Decrypt::Stream {};

    interface NegotiatedConduit :
      CICM::Conduit,
      CICM::Decrypt::NegotiatedController,
      CICM::Decrypt::Stream {};

    interface WithMACConduit :
      CICM::AbstractMACVerifyConduit,
      CICM::Decrypt::Conduit {};

    interface WithMACNegotiatedConduit :
      CICM::AbstractMACVerifyConduit,
      CICM::Decrypt::NegotiatedConduit {};

    interface WithVerifyConduit :
      CICM::AbstractSigVerifyConduit,
      CICM::Decrypt::Conduit {};

    interface WithVerifyNegotiatedConduit :
      CICM::AbstractSigVerifyConduit,
      CICM::Decrypt::NegotiatedConduit {};

    interface KeyUnwrapConduit :
      CICM::Decrypt::Controller,
      CICM::Decrypt::KeyUnwrapStream {};

    interface Negotiator : CICM::Negotiator {
      CICM::Status complete(
        out CICM::Decrypt::NegotiatedConduit conduit_ref );
    };

    interface ControllerNegotiator : CICM::Negotiator {
      CICM::Status complete(
        out CICM::Decrypt::NegotiatedController controller_ref );
    };

    interface WithMACNegotiator : CICM::Negotiator {
      CICM::Status complete(
        out CICM::Decrypt::WithMACNegotiatedConduit conduit_ref );
    };

    interface WithVerifyNegotiator : CICM::Negotiator {
      CICM::Status complete(
        out CICM::Decrypt::WithVerifyNegotiatedConduit conduit_ref );
    };

    interface ChannelManager {
      CICM::Status negotiate_decrypt_conduit(
        in  CICM::RemotePort remote_port,
        in  CICM::ProtocolId protocol,
        in  CICM::AsymKey key_ref,
        out CICM::Decrypt::Negotiator negotiator_ref );

      CICM::Status negotiate_decrypt_with_mac_conduit(
        in  CICM::RemotePort remote_port,
        in  CICM::ProtocolId protocol,
        in  CICM::SymKey verify_key_ref,
        in  CICM::AsymKey nego_key_ref,
        in  CICM::SymMacAlgorithmId verify_algorithm,
        out CICM::Decrypt::WithMACNegotiator negotiator_ref );

      CICM::Status negotiate_decrypt_with_verify_conduit(
        in  CICM::RemotePort remote_port,
        in  CICM::ProtocolId protocol,
        in  CICM::AsymKey verify_key_ref,
        in  CICM::AsymKey nego_key_ref,
        in  CICM::AsymSigAlgorithmId verify_algorithm,
        out CICM::Decrypt::WithVerifyNegotiator negotiator_ref );

      CICM::Status negotiate_decrypt_controller(
        in  CICM::LocalPort local_port,
        in  CICM::RemotePort remote_port,
        in  CICM::ProtocolId protocol,
        in  CICM::AsymKey key_ref,
        out CICM::Decrypt::ControllerNegotiator negotiator_ref );

      CICM::Status create_decrypt_conduit(
        in  CICM::RemotePort remote_port,
        in  CICM::SymKey key_ref,
        in  CICM::SymEncrAlgorithmId algorithm,
        out CICM::Decrypt::Conduit conduit_ref );

      CICM::Status create_decrypt_with_mac_conduit(
        in  CICM::RemotePort remote_port,
        in  CICM::SymKey verify_key_ref,
        in  CICM::SymKey decrypt_key_ref,
        in  CICM::SymMacAlgorithmId verify_algorithm,
        in  CICM::SymEncrAlgorithmId decrypt_algorithm,
        out CICM::Decrypt::WithMACConduit conduit_ref );

      CICM::Status create_decrypt_with_verify_conduit(
        in  CICM::RemotePort remote_port,
        in  CICM::AsymKey verify_key_ref,
        in  CICM::SymKey decrypt_key_ref,
        in  CICM::AsymSigAlgorithmId verify_algorithm,
        in  CICM::SymEncrAlgorithmId decrypt_algorithm,
        out CICM::Decrypt::WithVerifyConduit conduit_ref );

      CICM::Status create_key_unwrap_conduit(
        in  CICM::RemotePort remote_port,
        in  CICM::SymKey kek_ref,
        in  CICM::KeyWrapAlgorithmId algorithm,
        out CICM::Decrypt::KeyUnwrapConduit conduit_ref );

      CICM::Status create_decrypt_controller(
        in  CICM::LocalPort local_port,
        in  CICM::RemotePort remote_port,
        in  CICM::SymKey key_ref,
        in  CICM::SymEncrAlgorithmId algorithm,
        out CICM::Decrypt::Controller controller_ref );

      CICM::Status get_decrypt_stream(
        in  CICM::LocalPort local_port,
        out CICM::Decrypt::Stream stream_ref );
    };
  };

  module Duplex {
    interface Stream :
      CICM::Encrypt::Stream,
      CICM::Decrypt::Stream {};

    interface Controller :
      CICM::Encrypt::Controller,
      CICM::Decrypt::Controller {};

    interface NegotiatedController :
      CICM::Encrypt::NegotiatedController,
      CICM::Decrypt::NegotiatedController {};

    interface Conduit :
      CICM::Conduit,
      CICM::Duplex::Controller,
      CICM::Duplex::Stream {};

    interface NegotiatedConduit :
      CICM::Duplex::NegotiatedController,
      CICM::Duplex::Stream {};

    interface ControllerNegotiator : CICM::Negotiator {
      CICM::Status complete(
        out CICM::Duplex::NegotiatedController controller_ref );
    };

    interface Negotiator : CICM::Negotiator {
       CICM::Status complete(
        out CICM::Duplex::NegotiatedConduit conduit_ref );
    };

    interface ChannelManager {
      CICM::Status negotiate_duplex_conduit(
        in  CICM::RemotePort remote_port,
        in  CICM::ProtocolId protocol,
        in  CICM::AsymKey key_ref,
        out CICM::Duplex::Negotiator negotiator_ref );

      CICM::Status negotiate_duplex_controller(
        in  CICM::LocalPort local_port,
        in  CICM::RemotePort remote_port,
        in  CICM::ProtocolId protocol,
        in  CICM::AsymKey key_ref,
        out CICM::Duplex::ControllerNegotiator negotiator_ref );

      CICM::Status create_duplex_conduit(
        in  CICM::RemotePort remote_port,
        in  CICM::SymKey key_ref,
        in  CICM::SymEncrAlgorithmId algorithm,
        out CICM::Duplex::Conduit conduit_ref );

      CICM::Status create_duplex_controller(
        in  CICM::LocalPort local_port,
        in  CICM::RemotePort remote_port,
        in  CICM::SymKey key_ref,
        in  CICM::SymEncrAlgorithmId algorithm,
        out CICM::Duplex::Controller controller_ref );

      CICM::Status get_duplex_stream(
        in  CICM::LocalPort local_port,
        out CICM::Duplex::Stream stream_ref );
    };
  };

  module BypassWrite {
    interface Stream : CICM::WriteStream {
      CICM::Status write_bypass(
        in  CICM::Buffer buffer );

      CICM::Status write_bypass_non_blocking(
        in  CICM::Buffer buffer,
        in  CICM::TransId transaction_id );

      CICM::Status write_bypass_poll(
        in  CICM::TransId transaction_id,
        out CICM::WriteStream::WriteStatus status );
    };

    interface Controller : CICM::MultiDomainController {};

    interface Conduit :
      CICM::Conduit,
      CICM::BypassWrite::Controller,
      CICM::BypassWrite::Stream {};

    interface ChannelManager {
      CICM::Status create_bypass_write_conduit(
        in  CICM::RemotePort remote_port,
        out CICM::BypassWrite::Conduit conduit_ref );

      CICM::Status create_bypass_write_controller(
        in  CICM::LocalPort local_port,
        in  CICM::RemotePort remote_port,
        out CICM::BypassWrite::Controller controller_ref );

      CICM::Status get_bypass_write_stream(
        in  CICM::LocalPort local_port,
        out CICM::BypassWrite::Stream stream_ref );
    };
  };

  module BypassRead {
    interface Stream : CICM::ReadStream {
      CICM::Status read_bypass(
        out CICM::Buffer buffer );

      CICM::Status read_bypass_non_blocking(
        out CICM::Buffer buffer,
        in   CICM::TransId transaction_id );

      CICM::Status read_bypass_poll(
        in  CICM::TransId transaction_id,
        out CICM::ReadStream::ReadStatus status );
    };

    interface Controller : CICM::MultiDomainController {};

    interface Conduit :
      CICM::Conduit,
      CICM::BypassRead::Controller,
      CICM::BypassRead::Stream {};

    interface ChannelManager {
      CICM::Status create_bypass_read_conduit(
        in  CICM::RemotePort remote_port,
        out CICM::BypassRead::Conduit conduit_ref );

      CICM::Status create_bypass_read_controller(
        in  CICM::LocalPort local_port,
        in  CICM::RemotePort remote_port,
        out CICM::BypassRead::Controller controller_ref );

      CICM::Status get_bypass_read_stream(
        in  CICM::LocalPort local_port,
        out CICM::BypassRead::Stream stream_ref );
    };
  };

  module EncryptBypass {
    interface Stream :
      CICM::Encrypt::Stream,
      CICM::BypassWrite::Stream {
    };

    interface NegotiatedController :
      CICM::Encrypt::NegotiatedController {};

    interface Controller : CICM::Encrypt::Controller {};

    interface Conduit :
      CICM::Encrypt::Conduit,
      CICM::EncryptBypass::Stream {};

    interface NegotiatedConduit :
      CICM::Encrypt::NegotiatedController,
      CICM::EncryptBypass::Stream {};

    interface ControllerNegotiator : CICM::Negotiator {
      CICM::Status complete(
        out CICM::EncryptBypass::NegotiatedController controller_ref );
    };

    interface Negotiator : CICM::Negotiator {
      CICM::Status complete(
        out CICM::EncryptBypass::NegotiatedConduit conduit_ref );
    };

    interface ChannelManager {
      CICM::Status negotiate_encrypt_bypass_conduit(
        in  CICM::RemotePort remote_port,
        in  CICM::ProtocolId protocol,
        in  CICM::AsymKey key_ref,
        out CICM::EncryptBypass::Negotiator negotiator_ref );

      CICM::Status negotiate_encrypt_bypass_controller(
        in  CICM::LocalPort local_port,
        in  CICM::RemotePort remote_port,
        in  CICM::ProtocolId protocol,
        in  CICM::AsymKey key_ref,
        out CICM::EncryptBypass::ControllerNegotiator negotiator_ref );

      CICM::Status create_encrypt_bypass_conduit(
        in  CICM::RemotePort remote_port,
        in  CICM::SymKey key_ref,
        in  CICM::SymEncrAlgorithmId algorithm,
        out CICM::EncryptBypass::Conduit conduit_ref );

      CICM::Status create_encrypt_bypass_controller(
        in  CICM::LocalPort local_port,
        in  CICM::RemotePort remote_port,
        in  CICM::SymKey key_ref,
        in  CICM::SymEncrAlgorithmId algorithm,
        out CICM::EncryptBypass::Controller controller_ref );

      CICM::Status get_encrypt_bypass_stream(
        in  CICM::LocalPort local_port,
        out CICM::EncryptBypass::Stream stream_ref );
    };
  };

  module DecryptBypass {
    interface Stream : CICM::Decrypt::Stream {};

    interface NegotiatedController :
      CICM::Decrypt::NegotiatedController {};

    interface Conduit :
      CICM::Decrypt::Conduit,
      CICM::DecryptBypass::Controller,
      CICM::DecryptBypass::Stream {};

    interface NegotiatedConduit :
      CICM::Decrypt::NegotiatedConduit,
      CICM::DecryptBypass::NegotiatedController,
      CICM::DecryptBypass::Stream {};

    interface ControllerNegotiator : CICM::Negotiator {
      CICM::Status complete(
        out CICM::DecryptBypass::NegotiatedController controller_ref );
    };

    interface Negotiator : CICM::Negotiator {
      CICM::Status complete(
        out CICM::DecryptBypass::NegotiatedConduit conduit_ref );
    };

    interface ChannelManager {
      CICM::Status negotiate_decrypt_bypass_conduit(
        in  CICM::RemotePort remote_port,
        in  CICM::ProtocolId protocol,
        in  CICM::AsymKey key_ref,
        out CICM::DecryptBypass::Negotiator negotiator_ref );

      CICM::Status negotiate_decrypt_bypass_controller(
        in  CICM::LocalPort local_port,
        in  CICM::RemotePort remote_port,
        in  CICM::ProtocolId protocol,
        in  CICM::AsymKey key_ref,
        out CICM::DecryptBypass::ControllerNegotiator negotiator_ref );

      CICM::Status create_decrypt_bypass_conduit(
        in  CICM::RemotePort remote_port,
        in  CICM::SymKey key_ref,
        in  CICM::SymEncrAlgorithmId algorithm,
        out CICM::DecryptBypass::Conduit conduit_ref );

      CICM::Status create_decrypt_bypass_controller(
        in  CICM::LocalPort local_port,
        in  CICM::RemotePort remote_port,
        in  CICM::SymKey key_ref,
        in  CICM::SymEncrAlgorithmId algorithm,
        out CICM::DecryptBypass::Controller controller_ref );

      CICM::Status get_decrypt_bypass_stream(
        in  CICM::LocalPort local_port,
        out CICM::DecryptBypass::Stream stream_ref );
    };
  };

  module Emit {
    interface GetStream : CICM::ReadStream {
      CICM::Status get(
        in  CICM::UInt32 length,
        out CICM::Buffer buffer );

      CICM::Status get_non_blocking(
        in  CICM::UInt32 length,
        out CICM::Buffer buffer,
        in  CICM::TransId transaction_id );

      CICM::Status get_poll(
        in  CICM::TransId transaction_id,
        out CICM::ReadStream::ReadStatus status );
    };

    interface Controller : CICM::Controller {
      readonly attribute CICM::RemotePort remote_port;
    };

    interface KeyStreamGenController :
      CICM::SymKeyController,
      CICM::GenVectorController,
      CICM::Emit::Controller {};

    interface PseudoRandomController :
      CICM::SymKeyController,
      CICM::Emit::Controller {};

    interface RandomController : CICM::Emit::Controller {};

    interface KeyStreamGenConduit :
      CICM::Conduit,
      CICM::SymKeyController,
      CICM::GenVectorController,
      CICM::Emit::GetStream {};

    interface PseudoRandomConduit :
      CICM::Conduit,
      CICM::SymKeyController,
      CICM::Emit::GetStream {};

    interface RandomConduit :
      CICM::Conduit,
      CICM::Emit::GetStream {};

    interface ChannelManager {
      CICM::Status create_key_stream_gen_controller(
        in  CICM::RemotePort remote_port,
        in  CICM::SymKey key_ref,
        in  CICM::SymEncrAlgorithmId algorithm,
        out CICM::Emit::KeyStreamGenController controller_ref );

      CICM::Status create_pseudorandom_controller(
        in  CICM::RemotePort remote_port,
        in  CICM::SymKey seed,
        out CICM::Emit::PseudoRandomController controller_ref );

      CICM::Status create_random_controller(
        in  CICM::RemotePort remote_port,
        out CICM::Emit::RandomController controller_ref );

      CICM::Status create_key_stream_gen_conduit(
        in  CICM::SymKey key_ref,
        in  CICM::SymEncrAlgorithmId algorithm,
        out CICM::Emit::KeyStreamGenConduit conduit_ref );

      CICM::Status create_pseudorandom_conduit(
        in  CICM::SymKey seed,
        out CICM::Emit::PseudoRandomConduit conduit_ref );

      CICM::Status create_random_conduit(
        out CICM::Emit::RandomConduit conduit_ref );
    };
  };

  module Answer {
    interface PutStream : CICM::Stream {
      CICM::Status put(
        in  CICM::Buffer buffer );
    };

    interface HashConduit :
      CICM::Conduit,
      CICM::Answer::PutStream {

      readonly attribute CICM::HashAlgorithmId algorithm;

      CICM::Status end_get_hash(
        out HashBuffer hash );
    };

    interface MACConduit :
      CICM::AbstractMACConduit,
      CICM::Answer::PutStream {};

    interface MACVerifyConduit :
      CICM::AbstractMACVerifyConduit,
      CICM::Answer::PutStream {};

    interface SignConduit :
      CICM::AbstractSignConduit,
      CICM::Answer::PutStream {};

    interface SignHashConduit : CICM::Answer::SignConduit {};

    interface VerifyConduit :
      CICM::AbstractSigVerifyConduit,
      CICM::Answer::PutStream {};

    interface VerifyHashConduit : CICM::Answer::VerifyConduit {};

    interface ChannelManager {
      CICM::Status create_hash_conduit(
        in  CICM::HashAlgorithmId algorithm,
        out CICM::Answer::HashConduit conduit_ref );

      CICM::Status create_mac_conduit(
        in  CICM::SymKey key_ref,
        in  CICM::SymMacAlgorithmId algorithm,
        out CICM::Answer::MACConduit conduit_ref );

      CICM::Status create_mac_verify_conduit(
        in  CICM::SymKey key_ref,
        in  CICM::SymMacAlgorithmId algorithm,
        out CICM::Answer::MACVerifyConduit conduit_ref );

      CICM::Status create_sign_conduit(
        in  CICM::AsymKey key_ref,
        in  CICM::AsymSigAlgorithmId algorithm,
        out CICM::Answer::SignConduit conduit_ref );

      CICM::Status create_sign_hash_conduit(
        in  CICM::AsymKey key_ref,
        in  CICM::AsymSigAlgorithmId algorithm,
        out CICM::Answer::SignHashConduit conduit_ref );

      CICM::Status create_verify_conduit(
        in  CICM::AsymKey key_ref,
        in  CICM::AsymSigAlgorithmId algorithm,
        out CICM::Answer::VerifyConduit conduit_ref );

      CICM::Status create_verify_hash_conduit(
        in  CICM::AsymKey key_ref,
        in  CICM::AsymSigAlgorithmId algorithm,
        out CICM::Answer::VerifyHashConduit conduit_ref );
    };
  };

  module Coprocessor {
    interface Stream : CICM::Stream {
      CICM::Status get_final_buffer(
        out CICM::Buffer buffer );
    };

    interface EncryptConduit :
      CICM::Conduit,
      CICM::SymKeyController,
      CICM::GenVectorController,
      CICM::ResyncController,
      CICM::Coprocessor::Stream {

      CICM::Status encrypt(
        in  CICM::Buffer plaintext,
        out CICM::Buffer ciphertext );
    };

    interface EncryptWithMACConduit :
      CICM::AbstractMACConduit,
      CICM::Coprocessor::EncryptConduit {};

    interface EncryptWithSignConduit :
      CICM::AbstractSignConduit,
      CICM::Coprocessor::EncryptConduit {};

    interface DecryptConduit :
      CICM::Conduit,
      CICM::SymKeyController,
      CICM::SetVectorController,
      CICM::ResyncController,
      CICM::Coprocessor::Stream {

      CICM::Status decrypt(
        in  CICM::Buffer ciphertext,
        out CICM::Buffer plaintext );
    };

    interface DecryptWithMACConduit :
      CICM::AbstractMACVerifyConduit,
      CICM::Coprocessor::DecryptConduit {};

    interface DecryptWithVerifyConduit :
      CICM::AbstractSigVerifyConduit,
      CICM::Coprocessor::DecryptConduit {};

    interface ChannelManager {
      CICM::Status create_coprocessor_encrypt_conduit(
        in  CICM::SymKey key_ref,
        in  CICM::SymEncrAlgorithmId algorithm,
        out CICM::Coprocessor::EncryptConduit conduit_ref );

      CICM::Status create_coprocessor_encrypt_with_mac_conduit(
        in  CICM::SymKey mac_key_ref,
        in  CICM::SymKey encrypt_key_ref,
        in  CICM::SymMacAlgorithmId mac_algorithm,
        in  CICM::SymEncrAlgorithmId encrypt_algorithm,
        out CICM::Coprocessor::EncryptWithMACConduit conduit_ref );

      CICM::Status create_coprocessor_encrypt_with_sign_conduit(
        in  CICM::AsymKey sign_key_ref,
        in  CICM::SymKey encrypt_key_ref,
        in  CICM::AsymSigAlgorithmId sign_algorithm,
        in  CICM::SymEncrAlgorithmId encrypt_algorithm,
        out CICM::Coprocessor::EncryptWithSignConduit conduit_ref );

      CICM::Status create_coprocessor_decrypt_conduit(
        in  CICM::SymKey key_ref,
        in  CICM::SymEncrAlgorithmId algorithm,
        out CICM::Coprocessor::DecryptConduit conduit_ref );

      CICM::Status create_coprocessor_decrypt_with_mac_conduit(
        in  CICM::SymKey mac_key_ref,
        in  CICM::SymKey decrypt_key_ref,
        in  CICM::SymMacAlgorithmId mac_algorithm,
        in  CICM::SymEncrAlgorithmId encrypt_algorithm,
        out CICM::Coprocessor::DecryptWithMACConduit conduit_ref );

      CICM::Status create_coprocessor_decrypt_with_verify_conduit(
        in  CICM::AsymKey verify_key_ref,
        in  CICM::SymKey decrypt_key_ref,
        in  CICM::AsymSigAlgorithmId verify_algorithm,
        in  CICM::SymEncrAlgorithmId decrypt_algorithm,
        out CICM::Coprocessor::DecryptWithVerifyConduit conduit_ref );
    };
  };

  interface Iterator {
    typedef CICM::UInt32 Status;
    const CICM::Iterator::Status C_ITERATOR_HAS_NEXT = 0x00006031;
    const CICM::Iterator::Status C_ITERATOR_NO_MORE = 0x00006032;

    CICM::Status has_next(
      out CICM::Iterator::Status has_next );
  };

  interface AsymKeyIterator : CICM::Iterator {
    CICM::Status get_next(
      out CICM::AsymKey asym_key_ref );
  };

  interface LogEntryIterator : CICM::Iterator {
    CICM::Status get_next(
      out CICM::LogEntry log_entry_ref );
  };

  interface ModuleAssnIterator : CICM::Iterator {
    CICM::Status get_next(
      out CICM::ModuleRecord module_rec_ref );
  };

  interface PackageIterator : CICM::Iterator {
    CICM::Status get_next(
      out CICM::Package package_ref );
  };

  interface RoleIdIterator : CICM::Iterator {
    CICM::Status get_next(
      out CICM::RoleId role_id );
  };

  interface SymKeyIterator : CICM::Iterator {
    CICM::Status get_next(
      out CICM::SymKey sym_key_ref );
  };

  interface TokenAssnIterator : CICM::Iterator {
    CICM::Status get_next(
      out CICM::TokenRecord token_rec_ref );
  };

  interface UserIdIterator : CICM::Iterator {
    CICM::Status get_next(
      out CICM::UserId user_id );
  };

  interface ChannelManager :
    CICM::Answer::ChannelManager,
    CICM::BypassRead::ChannelManager,
    CICM::BypassWrite::ChannelManager,
    CICM::Coprocessor::ChannelManager,
    CICM::Decrypt::ChannelManager,
    CICM::DecryptBypass::ChannelManager,
    CICM::Duplex::ChannelManager,
    CICM::Emit::ChannelManager,
    CICM::Encrypt::ChannelManager,
    CICM::EncryptBypass::ChannelManager {

    CICM::Status create_controller_group(
      out CICM::ControllerGroup controller_group_ref );
  };

  interface LogManager {
    readonly attribute CICM::LogEntryIterator log_entry_iterator;

    CICM::Status retrieve(
      out CICM::Buffer log_ref );

    CICM::Status destroy();
  };

  interface LoginManager {
     CICM::Status login(
      in  CICM::UserId user,
      in  CICM::CharString password,
      out CICM::Login login_ref );

    CICM::Status login_auth_data(
      in  CICM::UserId user,
      in  CICM::CharString password,
      in  CICM::Buffer auth_data,
      out CICM::Login login_ref );
  };

  interface PackageManager {
    readonly attribute CICM::PackageIterator package_iterator;

    CICM::Status import_package(
      in  CICM::Package::PackageType package_type,
      out CICM::PackageImporter importer_ref );

    CICM::Status import_package_with_key(
      in  CICM::Package::PackageType package_type,
      in  CICM::SymKey key_ref,
      out CICM::PackageImporter importer_ref );

    CICM::Status get_package_by_id(
      in  CICM::PackageId package_id,
      out CICM::Package package_ref );

    CICM::Status reencrypt_software();
  };

  interface TestManager {
    typedef CICM::UInt32 Status;
    const CICM::TestManager::Status C_TEST_SUCCESS = 0x00006062;
    const CICM::TestManager::Status C_TEST_FAILURE = 0x00006064;

    CICM::Status run_test(
      in  CICM::Buffer test_parameters,
      out CICM::TestManager::Status status );

    CICM::Status run_test_get_results(
      in  CICM::Buffer test_parameters,
      out CICM::Buffer test_results );
  };

  interface TokenManager {
    readonly attribute CICM::ModuleAssnIterator
      module_association_iterator;

    readonly attribute CICM::TokenAssnIterator
      token_association_iterator;

    CICM::Status associate(
      out CICM::ModuleRecord module_rec,
      out CICM::TokenRecord token_rec );

    CICM::Status disassociate();

    CICM::Status disassociate_missing_module(
      in  CICM::ModuleRecord module_rec );

    CICM::Status disassociate_missing_token(
      in  CICM::TokenRecord token_rec );
  };

  interface UserManager {
    readonly attribute CICM::UserIdIterator user_iterator;
    readonly attribute CICM::RoleIdIterator role_iterator;

    CICM::Status add(
      in  CICM::UserId user,
      in  CICM::CharString password );

    CICM::Status modify(
      in  CICM::UserId user,
      in  CICM::CharString password );

    CICM::Status remove(
      in  CICM::UserId user );

    CICM::Status associate(
      in  CICM::UserId user,
      in  CICM::RoleId role );

    CICM::Status disassociate(
      in  CICM::UserId user,
      in  CICM::RoleId role );
  };

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

  interface CryptoModule {
    readonly attribute CICM::ModuleId module_id;
    readonly attribute CICM::CharString manufacturer;
    readonly attribute CICM::CharString model;
    readonly attribute CICM::CharString serial_number;
    readonly attribute CICM::CharString module_version;
    readonly attribute CICM::CharString software_version;
    readonly attribute CICM::CharString driver_version;
    readonly attribute CICM::CharString library_version;
    readonly attribute CICM::RoleId role;
    attribute CICM::CharString date_time;
    readonly attribute CICM::SymKeyManager sym_key_manager;
    readonly attribute CICM::AsymKeyManager asym_key_manager;
    readonly attribute CICM::KeyDatabase key_database;
    readonly attribute CICM::ChannelManager channel_manager;
    readonly attribute CICM::ModuleEventManager event_manager;
    readonly attribute CICM::PackageManager package_manager;
    readonly attribute CICM::TokenManager token_manager;
    readonly attribute CICM::UserManager user_manager;
    readonly attribute CICM::LoginManager login_manager;
    readonly attribute CICM::TestManager test_manager;
    readonly attribute CICM::LogManager log_manager;

    CICM::Status configure_fill_interface(
      in  CICM::Buffer interface_parameters,
      in  CICM::LocalPort fill_port );

    CICM::Status reset();
  };

  interface CICMRoot {
    CICM::Status get_module_by_id(
      in  CICM::ModuleId id,
      out CICM::CryptoModule crypto_module_ref );
  };
};

[RFC2119]	Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML).
[RFC3552]	Rescorla, E. and B. Korver, “Guidelines for Writing RFC Text on Security Considerations,” BCP 72, RFC 3552, July 2003 (TXT).

	Daniel J. Lanz
	The MITRE Corporation
Email:	dlanz@mitre.org

	Lev Novikov
	The MITRE Corporation
Email:	lnovikov@mitre.org

Common Interface to Cryptographic Modulesdraft-lanz-cicm-01

Abstract

Requirements Language

Status of this Memo

Copyright Notice

Table of Contents

1. Introduction

1.1. Background

1.2. Audience

1.3. Scope of the Specification

1.4. Use Cases

1.4.1. Data-in-Transit

1.4.2. Data-at-Rest

1.4.3. Single Security Domain

1.5. Assumptions

1.6. Specification Organization

1.7. Acknowledgements

2. Using the Specification

2.1. Specification Categories

2.2. Module Management

2.2.1. Managing Module Authentication

2.2.1.1. Managing Hardware Access Tokens

2.2.1.2. Managing Users

2.2.1.3. Logging in to a Module from a Host

2.2.2. Managing Software Packages

2.2.3. Managing Logs

2.2.4. Managing Tests

2.2.5. Managing Module Events

2.2.6. Managing Keys and Channels

2.3. Key Management

2.3.1. Creating and Establishing Keys

2.3.1.1. No Host Interaction Key Fill

2.3.1.2. Client Program-Initiated

2.3.1.3. Module/Key Infrastructure Initiated

2.3.2. Exporting Keys

2.3.2.1. Locating and Retrieving Information about a Key

2.3.2.2. Applying Metadata to Keys

2.3.2.3. Performing Operations on Keys

2.3.2.4. Enabling Remote Management

2.3.3. Channel Management

2.3.3.1. Creating Channels

2.3.3.1.1. Encryption and Decryption

2.3.3.1.2. Bypass

2.3.3.1.3. Integrity

2.3.3.1.4. Hashing

2.3.3.1.5. Keystream Generation

2.3.3.1.6. Random Data

2.3.3.2. Managing Channels

2.3.3.3. Using Channels

2.3.3.4. Grouping Channels

2.3.3.5. Receiving Notification of Channel Events

2.3.3.6. Destroying Channels

3. Normative Specification

3.1. Introduction

3.1.1. Conventions

3.1.1.1. Diagrams

3.1.1.2. IDL Definitions

3.1.2. Normative Statements

3.1.2.1. Endianness

3.1.2.2. Blocking and Non-blocking Calls

3.1.2.3. IDL Language Mapping Conventions

3.2. Fundamental Definitions

3.2.1. Namespace CICM

3.2.2. Fundamental Types

3.2.2.1. General Types

3.2.2.2. Identifiers

3.2.2.3. Status Codes

3.2.2.4. Classifications

3.2.2.5. Algorithms

3.2.2.6. Ports

3.2.2.7. State Vector

3.2.2.8. Integrity Buffers

3.2.3. Fundamental Interfaces

3.2.3.1. Interface CICM::CICMRoot

3.2.3.1.1. CICM::CICMRoot Methods

3.2.3.2. Interface CICM::CryptoModule

3.2.3.2.1. CICM::CryptoModule Attributes

3.2.3.2.2. CICM::CryptoModule Methods

3.2.3.3. Interface CICM::Iterator

3.2.3.3.1. CICM::Iterator Types and Constants

Common Interface to Cryptographic Modules
draft-lanz-cicm-01