Finished Projects

Security Architecture and Modeling

Composable Replaceable Security Services for Survivable Distributed Systems

Architecture Report

February 27, 1998

Prepared by:
Richard Feiertag, Principal Investigator
Eve Cohen, Jeff Cook, Timothy Redmond, Jaisook Rho
Trusted Information Systems, Inc.
444 Castro Street, Suite 800
Mountain View, CA 94041
(650) 962-8885

This work is sponsored by DARPA under contract number F30602-97-C-0187.

Table of Contents
1. Introduction *
2. Architecture Overview *

2.1 High-Level Services *
2.2 Low-Level Services * 3. Framework * 3.1 Relationship of Framework to Architecture *
3.2 Framework Functions *
3.3 Framework Design *
3.4 Framework Distribution * 4. Simple Example Application *
5. Low-level Services * 5.1 Cryptographic Services *
5.2 Credential and Certificate Management Services *
5.3 Database Services *
5.4 Trust Policy Management Services *
5.5 Key Recovery Services *
5.6 Audit Services *
6. High-Level Services * 6.1 The Authentication Service *
6.2 The Secure Connection Service *
6.3 Secure Transaction/Exchange Service *
6.4 The Secure Retrieval and Storage Service *
6.5 Secure Execution * 7. Conclusion and Plans *
8. References *
References for CDSA 1.2 *
References for CDSA 2.0 *
Other References *

1. Introduction
The goal of the Composable Replaceable Security Services (CRSS) is to develop a security infrastructure that can support the next generation of survivable distributed systems. The CRSS provides an infrastructure that applications can use in a manner independent of various operating system and networking technologies. Toward this goal, we are developing a collection of distributed security services that embody the properties needed for survivability as well as a framework for composing them. The needed properties for survivability include identification and authentication, confidentiality, integrity, and non-repudiation.

The document describes how the CRSS architecture provides the infrastructure that has the following three properties. First, each service has multiple implementations that can coexist at the same time. For instance, the cryptographic service may have implementations for the RSA encryption as well as for the DES encryption. Second, services are designed to be composable. As systems evolve, the composability allows administrators to update individual services as needed without affecting the performance of the other services. Also, composability allows more complex services to be constructed from a few simple basic services and possibly permits these more complex services to be constructed in different ways using different basic services.

Finally, each service is designed to be a part of a distributed environment. Every service consists of two components: the service framework and the collection of service providers that implement the desired service. The service framework accepts requests from applications or service providers and directs them to appropriate service providers. For example, for the cryptographic service, when an application requests encryption service, the service framework accepts the request and may forward it to the RSA encryption service provider.

Both the service framework and the collection of service providers run in a distributed environment. The service framework can fulfill a service request by invoking a service provider that resides on the local host or a remote host. Similarly, the framework itself is implemented in a redundant distributed manner allowing, for example, the framework on a host to continue operating even if its local copy of the database of service providers is corrupted.

These three properties are essential for survivability. They provide fault-tolerance, scalability, and flexibility. Multiple implementations that are composable can be made fault-tolerant by identifying multiple ways of providing a given service and constructing a mechanism to use an alternative if one way fails. The alternative may be as simple as using a different service provider to fulfill a service request or more complex such as using a different composition of services to fulfill the request. For example, suppose two applications are using a cryptographic service provider (CSP) to communicate and the CSP becomes inoperable. A different CSP or another instance of the same CSP on a different host could be used to secure the communication.

Designing each service so that it can be implemented in a distributed manner allows the infrastructure to be easily scaled. Additional instances of a service provider can be added as the system grows. The scalability is crucial as the number of services grows and as the inter-relationships among them become more complex, and as the number of variable diverse implementations increase.

Finally, reconfigurability and composability satisfy the flexibility requirement. As services evolve, the these two properties allow administrators to reconfigure existing services to facilitate their interactions with new services.

The first design of the CRSS architecture had three layers: the application-specific security service layer, high-level services, and low-level services. Because of the wide-range of applications we wish to support, we thought we needed to develop application-specific security services. However, after categorizing the application-specific services, we have determined that most applications' security needs can be fulfilled by the four high-level security services described below.

The version of the architecture described in this document has two layers of services: the high-level services and low-level services. The high-level services are those services that directly support application programs. There are four such services. The first three services allow applications to specify the following security properties: confidentiality, integrity, and non-repudiation. They also allow specification of the degree of the assurance they provide, ranging from none to strong.

The first high-level service allows applications to connect with each other. Applications can use the connection service to invoke the telnet program across the network. The second high-level service allows applications to send transactions to each other. Applications can use the transaction service to perform electronic commerce and send electronic mail. The third high-level service allows applications to store and retrieve objects. Applications can use this service to retrieve and store files across networks. Finally, the last high-level service allows applications to execute programs securely across the network.

The low-level services are basic capabilities needed to support high-level services. These services consist of the cryptographic service, credential and certificate management service, database management service, trust policy management service, key recovery service and audit service.

This report describes the architecture of the CRSS. This includes a description of each of the services, both high-level and low-level, and a description of the service framework. This report does not address issues such as how failures are detected, how alternative providers and compositions are identified and selected, or how one measures the survivability of a particular configuration of service providers. These will be the subject of subsequent reports.

Section 2 presents an overview of the architecture. Section 3 describes the framework of the infrastructure. Section 4 presents a simple example of how the architecture supports survivability. Section 5 describes the low level services. Section 6 describes the high-level services.

2. Architecture Overview
In this section, we give an overview of the architecture of the CRSS. The CRSS is designed as a composition of several interoperating services. Each service provides an interface with a well defined functionality. For example, the cryptographic service provides the ability to encrypt and decrypt data and other cryptographic operations. These service interfaces combine to provide the CRSS functionality.

The CRSS contains two layers of services as shown in Figure 1. The top layer of services is the point of entry for most applications. These high-level services provide the security support that most applications need. This support allows applications to have secure transactions and connections with security properties such as confidentiality, integrity, identification, non-repudiation and authentication.

Figure 1 - Security Services Architecture

The bottom level of services provide the mechanisms that the high-level services require. These services provide the high-level services with the ability to do such things as encrypt and decrypt data, examine certificates to determine what they authorize, and store audit records.

The service concept in the CRSS architecture has been designed to support pluggability. The consumer of a service is not restricted to a single implementation of the service interface. Rather, the service interface is implemented by one or more service providers that can be selected dynamically by the consumer or preset by an administrator. For example, the cryptographic service may include a service provider that implements RSA encryption and another service provider that implements DES encryption. These service providers can be added and deleted from a service dynamically.

When a service consumer first desires to use a service, some negotiation must occur to decide which of the service providers performs the right features for the service consumer. By providing a range of service providers that all implement a common interface, the service provides a great deal of choice with regards to choosing the best mechanism to perform a security function. The mechanics of selecting and using a service provider from a given service is described in more detail in a later section. In the remainder of this section, we give an overview of each of these services and an example of how a service provider might be chosen.

2.1 High-Level Services
We now describe each of the high-level services in Figure 1. The connection service is responsible for adding security properties, such as confidentiality and integrity, to a connection between two applications.

An application calls the connection service after the client has obtained an insecure connection. The connection service directs the client through a protocol exchange by which the peer systems set up a common security context for the connection. Depending on the connection service provider chosen, this data exchange may represent, for example, a Diffie-Hellman key exchange or the sending of a kerberos ticket. The security context that is obtained can then be used to impose security on the existing connection. For example, the application can use the security context to encrypt or decrypt data in a manner that is understood by the application's peer.

The transaction/exchange service is responsible for providing security enhancements to data that are used for a single transaction. Examples of the security properties provided by the transaction/exchange service are authentication of the author, integrity, confidentiality and non-repudiation of receipt. This service might be used by an e-mail application or an application that implements electronic money.

When an application desires to add security enhancements to data, it must first set up a security environment. When the application makes the call to create the security environment, it specifies the security properties that it desires. When the security environment is created, the transaction/exchange service informs the application as to what security properties were obtained. The application can then use the security environment to apply security enhancements to data. For example, if the security environment supports confidentiality, then the security environment can be used to encrypt or decrypt data.

The retrieval and storage service is responsible for the secure retrieval and storage of named objects. Such named objects include files and web pages. In general, there are security implications of accessing such named objects. The retrieval and storage service implements the required access controls on named objects. Such access controls can either be based on identity or based on certificate authorization schemes. It is not expected that retrieval and storage of all named objects be accomplished via the retrieval and storage service. Most retrieval/storage mechanisms such as file systems and data bases would likely use other services such as the trust service for implementing security, however, the retrieval and storage service is intended to provide some simple retrieval and storage that has very well understood security properties.

To access a named object, the application opens the named object for a specific access mode. After successfully opening the named object, the application has an object descriptor that it can use to exercise its access to the object. When it is done, the application closes its access to the object.

The remote execution service is responsible for ensuring that executable code transferred between systems can be executed in a safe and secure manner. If potentially malicious code of unknown origin is to be executed then the controls must include some form of sandboxing. Another approach to the remote execution service is to require that the code come with some proof of origin so that it can be executed safely. While remote execution is important, due to its complexity we have deferred design of the remote execution service and it is not included in this report. Many other research efforts are studying the security requirements of remotely executed code and we want our design to reflect results from those studies.

The authentication service is responsible for associating active entities in the system with their identification, authorizations, certificates and credentials. A traditional approach to this problem is to require that a user attempting to use a system must first pass a login challenge. After the user has authenticated himself, all processes started by the user are unforgeably tagged with the user's identity. From there on, determining the authority, certificates and credentials to associate with a process is simply a lookup.

However, the authentication service interface must be rich enough to handle other scenarios. For example, one may wish to authenticate entities other than users such as hosts, programs, or servers. Another possibility is that a user or process may demonstrate its authority by opening a crypto device (which requires a password). The authentication service is designed to incorporate possibilities such as these as well.

2.2 Low-Level Services
The high-level services are intended to be implemented using a set of low-level services as the basis for security. These services, shown in Figure 1, cover the following areas of functionality:

cryptographic operations,
key/credential/certificate management,
trust and authorization policy definition, mediation and enforcement, and
recording of audit data.

We briefly describe each of the low-level services.

The cryptographic service implements the basic cryptographic operations such as encryption and decryption of data and generation of signatures. In order to use the cryptographic services, the consumer must first create a cryptographic session. In contrast to the high-level services, the cryptographic context creation operations do not take a list of security properties as a parameter. The consumer must have determined that the cryptographic service provider implements the security properties that are desired. The consumer can then use the cryptographic session to encrypt, decrypt, generate digests, sign, verify signature, and generate keys. The cryptographic context should be closed as soon as the desired operations are complete to minimize exposure of key information.

The credential/certificate service provides life cycle support and format-specific manipulation for certificates. This support allows clients to:

create, sign and verify certificates and certificate revocation lists (CRLs),
view certificates and extract certificate fields,
import and export certificates to and from other certificate service providers,
revoke and reinstate certificates, and
search CRLs.

These calls allow the user to support the entire life cycle of a certificate.

The trust policy service is responsible for determining what authorization is associated with certificates. In this context, a certificate is taken in a broad context. For example, and access control list (ACL) can be considered a certificate and therefore the trust policy service can be used to determine authorization to objects with ACLs. As another example, SPKI defines an algorithm for examining a SPKI certificate to determine what authority can be extended to the entity associated with a certificate. An SPKI trust policy service provider would implement this algorithm.

The key recovery service is responsible for implementing key recovery schemes. Interaction with the key recovery service goes through three phases. First, the consumer must register itself with the key recovery service. This simply initializes key recovery for the consumer. Second, the consumer must enable the key recovery for a particular key blob. This is where key recovery fields are generated and processed. Finally, the consumer may execute a key recovery request to initiate the recovery of a lost key.

The audit service implements a very simple audit log functionality. It has a single call that the consumer of the audit service uses to add some data to the audit log. It is assumed that the data being added represents an audit log entry for some auditable event. This service represents only the interface applications have with audit mechanisms, it is assumed that management of audit logs as well as any analysis of audit logs is defined elsewhere.

3. Framework

3.1 Relationship of Framework to Architecture
The architecture has two parts as shown in Figure 2. The first part consists of the security service providers, shown in Figure 3, to be used by application programs and users. The second part provides the glue that supports invocation of the security providers by application programs, users, and other service providers. We call this part of the architecture the framework as it provides the infrastructure supporting the security services. An important part of the framework is enhancement of the survivability of the security services by enabling replacement of service providers that become inoperable with identical or similar service providers. This replacement can either be directed or automatic. This potential for replacement provides the redundancy necessary to ensure survivability of the collection of security services in the presence of component failures. Another important aspect of the framework is its support for distribution of the security services. Service providers need not be instantiated on the same host from which they are invoked. The framework allows an application or service provider on one host to invoke a service provider on another host. The fact that the invoked service provider is remote need not be visible to the client. The framework ensures that the remote invocation maintains the security properties requested by the client. The following sections describe the functions provided by the framework, the design of the framework, an overview of provisions for survivability, and an overview of provisions for distribution.

3.2 Framework Functions
The primary purpose of the framework is to allow a client to invoke a service. All of the operations described later in this document are invoked via the framework. The client specifies the operation being invoked and any arguments to that operation and the framework invokes an appropriate service provider. If there is no service provider present to implement the designated service, then the framework returns an error. For most clients, invoking services is the only use they will make of the framework. The framework can automatically locate and invoke a service provider that can fulfill the client's request.

If the service provider is remote, it securely forwards the invocation information to the remote host and, if necessary, receive a reply from the remote host. If the invoked service provider fails to operate, the framework attempts to locate and invoke an alternative service provider that can fulfill the request. The framework continues to seek alternatives until the request is satisfied or no appropriate alternative service providers can be located. For most clients, these processes of location, distribution, and recovery are transparent, i.e., the client need not be aware of them. To the client it is a simple service invocation.

Figure 2 - Services Architecture

Figure 3 - Service Providers

However, some clients may be able to make use of location, distribution, and recovery of the services they use. To accommodate such clients the framework provides operations to query and advise the framework in actions it takes. The framework provides a registry of service providers. A client can query this registry to locate a particular provider for a particular service. The client can request that invocations of a particular service be fulfilled by a limited set of providers. When that service is invoked by the client then the framework limits itself to locating the restricted set. In this way a client can direct its invocations to particular service providers. A client may want to limit the fulfillment of a service in this way in order to take advantage of special features of certain providers. However, such restriction may adversely effect the reliability of the service by limiting alternatives available to the framework.

Clients may also want to control the distribution of fulfillment of a service. In particular, the framework provides means for a client to restrict the hosts on which providers can run to fulfill service invocations by the client. Also, the client can control the communication mechanisms used to fulfill invocations on remote hosts. When fulfilling a service invocation on a remote host, the framework attempts to use communication mechanisms consistent with the security requirements of the service being invoked. For example, when invoking a remote trust policy provider, the framework communicates with the remote provider using a communication mechanism that preserves the integrity of the data in the invocation. Also, the framework verifies the trustworthiness of the remote provider. Clients can exercise control over the constraints the framework places on remote invocation of service providers. Clients can use this control both to increase the security of remote invocations as well as decrease this security. The ability to decrease security is useful in cases where highly secure providers are unavailable and it is essential to fulfill the service even though security may be compromised.

The framework also provides an interface to service providers to permit providers to register and unregister themselves. As part of registration, the provider provides information about itself including the service it fulfills, its location, and other attributes concerning its operation. Before completing the registration of the provider, the framework may verify properties of the service provider such as its location, the presence of certain operations, and authenticating its origin.

Finally, the framework provides an administrative interface. The administrative interface provides the means to control operation and policy of the framework including such information as what remote hosts it uses for distribution, what properties are required for registration of providers, and what policy it uses for selecting alternative providers. The latter includes determining to what degree the framework allows degradation of service both in security and performance before allowing a service invocation to go unfulfilled.

3.3 Framework Design
The framework consists of three major components as shown in Figure 4. The Provider Registry is a database that maintains information on registered service providers. This includes information on their service, location, attributes, and operation status. Provider Management uses this information to select providers to fulfill service invocations and to select alternatives when providers become inoperative.

Figure 4 - Framework Design

The Provider Switch performs invocation of service providers. The Switch passes to the provider the information supplied by the client when it invoked the service as well as additional information that the framework needs to pass to the provider. When the invocation is completed, the Switch passes any return information back to the client. The Switch is controlled by Provider Management, i.e., Provider Management tells the Switch which provider to invoke for a given service invocation by a given client. The Switch also monitors the invocation of a provider for unanticipated errors or failure to respond as evidence that a provider is no longer operational. It passes any such evidence to Provider Management. On the basis of such evidence, Provider Management may instruct the Switch to invoke a different provider for subsequent invocations to the service.

Provider Management coordinates the activities of the framework. It accepts all service invocations from clients. In reality these service invocations are passed directly to the Provider Switch (optimizations may allow the service invocations to go directly to the Switch). However, Provider Management manages the Switch, directing it as to which providers are invoked. Provider Management also manages the Registry, accepting registration requests from providers and directing the Registry to incorporate or remove providers in its data base. Provider Management also determines which provider is invoked to fulfill a service request by a particular client. Clients may provide input to Provider Management to influence this decision, but Provider Management makes the decisions and directs the Switch accordingly. Provider Management accepts direction via its administrative interface as to policy for selecting a provider. This information is also used to select alternatives when providers become nonoperational. Providers may also be replaced for other reasons such as the registration of a new provider that may be better suited to fulfill a particular server for a given client.

3.4 Framework Distribution
The framework is intended to operate in a distributed environment. That is, it operates in a coordinated fashion on multiple interconnected hosts. This allows a client running on one host to have a service invocation fulfilled by a provider running on a different host. Some part of the framework must be present in each participating host (for example, the Provider Switch must be present on each host but the registry may not have to be present on each host). The Provider Registry is a distributed data base within the framework. Provider Management is a distributed service that can select from both local and remote providers. Reliability considerations dictate to what extent framework components such as the Registry are present on each host.

The Provider Switch is responsible for communication between the framework on each host. The Provider Switch uses either the Secure Connection or Secure Transaction service to establish secure communication between hosts. Whenever the Provider Switch is used to fulfill a service invocation and the provider is remote, the switch sends the information to the Switch on the remote host which, in turn, invokes the desired provider. The logical path for both local and remote service invocations is illustrated in Figure 5 and Figure 6. Figure 5 shows a local invocation. The first time a client invokes a particular service is illustrated in Path 1. The Provider Manager selects a provider to fulfill the service invocation by consulting the Registry and forwards the information to the Provider Switch. The Provider Switch then invokes the selected provider. The Switch retains the association between the client and the provider so that in subsequent invocations, the Provider Manager can essentially be bypassed. However, the Provider Manager may at any time direct the Switch to use a different provider for the client. In the case where the provider is remote as shown in Figure 6, instead of invoking the provider, the Switch sends the request to the Switch on the remote host where the provider resides using the Secure Connection or Secure Transaction Service. The remote Provider Switch then makes the invocation of the provider.

Figure 5 - Local service provider invocation

Figure 6 - Remote service provider invocation

Although not specifically indicated on the diagram, the invocation by the Switch of the Secure Connection or Secure Transaction Service is similar to any invocation of the service by a client. This means that the Switch calls the Provider Manager that decides which provider to select to fulfill the service and then forwards the call back to the Switch to actually invoke the provider. When calling the Provider Manager to invoke the Secure Transaction Service, the Switch must request a local provider to avoid an unbounded recursion. Calls between components of the framework are handled in a similar manner. For example, if the instance of the Provider Registry on one host needs to invoke the Registry on another host, it is treated as a service invocation with only one provider, namely the Registry on the latter host. This allows the same mechanisms that assure survivability of security services invoked by clients to be applied to internal invocations, i.e., invocations by the framework itself.

4. Simple Example Application
In this section we describe an example of how an application can utilize the security features of the CRSS in a fault tolerant manner. We describe how the application, e-mail in this case, uses the CRSS in the absence of a fault, then we a fault into the scenario and show how the application and the CRSS responds.

The e-mail application uses the transaction/exchange service in order to obtain security enhancements such as non-repudiation, authentication, confidentiality and integrity. For simplicity of exposition, we restrict our attention to the send e-mail operation and only consider authentication, confidentiality and integrity enhancements.

The transaction/exchange service provides applications with the option of using a single call to provide security enhancements to data. To use this option when an e-mail application is ready to send an e-mail message, it must specify the desired levels of security properties. For example, the application could specify that the message have strong confidentiality and a medium level of integrity. The e-mail application invokes the service framework specifying the transaction/exchange service. The framework selects a transaction/exchange service provider that can perform the requested security enhancements and invokes this provider. If for whatever reason, the selected service provider cannot perform the service, then the framework redirects the request to the next qualified service provider. As part of its function, the framework may have to clean up after the failed service provider.

We start by illustrating the case where no fault occurs. In this case, the framework must select a service provider to fulfill the service request. In this example, this selection will be driven primarily by the available credentials for the sender and recipient of the message. The credentials are the mean by which the sender and receiver authenticate each other and protect the data in transit. The framework must select a service provider that can use the available credentials. Also, the framework must be cognizant of the service providers that are available to the recipient in order to select a service provider that uses credentials that the recipient can use. The instance of the framework on the sender's host may need to communicate with the instance of the framework on the recipients host in order to select an appropriate service provider. Then, the framework passes the credentials to the transaction/exchange service provider that uses them to provide the desired service.

Now consider what happens when the chosen service provider cannot perform the desired service. The framework, as in previous case, invokes a provider, but the provider fails to provide the requested service for some reason (e.g., it has insufficient resources such as memory to fulfill the request or the credential is no longer valid). In this case, the framework must first recover from this failure in an orderly manner, by effectively restoring its state to that which existed before it invoked the failed provider. Then, the framework must find another provider to attempt to fulfill the request. It continues to recover from failures and try alternative providers until either the request is successfully fulfilled or the set of appropriate providers is exhausted. In the latter case, the framework returns an error to the email application, stating that the request could not be serviced.

5. Low-level Services
The pluggable low-level security services provided by CRSS are listed in the table below.

Low-level Service	Description
Cryptographic	cryptographic service providers
Credential and Certificate Management	syntactic credential and certificate management services
Database	database (local and/or remote storage) services
Trust Policy Management	trust policy management services (certificate semantics)
Key Recovery	key recovery services
Audit	audit services

The low-level services for CRSS have been modeled after the low-level services provided by Intel's Common Data Security Architecture (CDSA) specification, and we intend to use the CDSA services model and API where possible. By using an emerging standard such as CDSA we expect that there will be a large number of service providers for use in CRSS. This will both allow us to make use of the work of others and lead to a more survivable system. The CDSA contains a Common Security Services Manager (CSSM) that manages a set of low-level services. The low-level services of CRSS that are currently supported by CSSM are: Cryptographic, Credential and Certificate Management, Database, Trust Policy Management, and Key Recovery. An Audit Service is rumored to be in the works, but has not yet been made public.

Unfortunately, CDSA is a specification in transition. The newest specification is version 2.0, published in October 1997. The latest specification for which software exists is version 1.2, published in March 1997, and whose software was not available until November or December 1997. The version 2.0 specification is much cleaner, better organized, and more capable than 1.2, but, since software is not currently available for 2.0, for CRSS we are initially targeting CDSA 1.2 with the intention to move on to 2.0 when software becomes available. As such, when CRSS services correspond to CSSM services, we present the APIs for both CDSA 1.2 and 2.0.

5.1 Cryptographic Services
The cryptographic services of CRSS are modeled directly after the cryptographic services of CDSA. Low-level cryptographic services are provided by Cryptographic Service Providers (CSPs) that plug into CDSA's Service Provider Interface (SPI). CSPs are add-in modules that may be implemented in software, hardware, or a combination thereof. CSPs perform basic cryptographic operations such as digital signature and verification, encryption and decryption, key and key pair generation, and so forth. A complete list of the operations that may be performed by a CSP are listed below. An individual CSP may choose to implement a subset of the possible operations, and may implement additional vendor-specific operations by using the PassThrough functionality provided for extensibility.

An application may make queries to determine what CSPs are installed and what services they provide. (CDSA has provisions for registration and integrity checking of CSPs to prevent masquerading.) Calls made to a CSP to perform cryptographic algorithms occur within a framework called a session, which is established and terminated by an application. A cryptographic context is created prior to starting a session and is deleted as soon as possible after completion. This contextual information is not persistent and is not saved permanently in a file or database. To protect access to CSP services, CSPs optionally support a password-based login/logout sequence, where users may change their passwords as deemed necessary, and support may even be provided for operations to be performed by privileged CSP administrators.

Secure storage of private keys is always the responsibility of a CSP, which may optionally assume responsibility for the secure storage of objects of other types, such as symmetric keys and certificates. For storage of private keys, a CSP may choose to use the services of a Data Storage Library module within the CSSM framework (if the module provides secure storage) or may use an approach that is internal to the CSP. Access to other persistent objects managed by the CSP are performed using CSSM's Data Storage Library APIs.

Cryptographic operations come in two types -- a single call to perform an operation and a staged method of performing the operation. For the staged method, there is an initialization call followed by one or more update calls, and ending with a completion (final) call. For most staged cryptographic operations, the final result is available after the function completes its execution, the exception being encryption/decryption where each update call generates a portion of the result.

Cryptographic Operations The cryptographic operations that may be provided by a CSP, for both CDSA 1.2 and 2.0, are tabulated in two separate tables below. Most of these operations make use of a handle that indicates the cryptographic context in which the operation is to be performed. The nine distinct types of cryptographic context are: Signature, Symmetric, Digest, Mac, Random, Asymmetric, DeriveKey, KeyGen, and PassThrough.

Table: SPI Operations for CDSA 1.2

Single Call	Staged Call
CSSM_CSP_Login
CSSM_CSP_Logout
CSSM_CSP_ChangeLoginPassword

CSSM_CSP_PassThrough

CSSM_SignData	CSSM_SignDataInit/Update/Final
CSSM_VerifyData	CSSM_VerifyDataInit/Update/Final
CSSM_DigestData	CSSM_DigestDataInit/Update/Final
CSSM_GenerateMac	CSSM_GenerateMacInit/Update/Final
CSSM_QuerySize
CSSM_EncryptData	CSSM_EncryptDataInit/Update/Final
CSSM_DecryptData	CSSM_DecryptDataInit/Update/Final
CSSM_GenerateKey
CSSM_KeyPair
CSSM_Random
CSSM_UniqueId
CSSM_WrapKey
CSSM_UnwrapKey
CSSM_DeriveKey
CSSM_KeyExchGenParam
CSSM_KeyExchPhase1
CSSM_KeyExchPhase2

The SPI operations in the table above, for CDSA 1.2, are described briefly below.

Login: accepts as input a login password and a flag indicating the persistent or non-persistent status of keys and other objects created during the login session. CSPs are not required to support a login model. If a login model is supported, the CSP may request additional passwords at any time during the period of service.
Logout: logout from a CSP
ChangeLoginPassword: change login password
PassThrough: pass through vendor-defined operation, provides extensibility
SignData: cryptographically signs some data using a private key
VerifyData: verifies the input data against the provided cryptographic signature
DigestData: computes message digest (cryptographic hash) for some data
GenerateMac: generates a message authentication code for some data
QuerySize: queries the size of output data for encryption, decryption, and staged operations
EncryptData: cryptographically encrypts some data
DecryptData: cryptographically decrypts some data
GenerateKey: generates a symmetric key
GenerateKeyPair: generates an asymmetric key pair
GenerateRandom: generates some random data
WrapKey: wraps up a key using a cryptographic context
UnwrapKey: unwraps a key to complete a key exchange
DeriveKey: derives a new symmetric key using a cryptographic context and other information
KeyExchGenParam: generates a key exchange parameter for phase 1
KeyExchPhase1: phase 1 of the key exchange operation generates data for phase 2
KeyExchPhase2: phase 2 is the final phase of the key exchange operation

Table: SPI Operations for CDSA 2.0

Single Call	Staged Call
CSSM_CSP_Login
CSSM_CSP_Logout
CSSM_CSP_ChangeLoginPassword

CSSM_CSP_PassThrough

CSSM_SignData	CSSM_SignDataInit/Update/Final
CSSM_VerifyData	CSSM_VerifyDataInit/Update/Final
CSSM_DigestData	CSSM_DigestDataInit/Update/Final
CSSM_GenerateMac	CSSM_GenerateMacInit/Update/Final
CSSM_VerifyMac	CSSM_VerifyMacInit/Update/Final
CSSM_QuerySize
CSSM_EncryptData	CSSM_EncryptDataInit/Update/Final
CSSM_DecryptData	CSSM_DecryptDataInit/Update/Final
CSSM_QueryKeySizeInBits
CSSM_GenerateKey
CSSM_KeyPair
CSSM_Random
CSSM_WrapKey
CSSM_UnwrapKey
CSSM_DeriveKey
CSSM_GenerateAlgorithmParameters

The SPI operations for CDSA 2.0 differ only slightly from those for 1.2. A VerifyMac operation, inadvertently left out of the 1.2 specification, has been included. Also included is a QueryKeySizeInBits operation. The GenerateUniqueId operation has been removed. And lastly, the three operations KeyExchGenParam, KeyExchPhase1, and KeyExchPhase2 have been replaced by the single operation GenerateAlgorithmParameters. The new operations are described briefly below.

VerifyMac: verifies a message authentication code for some data
QueryKeySizeInBits: queries a CSP for the effective and real size of a key in bits
GenerateAlgorithmParameters: generates algorithm parameters for, for example, Diffie-Hellman key agreement and DSA key generation

5.2 Credential and Certificate Management Services
The credential and certificate management services provided by CRSS are modeled directly after those provided by CDSA. These services are provided by Certificate Library (CL) modules that plug into CDSA's Certificate Library Interface (CLI). The primary purpose of a Certificate Library is to perform syntactic manipulations on a specific certificate format and its associated Certificate Revocation List (CRL) format. These manipulations include the complete life cycle of a certificate and the keys associated with the certificate. Certificates and CRLs are related by the life cycle model and by the data formats used to represent them. As such, these objects should be manipulated by a single, cohesive library.

Certificate Libraries manipulate memory-based objects only. It is the responsibility of the application and/or the trust policy module to use data storage add-in modules to make objects persistent, when appropriate.

Certificate Life Cycle A Certificate Library provides life cycle support and format-specific manipulation for certificates. It permits applications and other modules to create, sign, verify, revoke, renew, and recover certificates without requiring knowledge of certificate and CRL format and encodings.

The first step in the life cycle process is registration, during which the authenticity of a user's identity is verified. This may require manual procedures, depending on the Security Policy in force. After registration, keying material is generated and certificates are created, issued to the user, and then backed up if appropriate, after which the active phase of the certificate life cycle begins. The active phase includes:

retrieval: retrieve a certificate from a remote repository
verification: verify the validity dates and signature(s) on a certificate and its revocation status
revocation: assert that a previously-legitimate certificate is no longer valid
recovery: recover a key when the user has forgotten his password
update: issue a new certificate when one will expire soon

Certificate Operations The syntactic operations that may be provided by a Certificate Library Interface, for both CDSA 1.2 and 2.0, are tabulated in separate tables below. Besides referring to a specific CL module, these operations may also access to CSP modules.

Table: CLI Operations for CDSA 1.2

Certificate Operations	CRL Operations	Group and Extensibility Operations
CSSM_CL_ CertSign	CSSM_CL_ CrlCreate	CSSM_CL_ CertGroupConstruct
CSSM_CL_ CertUnsign	CSSM_CL_ CrlAddCert	CSSM_CL_ CertGroupPrune
CSSM_CL_ CertVerify	CSSM_CL_ CrlRemoveCert	CSSM_CL_ CertGroupVerify
CSSM_CL_ CertCreate	CSSM_CL_ CrlSign
CSSM_CL_ CertView	CSSM_CL_ CrlVerify	CSSM_CL_ PassThrough
CSSM_CL_ CertGetFirstFieldValue	CSSM_CL_ IsCertInCrl
CSSM_CL_ CertGetNextFieldValue	CSSM_CL_ CrlGetFirstFieldValue
CSSM_CL_ CertAbortQuery	CSSM_CL_ CrlGetNextFieldValue
CSSM_CL_ CertGetKeyInfo	CSSM_CL_ CrlAbortQuery
CSSM_CL_ CertGetAllFields	CSSM_CL_ CrlDescribeFormat
CSSM_CL_ CertImport
CSSM_CL_ CertExport
CSSM_CL_ CertDescribeFormat

The CLI operations in the table above, for CDSA 1.2, are described briefly below.

CertSign: signs the fields of a certificate
CertUnsign: removes a signature from a certificate
CertVerify: verifies the signature on a certificate
CertCreate: allocates and initializes memory in order for a certificate to be created
CertView: returns the viewable fields of a certificate
CertGetFirstFieldValue: returns the first value of the designated certificate field
CertGetNextFieldValue: returns the next value of the designated certificate field
CertAbortQuery: terminates a query initiated by a CertGetFirstFieldValue
CertGetKeyInfo: returns information about a certificate's public key
CertGetAllFields: returns a list of the fields in a certificate
CertImport: imports a certificate from the input format to the CL's native format
CertExport: exports a certificate from its native format to the specified target format
CertDescribeFormat: returns a list of OIDs used to describe the CL's certificate format
CrlCreate: creates an empty CRL
CrlAddCert: revokes a certificate by adding it to a CRL
CrlRemoveCert: unrevokes a certificate by removing it from a CRL
CrlSign: signs a CRL
CrlVerify: verifies the signature on a CRL
IsCertInCrl: determines whether a certificate is on a CRL
CrlGetFirstFieldValue: returns the first value of the designated certificate field
CrlGetNextFieldValue: returns the next value of the designated certificate field
CrlAbortQuery: terminates a query initiated by a CrlGetFirstFieldValue
CrlDescribeFormat: returns a list of OIDs used to describe the CL's CRL format
CertGroupConstruct: construct an ordered group of certificates
CertGroupPrune: prunes from a certificate group all certificates not verifiable by an external host
CertGroupVerify: verifies an ordered certificate group
PassThrough: call a certificate library module-specific operation, for extensibility

Table: CLI Operations for CDSA 2.0

Certificate Operations	CRL Operations	Extensibility Operations
CSSM_CL_ CertRequest	CSSM_CL_ CrlCreateTemplate	CSSM_CL_ PassThrough
CSSM_CL_ CertRetrieve	CSSM_CL_ CrlSetFields
CSSM_CL_ RegistrationFormRequest	CSSM_CL_ CrlRequest
CSSM_CL_ CertMultiSignRequest	CSSM_CL_ CrlRetrieve
CSSM_CL_ CertMultiSignRetrieve	CSSM_CL_ CrlAddCert
CSSM_CL_ CertRecoveryRequest	CSSM_CL_ CrlRemoveCert
CSSM_CL_ CertRecoveryRetrieve	CSSM_CL_ CrlSign
CSSM_CL_ CertRecover	CSSM_CL_ CrlVerify
CSSM_CL_ CertKeyRecover	CSSM_CL_ IsCertInCrl
CSSM_CL_ CertAbortRecovery	CSSM_CL_ CrlGetFirstFieldValue
CSSM_CL_ CertVerify	CSSM_CL_ CrlGetNextFieldValue
CSSM_CL_ CertGetFirstFieldValue	CSSM_CL_ AbortQuery
CSSM_CL_ CertGetNextFieldValue	CSSM_CL_ CrlDescribeFormat
CSSM_CL_ AbortQuery
CSSM_CL_ GetKeyInfo
CSSM_CL_ GetAllFields
CSSM_CL_ CertImport
CSSM_CL_ CertExport
CSSM_CL_ CertDescribeFormat

The CLI operations for CDSA 2.0 a quite different from those for 1.2. Four of the initial five certificate operations (CertSign, CertUnsign, CertCreate, and CertView) have been replaced by a new set of operations, described briefly below.

CertRequest: submits a certificate creation request to a Certificate Authority
CertRetrieve: returns the certificate created in response to a CertRequest operation
RegistrationFormRequest: returns a blank registration from from a Registration Authority
CertMultiSignRequest: requests of a Certificate Authority that one or more signatures be added to a certificate
CertMultiSignRetrieve: returns the multiply-signed certificate resulting from a CertMultiSignRequest operation
CertRecoveryRequest: submits a certificate recovery request to a Certificate Authority to prepare for the recovery of a set of certificates and their associated private keys
CertRecoveryRetrieve: returns the set of certificates recovered in response to a CertRecoveryRequest operation
CertRecover: returns a certificate from a cache of certificates retrieved by a CertRecoveryRetrieve operation
CertKeyRecover: recovers the private key associated with a certificate and securely stores it in the specified CSP
CertAbortRecovery: terminates the iterative key recovery process, to enable the destruction of any private key8 evidence

The CrlCreate operation has been replaced by a new set of operations, described briefly below.

CrlCreateTemplate: creates an unsigned CRL with some subset of its fields filled in
CrlSetFields: sets the fields in a CRL to new values
CrlRequest: submits a request to a Certificate Authority to issue the most current version of a CRL
CrlRetrieve: returns the CRL issued in response to a CrlRequest operation

And finally, the certificate grouping constructs, which in CDSA 2.0 are semantic and not syntactic operations, have been moved to Trust Policy Services.

5.3 Database Services
The database services provided by CRSS are modeled directly after those provided by CDSA. These services are provided by Data Storage Library (DL) modules that plug into CDSA's Data Library Interface (DLI). The primary purpose of a data storage library is to provide persistent storage of security-related objects such as certificates, CRLs, keys, and policy objects. A DL module is responsible for the creation and accessibility of one or more data stores. A single DL module can be tightly coupled to a CL and/or a TP module, or can be independent of all other module types. A single data store can contain a single object type in one format, a single object type in multiple formats, or multiple object types. The persistent repository can be local or remote.

The abstract data model defined by the DL APIs partitions all values stored in a data record into two categories; one or more mutable attributes and one opaque data object. The attribute values can be directly manipulated by the application and the DL module. Values stored within the opaque data object must be accessed using parsing functions. A DL module that stores certificates can, but should not, interpret the format of those certificates. A set of parsing functions such as those defined in a CL module can be used to parse the opaque certificate object.

Database Operations The database operations that may be provided by a Data Library Interface, for both CDSA 1.2 and 2.0, are tabulated in separate tables below.

Table: DLI Operations for CDSA 1.2

Data Storage Functions	Data Record Operations
CSSM_DL_DbOpen	CSSM_DL_DataInsert
CSSM_DL_DbClose	CSSM_DL_DataDelete
CSSM_DL_DbCreate	CSSM_DL_DataGetFirst
CSSM_DL_DbDelete	CSSM_DL_DataGetNext
CSSM_DL_DbImport	CSSM_DL_DataAbortQuery
CSSM_DL_DbExport
CSSM_DL_DbSetInfo	CSSM_DL_CertInsert
CSSM_DL_DbGetInfo	CSSM_DL_CertDelete
CSSM_DL_FreeDbInfo	CSSM_DL_CertRevoke
CSSM_DL_GetDbHandleToName	CSSM_DL_CertGetFirst
	CSSM_DL_CertGetNext
CSSM_DL_PassThrough	CSSM_DL_CertAbortQuery

	CSSM_DL_CrlInsert
	CSSM_DL_CrlDelete
	CSSM_DL_CrlGetFirst
	CSSM_DL_CrlGetNext
	CSSM_DL_CrlAbortQuery

The DLI operations in the table above, for CDSA 1.2, are described briefly below.

DbOpen: open a data store
DbClose: close a data store
DbCreate: create and open a new data store
DbDelete: delete a data store and its contents
DbImport: import records from a file into a new data store
DbExport: export records from a data store to a file
DbSetInfo: set information regarding the data source
DbGetInfo: get information regarding the datat source
FreeDbInfo: frees database "get info" memory
GetDbHandleToName: retrieve the data source name corresponding to an open data store
DataInsert: insert a data record into a persistent data store
DataDelete: delete a data record from a persistent data store
DataGetFirst: retrieve the first object in a persistent data store that matches the selection criteria
DataGetNext: retrieve the next object matching the selection criteria
DataAbortQuery: terminate a DataGetFirst operation
CertInsert: insert a certificate into a persistent data store
CertDelete: delete a certificate from a persistent data store
CertRevoke: make persistent the knowledge that a certificate has been revoked
CertGetFirst: retrieve the first certificate in a persistent data store that matches the selection criteria
CertGetNext: retrieve the next certificate matching the selection criteria
CertAbortQuery: terminate a CertGetFirst operation
CrlInsert: insert a certificate into a persistent data store
CrlDelete: delete a certificate from a persistent data store
CrlGetFirst: retrieve the first certificate in a persistent data store that matches the selection criteria
CrlGetNext: retrieve the next certificate matching the selection criteria
CrlAbortQuery: terminate a CrlGetFirst operation
PassThrough: call a data storage library module-specific operation, for extensibility

Table: DLI Operations for CDSA 2.0

Data Storage Functions	Data Record Operations
CSSM_DL_DbOpen	CSSM_DL_DataInsert
CSSM_DL_DbClose	CSSM_DL_DataDelete
CSSM_DL_DbCreate	CSSM_DL_DataModify
CSSM_DL_DbDelete	CSSM_DL_DataGetFirst
CSSM_DL_DbImport	CSSM_DL_DataGetNext
CSSM_DL_DbExport	CSSM_DL_DataAbortQuery
CSSM_DL_DbAuthenticate	CSSM_DL_DataGetFromUniqueRec ord
CSSM_DL_DbSetRecordParsingFunctions	CSSM_DL_FreeUniqueRecord
CSSM_DL_DbGetRecordParsingFunctions
CSSM_DL_GetDbNames
CSSM_DL_GetDbNameFromHandle
CSSM_DL_FreeNameList

CSSM_DL_PassThrough

The DL APIs defined in CDSA 1.2 included operations that were specific to certificates and CRLs. These functions are made obsolete in 2.0 in order to store and retrieve an extensible set of security-related objects. Whereas CL parsing functions were to be used to parse certain data objects in CDSA 1.2, CDSA 2.0 permits these parsing functions to be specified within the DL modulel. Also, CDSA 2.0 permits the construction of data stores that may require authentication before access. The DLI operations in the table above, for CDSA 2.0, that do not appear in CDSA 1.2 are described briefly below.

DbAuthenticate: authenticate an access to a data store
DbSetRecordParsingFunctions: sets up a table of record parsing functions, for parsing opaque data objects
DbGetRecordParsingFunctions: gets the records parsing table, for parsing opaque data objects
GetDbNames: returns a list of the logical data store names associated with this DL module
GetDbNameFromHandle: retrieves the data source name corresponding to an opened data store
DbFreeNameList: frees the list returned from GetDbNames
DataModify: modifies a data record into a persistent data store
DataGetFromUniqueRecord: retrieves a data record based on a unique record identifier, for performance enhancement of data retrieval
DataFreeUniqueRecord: frees a unique record identifier

5.4 Trust Policy Management Services
The Trust Policy Management Services of CRSS are modeled directly after the Trust Policy Services of CDSA, which includes Authorization Services. Trust Policy Management Services associate semantics with certificates and are provided by Trust Policy (TP) modules that plug into CDSA's Trust Policy Interface (TPI). The primary purpose of a Trust Policy module is to answer the following question:

Is this certificate authorized for this operation in this trust domain?

Applications are executed in a trust domain. For example, executing an installation program at the office takes place within a difference trust domain than performing the same action on a home computer. In the former case, the trust domain is corporate and may require extensive credentials, whereas in the latter case, the trust domain is personal and may only require a credential that establishes the user as a known entity on the local system.

The general CSSM trust model defines a set of basic trust objects that most trust policies use to model their trust domain and the policies over that domain. These basic trust objects include:

policies,
certificates,
defined sources of trust,
certificate revocation lists,
application-specific actions, and
evidence.

Policies define the credentials required for authorization to perform an action on another object. Certificates are the basic credentials representing a trust relationship among a set of two or more parties.

Evaluation of trust depends on relationships among certificates. Certificate chains represent hiercharchical trust, where a root authority is the source of trust. Entities attain a level of trust based on their relationship to the root authority. Certificate graphs represent an introducer model of trust, where the number and strength of endorsers increases the level of trust in an entity. In both models, the trust domain can defined accepted sources of trust. In contrast to certificates, certificate revocation lists represetn sources of distrust. Trust policies may consult these lists during the certificate verification process.

Trust evaluation can be performed with respect to a specific action the bearer wishes to perform, or with respect to a policy, or with respect to the application domain in general. In the latter case, the action is understood to be either one specific action, or any and all actions in the domain.

When verifying trust, a Trust Policy Module (TPM), which is an encoding of a specific trust policy, processes a group of certificates. The result of verification is a list of evidence, which forms an audit trail of the process. The evidence may be a list of verified attribute values that were contained in the certificates, or the entire set of certificates, or some other information that serves as evidence.

Trust Policy Operations The trust policy operations that may be provided by a Trust Policy Interface, for both CDSA 1.2 and 2.0, are tabulated in separate tables below. Besides referring to a specific TP module, these operations may require access to other CL, CSP, and DL modules.

Table: TPI Operations for CDSA 1.2

Trust Policy Operations	Extensibility Operations
CSSM_TP_CertVerify	CSSM_TP_VerifyAction
CSSM_TP_CertSign	CSSM_TP_PassThrough
CSSM_TP_CertRevoke
CSSM_TP_CrlVerify
CSSM_TP_CrlSign
CSSM_TP_ApplyCrlToDb

The TPI operations in the table above, for CDSA 1.2, are described briefly below.

CertVerify: determines whether the certificate is trusted
CertSign: signs a certificate after determining whether the signer is trusted
CertRevoke: revokes a certificate if the operation is trusted
CrlVerify: determins whether the CRL is trusted
CrlSign: signs a CRL after determining whether the signer is trusted
ApplyCrlToDb: update persistent storage from a memory-resident CRL if the CRL is trusted
VerifyAction: verifies whether an input certificate is trusted to perform the module-specific operation
PassThrough: call a trust policy module-specific operation, for extensibility

Table: TPI Operations for CDSA 2.0

Trust Policy Operations	Group and Extensibility Operations
CSSM_TP_CertRequest	CSSM_TP_CertGroupConstruct
CSSM_TP_CertRetrieve	CSSM_TP_CertGroupPrune
CSSM_TP_CertVerify
CSSM_TP_CertSign	CSSM_TP_PassThrough
CSSM_TP_CertRevoke
CSSM_TP_CrlVerify
CSSM_TP_CrlSign
CSSM_TP_ApplyCrlToDb

The TPI operations for CDSA 2.0 are different in philosophy, if not in syntax, from those for 1.2. The CertRequest and CertRetrieve operations have been added, the VerifyAction operation has been removed and its semantics have been folded into the CertVerify operation, and the certificate grouping operations, syntactic in 1.2, have been added as semantics operations in 2.0. The primary difference between 2.0 and 1.2 are that the CertVerify operation has been expanded to verify authorization to perform an action, and may make use of certificate groups. All of the CDSA 2.0 TPI operations that are not a part of CDSA 1.2 are described briefly below.

CertRequest: requests certificate creation from a certificate authority if authorized
CertRetrieve: returns the certificate created in response to a CertRequest operation
CertVerify: verifies whether the subject certificate is authorized to perform some action on some data
CertSign: signs a certificate if the signer is authorized
CertRevoke: revokes a certificate if the operation is authorized
CrlVerify: determines whether the CRL is trusted
CrlSign: signs a CRL if the signer is trusted
ApplyCrlToDb: update persistent storage from a memory-resident CRL if the CRL trusted
CertGroupConstruct: constructs an ordered certificate group and augments it with semantically related certificates
CertGroupPrune: removes certificatres from a certificate group
PassThrough: call a trust policy module-specific operation, for extensibility

5.5 Key Recovery Services
This section describes those key recovery services provided as an elective module by CDSA 2.0. Key recovery mechanisms facilitate the retrieval of cryptographic keys by authorized parties.

Key Recovery Scenarios The CDSA Key Recovery Module supports three basic scenarios motivating the use of key recovery mechanisms:

Individual key recovery: an individual user may need to recover a lost or corrupted key.
Enterprise key recovery: a corporation may wish to recover keys used by its employees in the case where the employee is unavailable or unwilling to provide them.
Law enforcement key recovery: key recovery mechanisms may be used by law enforcement bodies to access the contents of confidential communications or stored data in the interests of law enforcement or national security.

The CSSM enforces both the applicable enterprise and law enforcement policies on all cryptographic operations.

Key Recovery Mechanism Types There are two types of key recovery mechanisms supported by the CDSA Key Recovery Module:

Key escrow: a trusted party holds the cryptographic keys in question (or portions thereof.)
Key encapsulation: a cryptographically wrapped form of the key in question is provided to those requiring key recovery. The encapsulated key may be unwrapped only by a trusted party.

Key Recovery Operations The key recovery operations that may be provided by a Key Recovery Interface (KRI), for CDSA 2.0, are tabulated below.

Table: KRI Operations for CDSA 2.0

CSSM_KR_SetEnterpriseRecoveryPolicy

CSSM_KR_CreateRecoveryRegistrationContext

CSSM_KR_CreateRecoveryEnablementContext

CSSM_KR_CreateRecoveryRequestContext

CSSM_KR_PolicyInfo

CSSM_KR_RegistrationRequest

CSSM_KR_RegistrationRetrieve

CSSM_KR_GenerateRecoveryFields

CSSM_KR_ProcessRecoveryFields

CSSM_KR_RecoveryRequest

CSSM_KR_RecoveryRetrieve

CSSM_KR_GetRecoveredObject

CSSM_KR_RecoveryRequestAbort

CSSM_KR_PassThrough

The KRI operations in the table above are described briefly below.

Key Recovery Module Management Operations

SetEnterpriseRecoveryPolicy: establishes the identity of the file containing the enterprise key recovery policy function.

Key Recovery Context Operations: all key recovery operations are performed with a key recovery context, containing the necessary state information.

CreateRecoveryRegistrationContext: creates a key recovery registration context
CreateRecoveryEnablementContext: creates a key recovery enablement context maintaining information about the profiles of local and remote parties for a cryptographic association.
CreateRecoveryRequestContext: creates a key recovery request context maintaining a set of key recovery fields and a denotatttion of the operational scenario of the recovery request operation.
PolicyInfo: returns the key recovery policy information controlling a given cryptographic context

Key Recovery Registration Operations: during the key recovery registration phase, a key recovery client registers with a recovery agent persuant to initiating recoverable cryptographic actions.

RegistrationRequest: initiates a key recovery registration operation
RegistrationRetrieve: returns the profile information generated as a result of a succesful ekey recovery registration process

Key Recovery Enablement Operations: in this phase, the application includes the generated key recovery fields with the encrypted text to enable subsequent key recovery.

GenerateRecoveryFields: generates the key recovery fields associated with a particular recoverable context
ProcessRecoveryFields: returns a cryptographic context handle which may be used for the decrypt API calls of the CSSM Cryptographic Module.

Key Recovery Request Operations: in this phase the key recovery fields, together with authorization credentials of the requesting party, are provided to the key recovery server in order to reconstruct the secret key which will decrypt the ciphertext.

RecoveryRequest: initiates a key recovery request operation
RecoveryRetrieve: returns an object which may be used with the GetRecoveredObject function to retrieve the recovered keys
GetRecoveredObject: uses the results of a recovery request operation to retrieve a single recovered key
RecoveryRequestAbort: terminates a recovery request operation

Extensibility Functions

PassThrough: allows applications to call exported operations specific to a given key recovery module

5.6 Audit Services
The CDSA currently contains no specification for audit services, although such services are often mentioned in the context of elective services [CSSM_EMM_2.0]. For CRSS, we provide audit services via an Audit Library (AL) module that plugs into an Audit Library Interface (ALI). The purpose of an audit library is to provide a repository for a time-stamped sequence of audit events. An Audit Library (AL) module is responsible for collecting and logging the audit events generated by other CRSS services or by applications that make use of CRSS. We take the approach that it is infeasible to determine which events of an application program or CRSS service are auditible, and, instead, let the application or service choose to audit those events deemed significant. The AL timestamps each audit event received and logs it to a permanent, protected audit repository. Timestamping permits the AL to maintain the proper sequencing of audit events. As a first cut, we intend for the ALI to provide only the single interface that simply timestamps and records audit events. The initial ALI does not have operations for opening, closing, and analyzing audit logs. We assume that all audit analysis is performed off-line.

Audit Operations An Audit Library Interface (ALI) exports only one interface function, CSSM_ALI_AuditEvent, to other services and applications. This operation is described below, in the format in which CSSM add-in library functions are described.

NAME

CSSM_AL_AuditEvent

SYNOPSIS

CSSM_RETURN CSSMAPI CSSM_AL_AuditEvent

(CSSM_AL_HANDLE ALHandle,
const CSSM_DATA_PTR Header,
const CSSM_DATA_PTR Data)

DESCRIPTION

This function records an audit event by timestamping the header and the data and then appending the result to the audit log. The Header is optional and may be used to uniquely identify the producer of the audit event. The Data is mandatory and is treated as an opaque object that represents the event being logged.

PARAMETERS

ALHandle(input)

The handle that describes the add-in audit library module to be used to perform this function.

Header(input/optional)

A pointer to the CSSM_DATA structure which contains optional header information for the audit event being logged.

Data(input)

A pointer to the CSSM_DATA structure which contains the opaque data object representing the audit event to be logged.

RETURN VALUE

CSSM_OK if the function was successful. CSSM_FAIL if an error condition occurred.

ERROR CODES

CSSM_AL_INVALID_HANDLE: Invalid AL handle.
CSSM_AL_INSERT_FAIL: Header/data logging caused an exception.

6. High-Level Services
The high-level security services provided by CRSS are listed in the table below. These services may be invoked by applications, service providers, or the framework.

High-level Service	Description
Authentication	credential management
Secure Connection	securing dynamically established communication between two parties
Secure Transaction/Exchange	file or message protection
Secure Retrieval and Storage	named-object protection and access
Secure Execution	securing local execution of executable objects

6.1 The Authentication Service
The authentication service extends the trust policy management by managing users' credentials. It provides an administrative interface for maintaining the credential database; in addition, it allows other high-level CRSS services, such as the Secure Connection Service, to obtain credentials associated with a user or a role.

There exists a wide variety of methods by which authentication and authorization can be provided [CRYPTO]. A conventional method is to use passwords to authenticate users. Once a user is authenticated to the system, any processes spawned by the user is marked as belonging to that user. When the process initiates an action requiring a key, the system can use the user identification associated with the process to determine if the process is allowed to use the key. A variation of this approach is to have a system configured in such a way that any user sitting at a certain terminal is given a certain authority. Another approach is to use a crypto device to give certain users access to crypto operations. Such a device does not give out keys but instead performs crypto operations for an active entity that can provide the needed personal identification number (PIN). In this approach, the system may not have any identification or authorization information associated with a particular active entity. The authorization is implicit in the active entity's ability to execute certain crypto operations requiring keys.

In the following interface description, the caller is the active entity invoking the interface call. The requester is the active entity making the original request. In most cases, the requester is a user or an application program. When the requester is the latter, then it must be running on behalf of a user or role.

The authentication service provides two interfaces. The first interface is the administrative interface for creating or importing new credentials and revoking existing credentials. This interface is provided only to those users who are authorized to access the credential database. Whenever a requester wishes to access the credential database, the authentication service checks that the requester has presented a valid credential to perform the operation. The second interface is a programming interface for obtaining access to the credentials of a user or a role. Because the presentation of a credential authenticates a user or a role, the CRSS does not export actual credentials to the application program interface. Instead, application programs must use those interface calls that return credential handles. Other high-level CRSS services may invoke those calls that return credentials and use them on behalf of the application programs.

Trust Models In order to demonstrate that the interface that we define below is adequate, we need to categorize the various trust models we have for obtaining credentials in the systems that we support. Here are a set of trust models that we describe:

keys are decoded with a password,
user files supply key information which is protected by access control of the system,
keys are held by a protected subsystem that uses the system to identify the identity or authority of the caller, and
key information is stored in a crypto device and key information is never exposed outside the crypto device.

We discuss these models one by one.

Passwords Decode Key Information In this model, there is a file containing a user identity or authorization together with encoded key information. The encoded key information can only be decoded when the appropriate password is supplied. It is very important in this model to protect the file containing the encoded keys; if this file is compromised then the problem of finding all the possible keys for a user is reduced to the problem of checking all possible passwords. Since the password length is much shorter than the key length, this significantly reduces the difficulty of breaking the encryption.

In this model credentials returned by the authentication service includes the key information that has been decoded by the password. The subject argument that is passed to the authentication service in the get credentials calls is ignored. To get the password, the authentication service queries the user to get the password.

The infrastructure interfaces in this model are:

add user or role
delete user or role
change user or role information

Users' Files Supply Key Information In this trust model, secret keys are held in user files protected by the security mechanisms of the host system. The credentials in this model include the secret key information found in the user file. The key information in the file is still encrypted with some user password, but in addition to this protection, the user file may get some extra protection through access controls. The only infrastructure interface that needs to be available is the change user or role information call.

The subject argument to the get credentials call may or may not be necessary in this trust model. There is no security reason that the CRSS cannot be a library loaded into the applications address space. If this is true, then the check that the key information can be legally obtained for the application simply reduces to an access control check by the operating system.

However, one might imagine a case where authentication is provided by a server. In this case, the authentication service needs the subject parameter and somehow has to use it to get the appropriate access check to be made on the user file with the key information.

Keys held by Protected Subsystem In this model the authentication service is a protected subsystem responsible for a protected database that holds the key information. The separation of the authentication service from potentially hostile applications is done by the operating system. When an application makes a request that results in a call to get credential, the authentication service must use the operating system's identification of the application.

In this model, there are no passwords that the authentication service needs to know about. The authentication service relies on the operating system to provide an identity with applications. This identity is provided by the subject parameter to the get credential call.

The infrastructure interfaces to the authentication service are as follows:

add user or role
delete user or role which takes
change user or role information

Crypto Device In this trust model secret keys exist only in a crypto device that is inserted into the system by the user. Therefore the authentication service has no databases that include private keys or passcodes.

The authentication service does not need to use the subject argument to the get credentials call. The authority of the user is determined through the pin supplied by the user that is passed to the crypto device.

While the authentication service does not hold passwords itself, it may use the interfaces to the crypto device to change password information on the device. The following is the set of interfaces to the authentication service.

add user or role
delete user or role
change user or role information

The Authentication Service Administrative Interface
We define the following administrative interface calls.

add user or role

delete user

change user or role information

create credential

import credential

revoke credential

install trusted server

add user or role requires the following information

a user identity or role
a credential type
optional a password
optional secret information, such as a key
other user or role information, such as a certificate

and returns

a status code

Depending on the credential type, passwords may not need to be stored for a given user. In addition, the system may not need to maintain any secret information that could be associated with a user.

delete user requires the following information

a user identity or role
a credential type
optional a password

and returns

a status code

change user or role information requires the following information:

a user or role
the type of change to be made
a credential type
optional a password
optional a new password
optional new secret information, such as a key
optional new user or role information, such as a certificate

and returns

a status code

If a given credential type does not require passwords, then neither password is required. If the credential type does use passwords then the

create credential requires the following information

a user or role
a credential provider identity
credential data, which is provider-specific

and returns

status code
a credential handle

import credential requires the following information

a foreign-type credential
the credential provider identity for the foreign credential
a native-type credential provider identity

and returns

a status code
the native-type credential

This function imports a credential from the specified foreign format into the native format of the specified credential library.

revoke credential requires the following information

a credential handle
the credential provider identity

and returns

status code

The function revokes the input credential.

install trusted server requires the following information

the name of a trusted server such as a certificate authority or a Kerberos [Kerberos] authorization server
optional secret information such as a symmetric key (in the kerberos case)
other server information such as a certificate

and returns

a status code

The Authentication Service Programming Interface
Whenever a caller requests credentials, the caller must present the requester's authorization to obtain the credentials. Authorization can be supplied in different ways, based on the trust model and underlying operating system. The CRSS supports three modes of operation:

The user has his or her authorization encrypted and stored in the CRSS;
The user supplies his or her authorization at login time;
The user supplies his or her authorization on a per-use basis.

When a requester requests to use its user's credentials, the authentication service constructs them in the following manner. First, the authentication service obtains the user's authorization. If the user chose either of the first two modes, then the authentication server first determines the requester's user via the get subject call and then uses the authorization implicit in that identity to construct the user's credentials via get credential with implicit authorization. For the last choice, the authentication service interacts with the user directly, via get credential with explicit authorization to obtain the user's authorization to construct the user's credentials.

We define the following programming interface calls.

get subject

get credential with implicit authorization

get credential with explicit authorization

get credential handle with implicit authorization

get credential handle with explicit authorization

get credential types

The get subject call returns the following information

subject

This call returns the requester that initially made a request of the CRSS. This call must be made in the high-level service that is called by the application. The point of this constraint is that it is possible that the implementation of inter-CRSS interfaces may involve context switches. Once the context switch is executed, the identity of the original requester may be lost.

The get credential with implicit authorization call requires the following information

the subject that represents the requester
optional a password
the credential type

and returns the following information

a status code
the user identity or authorization obtained
credential for the user identity or authorization

This call returns a credential for the caller. In order for this call to succeed, there needs to be some system default.

The get credential with explicit authorization call requires the following information

the subject that represents the requester
the user identity or authorization required
optional a password
the credential type

and returns the following information:

status code
the requested credential

This call returns a credential for the requested user identity or authorization. The mechanism by which it does this is system dependent. The need for the password is system dependent. On systems that do not provide a means of determining the user on whose behalf a subject is acting, the CRSS needs to make an additional check to ensure that the subject really is acting on behalf of the user.

The get credential handle with implicit authorization call requires the following information

the subject that represents the requester
optional a password
the credential type

and returns

a status code
the user identity or authorization obtained
a credential handle for the user identity or authorization

The get credential handle with explicit authorization call requires the following information

the subject that represents the requester
the user identity or authorization required
optional a password
the credential type

and returns

status code
the requested credential handle

The get credential types call requires the following information

the subject that represents the requester
the user identity or authorization required

and returns

a list of the types of credentials that are available to the given user identity or authorization

6.2 The Secure Connection Service
A connection is an agreement about how to communicate that is dynamically established between two parties. Two parties that wish to communicate start with an initial data exchange to define the connection. As a result of this data exchange, both parties can store common information about the connection such as the communication path, quality of service information and security information. This data exchange is known as opening the connection. This information store is then consulted whenever the two parties wish to communicate.

The purpose of the connection service is to take an existing connection and add security services [TLS]. The service does this by defining a data exchange that should be implemented using the existing connection. The approach is as follows. The application opens an insecure connection. One side of this insecure connection, which we call the initiator, asks the connection service for some data to pass to the other side of the connection, which we call the acceptor. The initiator then uses the existing connection to pass the data to the acceptor. This represents the first step in a protocol for implementing a secure connection. The acceptor passes this data to its connection service in order to obtain some data to use to reply to the initiator. The acceptor's connection service returns some data to the acceptor that can then be passed to the initiator. This protocol continues until either or both of the acceptor or the initiator gets an indication from their connection service that the exchange is complete. We are basing this service on that provided by the Generic Security Service Application Program Interface [GSS-API].

The goal of this protocol is the generation of a security context for the initiator and the acceptor. This security context defines an agreement between the initiator and the acceptor that allows them to implement security services on their shared connection. For example, the security context may include a secret key shared between the initiator and the acceptor that allows them to encrypt data passed over the connection. The Diffie-Hellman exchange is an example of a protocol that the connection service could implement that would generate such a shared secret key.

Interfaces to the Connection Service The connection service has interfaces for the following types of functionality:

the exchange of data to open a connection,
the cleanup to close a connection,
the association of properties with a connection ,
per message calls to implement certain properties associated with a connection, and
support for delegation of connections.

We describe these in individually.

The Connection Open Interface
In order to open a connection, the connection service must define a data exchange between two parties, the initiator and the acceptor. We define four interfaces that are used to implement this exchange. The initiator calls the start security context negotiation call to obtain data to send to the acceptor. The acceptor calls the start security context negotiation reply call to accept this data from the initiator and to determine what to send back. Then the initiator calls continue security context negotiation to continue the protocol. The acceptor calls continue security context negotiation reply to reply.

The start security context negotiation call takes the following arguments:

optional a credential handle for the initiator. If no credentials are supplied, then this call obtains credentials from the system.
a name for the intended target of the connection.
optional a name for the security context mechanism to be used with the connection. This is to be used when the caller already knows which mechanism is the best one to be used.
the properties that the caller requests be associated with the connection. These properties include anonymity, authentication, non-repudiation, confidentiality, integrity and a delegation flag. The delegation flag gives the acceptor the ability to make additional connections on behalf of the initiator.
information about the underlying connection on which messages are passed. This information is used to optimize communication.

and returns

a status indicator indicating the completion of the transaction or that some error has occurred. The two success status codes that can be returned are SUCCESS, indicating that the negotiation is complete, and CONTINUE_NEEDED, indicating that the protocol needs to continue.
a handle for the security context to be established.
data to send to the acceptor of the connection.
properties that are associated with the connection as a result of the exchange. Unless otherwise specified, the listed set of properties is only valid when the status indicator returns SUCCESS, indicating that the negotiation is complete. These properties may be a subset of the properties that were requested. If so, the caller can discard the connection using the interface calls described below.

The start security context negotiation reply call takes the following arguments

optional a credential handle for the acceptor. If no credentials are supplied, then the accept connection call gets credentials from the system.
the data that has been received from the initiator of the connection.
optional a name for the security context mechanism to be used with the connection. This is to be used when the caller already knows which mechanism is the best one to be used.
information about the underlying connection on which messages are passed. This information is used to optimize communication.

and returns

a status indicator indicating the completion of the transaction or that some error has occurred. The two success status codes that can be returned are SUCCESS, indicating that the negotiation is complete, and CONTINUE_NEEDED, indicating that the protocol needs to continue.
a handle for the connection to be established.
null or the name of the initiator of the connection. This parameter may be null if the security context negotiation has not yet been completed. In addition, this parameter may never be filled in with the name of the initiator of the connection if the initiator requested anonymity.
data to send to the initiator of the connection.
properties that are associated with the connection as a result of the exchange. Unless otherwise specified, the listed set of properties is only valid when the status indicator returns SUCCESS, indicating that the negotiation is complete. These properties may be a subset of the properties that were requested. If so, the caller can discard the connection using the interface calls described below.

The continue security context negotiation call takes the following arguments:

a handle for the security context to be established. This handle corresponds to the handle returned by "start security context negotiation".
the data that has been received from the acceptor of the connection.

and returns

a status indicator indicating the completion of the transaction or that some error has occurred. The two success status codes that can be returned are SUCCESS, indicating that the negotiation is complete, and CONTINUE_NEEDED, indicating that the protocol needs to continue.
data to send to the acceptor of the connection.
properties that are associated with the connection as a result of the exchange. Unless otherwise specified, the listed set of properties is only valid when the status indicator returns SUCCESS, indicating that the negotiation is complete. These properties may be a subset of the properties that were requested. If so, the caller can discard the connection using the interface calls described below.

The continue security context negotiation reply call takes the following arguments:

a handle for the connection to be established.
data that has been received from the initiator of the connection.

and returns

a status indicator indicating the completion of the transaction or that some error has occurred. The two success status codes that can be returned are SUCCESS, indicating that the negotiation is complete, and CONTINUE_NEEDED, indicating that the protocol needs to continue.
null or the name of the initiator of the connection. This parameter may be null if the security context negotiation has not yet been completed. In addition, this parameter may never be filled in with the name of the initiator of the connection if the initiator requested anonymity.
data to send to the initiator of the connection.
properties that are associated with the connection as a result of the exchange. Unless otherwise specified, the listed set of properties is only valid when the status indicator returns SUCCESS, indicating that the negotiation is complete. These properties may be a subset of the properties that were requested. If so, the caller can discard the connection using the interface calls described below.

Taken together these calls define a protocol for defining a security context that is encoded in the security context handle. The connection service has a series of calls that implement the features provided by the security context. For example, if the security context supports confidentiality, then the application can encrypt a message by passing it to the connection service along with the security context.

The Connection Close Interface
Once established, a connection can be closed at any time. To close a connection, the two parties do any necessary cleanup first and then the connection information is thrown away. When a connection is released, the connection can never again legally be used to exchange data between the parties. The reason for the "legal" qualifier is that one of the attacks against a connection is a variation of the replay attack; in this attack, data is exchanged after the connection is closed.

When a connection is no longer needed, the applications need an interface for cleaning up the security context for the connection. There are two interfaces that are needed for this category. The first call simply deletes a security context and the second handles cleanup in the case that there is an error or a delete on the other side of the connection.

The delete security context call takes the following arguments

a security context handle to delete

and returns

a status code.
a token to send to the other end of the connection to start a cleanup there.

The process security context token call takes the following arguments:

a security context handle
a token received from the other end of the connection.

and returns

a status code.

The Connection Properties Interface
A client with an open connection may need to determine what properties are available in the security context. Properties that concern us include:

the security context supports confidential messages
the security context supports integrity
one or both ends of the connection have been authenticated.
the lifetime of the security context.
the security context mechanism type

The query security context call takes a the following arguments:

a security context

and returns

the name of the initiator and the acceptor if they are available
the security properties associated with the security context
the security context mechanism type

The Per-Message Interface
The connection service needs an interface by which security enhancements can be added to a message. The interfaces needed are get MIC and verify MIC for data integrity, and encrypt and decrypt for data confidentiality.

The get MIC call takes the following parameters

a security context handle
the data that needs to be signed

and returns

a status code
the signature associated with the data

The verify MIC call takes the following parameters

a security context handle
the data that has been signed
the signature for the data

and returns

a status code

The encrypt call takes the following parameters

a security context handle
the data to encrypt

and returns

a status code
the encrypted data

The decrypt call takes the following parameters

a security context handle
the encrypted data

and returns

a status code
the decrypted data

6.3 Secure Transaction/Exchange Service
The purpose of the transaction/exchange service is to service applications requiring protection of a unit of data, e.g., a file or message. Since the protection provided is independent of any concurrent contact with the eventual recipient of the protected data, this service would be useful to such applications as secure electronic mail. We are basing this service on that provided by the Independent Data Unit Protection Generic Security Service Application Program Interface [IDUP-GSS-API], [GSS-API].

The protections provided via the transaction/exchange service interface include the following:

data origin authentication with data integrity,
data confidentiality with data integrity, and
support for non-repudiation services.

The transaction/exchange service has interfaces for the following types of functionality:

establishing and abolishing the security environment,
providing the following types of security protection enhancement to the data:

signature and encryption protection and unprotection and
non-repudiation evidence support, and

establishing an environment and protecting the data in a single step.

We cover these in the following sections.

Establishing and Abolishing the Security Environment
This group of calls is used to establish and abolish security environments. Applications must establish security environments prior to invoking calls to add security enhancement to their data. Once applications have finished with transactions, they can invoke the abolishing security environment calls to clean up the security environment.

The acquire credential call is used to acquire the credentials necessary to establish a security environment.

The acquire credential call takes the following arguments:

optional a locally-determined identity indicator for the desired identity. If no value is supplied, the system provides a credential corresponding to the principal identity associated with the user.
optional an authenticator, most likely a passphrase required if the system has not previously authenticated the user as having the desired identity.
an integer which determines the span of validity in seconds of the returned credential handle. A value of 0 requests the system default value for this parameter.

and returns

a status flag indicating the completion of the operation.
a credential handle
the assigned span of validity in seconds of the returned credential handle.

The get token details call is used by the application to inquire of a unit of protected data the mechanism type used in its creation. This allows the recipient of the protected data to set up a security environment in which to process it.

The get token details call takes as it sole argument the protected data token and returns the following information, which is encapsulated in the protected data in a mechanism-independent fashion, as defined in [1] below:

a status flag indicating the completion of the operation.
the mechanism type used to protect the data
a boolean indicating whether or not the data received signing/encryption protection.
a boolean indicating whether or not the data received non-repudiation protection.

The establish security environment call must be invoked by an application before it can invoke data protection interface calls. Using the information in the credential referenced by the supplied credential handle, this routine initializes any structures required by the protection mechanism.

The establish security environment call takes the following arguments:

optional a credential handle. If no credentials are supplied, then this call obtains default credentials from the system.
optional a cryptographic mechanism type. If none is provided, a mechanism is supplied by the system.
the security properties desired in this environment.

and returns

a status flag indicating the completion of the operation.
a handle for the established security environment.
the cryptographic mechanism to be used.
the subset of the requested security properties available in the selected cryptographic mechanism.

The returned environment handle is used in all future operations which make reference to this security environment.

The abolish security environment call takes as its argument a security environment handle. It throws away any information specifically related to the specified environment.
The security environment inquiry call takes as its argument a security environment handle, and returns the following information:

a status flag indicating the completion of the operation.
the selected cryptographic mechanism
the subset of the requested security properties available in the selected cryptographic mechanism.

Data Protection Calls
This group of calls is used within an established security environment to provide protection and unprotection services. The calls support caller-requested data origin authentication with data integrity, confidentiality with data integrity, and non-repudiation evidence support.

The sign/encrypt calls These calls can be used to provide to the application an interface to the underlying cryptography mechanisms providing signature and encryption protection and unprotection services.

The sign/encrypt buffer protect call takes as its arguments:

a security environment handle
the requested protection options. These options include:

sign only
encrypt only
sign and encrypt, letting the selected mechanism choose the order
sign then encrypt data, leaving the signature in the clear.
sign then encrypt everything.
encrypt, then sign the ciphertext.
a representation of the quality required of the signature algorithm
a representation of the quality required of the encryption algorithm

the buffer to be protected.

and returns

a flag indicating the success or failure of the operation.
the protected buffer
the signature buffer

The inverse operation to sign/encrypt buffer protect is sign/encrypt buffer unprotect. This call takes as its arguments:

a security environment handle
the protected buffer
the signature buffer

and returns

a flag indicating the success or failure of the operation.
the protection options used, as described above.
the name of the originator
the time when protection was applied.
the unprotected buffer.

Non-repudiation Evidence Calls
This group of calls provides an interface to the underlying cryptographic services when only non-repudiation evidence is of interest to the application. The list of evidence types includes the following:

proof of origin - this service counters the threat of impersonation of the message originator.
proof of creation - this service counters the threat of the originator of a message denying creating the message.
proof of sender - this service counters the threat that the originator of a message denies sending the message.
proof of delivery - this service counters the threat of falsely acknowledged receipt.
proof of receipt - this service counters the threat of falsely denying that a message was received
proof of recipient approval - this service counts the threat that the recipient may approve the content of a received message and thereafter deny it.

Evidence is provided in the form of a token of evidence that either includes the associated data or a unique reference to that data.

The generate non-repudiation evidence generates a non-repudiation token associated with the data passed. Two types of evidence generation operations can be performed: generation of a token that includes evidence and/or evidence request; and generation of a token that includes evidence generated as a response to a request. The generate non-repudiation evidence call takes the following arguments:

a security environment handle
the data buffer
a flag indicating the desired type of evidence generation operation
a parameter indicating in detail the types of evidence requested and any other pertinent information.

and returns

a flag indicating the success or failure of the operation.
an evidence token

The verify non-repudiation evidence operation checks the validity of an evidence token and discloses its contents.

The verify non-repudiation evidence operation takes the following arguments:

a security environment handle.
an evidence token
the data buffer, if that information is not present in the token.

and returns

a flag indicating the success or failure of the operation.
the data buffer, if that information was contained in the token.
a parameter indicating in detail the types of evidence requested and any other pertinent information.

Single Step Data Protection Calls
This group of calls is used without an established security environment to provide protection and unprotection services. The calls support caller-requested data origin authentication with data integrity, confidentiality with data integrity, and non-repudiation evidence support. These calls are implemented as the following sequence:

establish the security environment
protect the data
abolish the security environment

If any error occurs during these steps, all cleanup work is automatically done including abolishing the security environment.

The sign/encrypt calls

The sign/encrypt buffer protect single step call takes as its arguments:

the requested protection options. These options include:

sign only
encrypt only
sign and encrypt, letting the selected mechanism choose the order
sign then encrypt data, leaving the signature in the clear.
sign then encrypt everything.
encrypt, then sign the ciphertext.
a representation of the quality required of the signature algorithm
a representation of the quality required of the encryption algorithm

the buffer to be protected.

and returns

a flag indicating the success or failure of the operation.
the protected buffer
the signature buffer

The inverse operation to sign/encrypt buffer protect single step is sign/encrypt buffer unprotect single step. This call takes as its arguments:

the protected buffer
the signature buffer

and returns

a flag indicating the success or failure of the operation.
the protection options used, as described above.
the name of the originator
the time when protection was applied.
the unprotected buffer.

Single Step Non-repudiation Evidence Calls
As with the data protection calls, the non-repudiation of evidence calls also have a single step version.

The generate non-repudiation evidence single step call takes the following arguments:

the data buffer
a flag indicating the desired type of evidence generation operation
a parameter indicating in detail the types of evidence requested and any other pertinent information.

and returns

a flag indicating the success or failure of the operation.
an evidence token

The verify non-repudiation evidence single step operation checks the validity of an evidence token and discloses its contents.

The verify non-repudiation evidence single step operation takes the following arguments:

an evidence token
the data buffer, if that information is not present in the token.

and returns

a flag indicating the success or failure of the operation.
the data buffer, if that information was contained in the token.
a parameter indicating in detail the types of evidence requested and any other pertinent information.

6.4 The Secure Retrieval and Storage Service

The secure object retrieval and storage service provides applications with the ability to access objects by name. Access to the objects is controlled by an access control policy. Therefore, all calls that require an access control check must also take a handle for the credentials of the caller. It has the following interfaces:

open object which requires the following information

the name of an object
optional a credential handle for the caller
the access modes requested for the object

and returns

a status code
a file descriptor for the object

exercise access which requires the following information

a file descriptor for an object
the name of the operation being performed (in particular, these operations must include read and write)
optional data for the operation

and returns

a status code
optional data returned by the operation

close object which takes a

object descriptor

and returns

a status code.

set object permissions which requires the following information

the name of an object
a credential handle for the caller
the permissions (including ownership) for the object

and returns

a status code

delete object which requires the name of an object and returns a status code.

6.5 Secure Execution
The purpose of the secure execution service is to provide a mechanism for retrieving a remote object, for example a Java applet, which includes instructions for "execution" of that object; and for insuring that the resulting local execution is "secure". Examples of two very different mechanisms for insuring security might be

a secure environment for the local execution of the object
the use of a digital signature to indicate that the object is safe to execute

The design of the secure execution service has been deferred to a subsequent report.

7. Conclusion and Plans
The architecture described above provides a basis for constructing a collection of services that can fulfill the security needs of a wide variety of applications. The architecture also provides a means for maintaining a high degree of survivability for this collection of services. The designs for the specific services given above are initial proposals and are subject to refinement as the development of the CRSS proceeds. In designing these services we have tried to make use of prior work by basing the designs on CDSA, GSSAPI, and GSSAPI-IDUP. We also anticipate that we will be able to use service providers developed for CDSA and possibly portions of the CDSA CSSM in the implementation of the CRSS.

The architecture is only the first step in the development of CRSS. Subsequent steps include the following:

design of selection algorithms for choosing service providers and identification of the data necessary to support the selection,
design of techniques and algorithms for replacing service providers in the presence of failures,
detailed design and specification of the framework,
detailed specification of the service APIs,
implementation of the above,
techniques and tools for analysis of the survivability of the CRSS.

These will be described in subsequent reports.

8. References

References for CDSA 1.2

[CDSA_1.2] Common Data Security Architecture Specification, Draft Release 1.2, Intel, March, 1997.

[CSSM_API_1.2] Common Security Services Manager Application Programming Interface (API), Draft for Release 1.2, Intel, March, 1997.

[CSSM_SPI_1.2] Common Security Services Manager Cryptographic Service Provider Interface (SPI) Specification, Draft for Release 1.2, Intel, March, 1997.

[CSSM_CLI_1.2] Common Security Services Manager Certificate Library Interface (CLI) Specification, Draft for Release 1.2, Intel, March, 1997.

[CSSM_DLI_1.2] Common Security Services Manager Data Storage Library Interface (DLI) Specification, Draft for Release 1.2, Intel, March, 1997.

[CSSM_TPI_1.2] Common Security Services Manager Trust Policy Interface (TPI) Specification, Draft for Release 1.2, Intel, March, 1997.

References for CDSA 2.0

[CDSA_2.0] Common Data Security Architecture Specification, Draft Release 2.0, version 1.0, The Open Group, October, 1997

[CSSM_API_2.0] CSSM Application Programming Interface, Draft Release 2.0, version 1.0, The Open Group, October, 1997.

[CSSM_SPI_2.0] Cryptographic Service Provider Interface Specification, Draft Release 2.0, version 1.0, The Open Group, October, 1997.

[CSSM_CLI_2.0] Certificate Library Interface Specification, Draft Release 2.0, version 1.0, The Open Group, October, 1997.

[CSSM_DLI_2.0] Data Storage Library Interface Specification, Draft Release 2.0, version 1.0, The Open Group, October, 1997.

[CSSM_TPI_2.0] Trust Policy Interface Specification, Draft Release 2.0, version 1.0, The Open Group, October, 1997.

[CSSM_EMM_2.0] CSSM Elective Module Management, Draft Release 2.0, version 1.0, The Open Group, October, 1997.

[CSSM_KR_API_2.0] Key Recovery Application Programming Interface Specification, Draft Release 2.0, version 1.0, The Open Group, October, 1997.

[CSSM_KRI_2.0] Key Recovery Service Provider Interface Specification, Draft Release 2.0, version 1.0, The Open Group, October, 1997.

Other References

[CRYPTO] Applied Cryptography, Second Edition, Bruce Schneier, John Wiley and Sons, Inc., 1996.

[GSS-API] Generic Security Service Application Program Interface, Version 2 , J. Linn, OpenVision Technologies, January 1997.

[IDUP-GSS-API] Independent Data Unit Protection Generic Security Service Application Program Interface (IDUP-GSS-API), D. Adams, Entrust Technologies, November 1997.

[KERBEROS] The Kerberos Network Authentication Service (Version 5), Internet RFC-1510, September, 1993.

[TLS] The TLS Protocol, Version 1.0, Tim Dierks and Christopher Allen, Consensus Development, November, 1997.

SPARTA ISSO

Finished Projects

Security Architecture and Modeling

Composable Replaceable Security Services for Survivable Distributed Systems