crypto_intro(3sec)

Introduction to the signature algorithm API registration facility

Description

This reference page describes the data types used by the signature algorithm API (or "cryptographic'') module registration API.

Accessing and Using Cryptographic Modules

Cryptographic implementations (also known as "algorithms'') are identified by OIDs (object identifiers).

Policy implementors are recommended to access cryptographic modules mainly through the following routines, which perform all locking necessary to make the calls thread safe, and also transparently handle any context information that a given cryptographic implementation may need.

· pkc_crypto_get_registered_algorithms(3sec)
Call this routine to get an OID set describing the currently registered algorithm implementations.

· pkc_crypto_sign(3sec)
Call this routine to get data signed.

· pkc_crypto_verify_signature(3sec)
Call this routine to verify signed data.

· pkc_crypto_generate_keypair(3sec)
Call this routine to generate a pair of public/private keys.

Information about a cryptographic module may be obtained by calling pkc_crypto_lookup_algorithm(3sec).

Data can also be signed and verified by looking up the desired algorithm (with pkc_crypto_lookup_algorithm(3sec)) and then explicitly calling the module's (sign)( ) or verify( ) routine, although in this case the calling application must take care to avoid multi-threading problems. It is also responsible for opening the crypto module prior to use and for closing it afterwards.

Implementing Cryptographic Modules

Every cryptographic module must export a pkc_signature_algorithm_t object.

The pkc_signature_algorithm_t data type is used to register a new cryptographic module with the certification API. It fully describes a specific implemented cryptographic algorithm, and provides entry points to its sign( ) and verify( ) functions. It is defined as follows:

typedef struct {

OM_uint32 version;

gss_OID_desc alg_id;

pkc_alg_flags_t flags;

char reserved[32 - sizeof(pkc_alg_flags_t)];

char * (* name)(void);

unsigned32 (*open) (void** context);

unsigned32 (*close) (void** context);

unsigned32 (*verify) (void ** context,

sec_pk_gen_data_t * data,

sec_pk_data_t * public_key,

sec_pk_data_t * signature);

unsigned32 (*sign) (void ** context,

sec_pk_gen_data_t * data,

sec_pk_data_t * private_key,

sec_pk_data_t * signature);

unsigned32 (*generate_keypair) (void ** context,

unsigned32 size,

void * alg_info,

sec_pk_data_t * private_key,

sec_pk_data_t * public_key);

} pkc_signature_algorithm_t;

The (name)( ), (open)( ), (close)( ), (verify)( ), (sign)( ) and (generate_keypair)( ) routines must be implemented by the application implementing the algorithm and registered by calling the pkc_crypto_register_signature_alg(3sec) routine. Note, however, that all the routines except for (verify)( ) are optional. Explanations of all the fields in pkc_signature_algorithm_t are contained in the following subsections.

Cryptographic Module Data Fields

The structure contains the following data fields:

version
Identifies the version of the certification API for which the module is implemented. The value of this field is always pkc_V1 for DCE 1.2.

alg_id
An object identifier that identifies the algorithm; the OID that appears in certificates signed by the algorithm.

flags
Describes whether the module's (sign)( ) and (verify)( ) functions are threadsafe, and whether the module supports simultaneous crypto sessions.

The version and alg_id fields are required for all versions of this data structure. Other fields may be version dependent.

Cryptographic Module Functions

NULL may be supplied as the address of the (name)( ), (open)( ), (close)( ), (sign)( ), or (generate_keypair)( ) routines, if the cryptographic module does not provide or require the corresponding feature; the presence of these functions in a cryptographic module is optional. However, all cryptographic modules must provide a (verify)( ) function.

Algorithm Flags Data Type

The pkc_alg_flags_t data type is used to record various information about a cryptographic module. It is defined as follows:

typedef struct {

char threadsafe;

char multi_session;}

pkc_alg_flags_t;

The structure contains two fields which have the following meanings:

threadsafe
Has a non-zero (TRUE) value if the module's (sign)( ) and (verify)( ) routines may be safely called simultaneously (within a single crypto session) by multiple threads.

multi_session
Has a non-zero (TRUE) value if the module implementation supports multiple simultaneous crypto sessions.

Cryptographic Module Data Fields

The structure contains the following data fields:

version
Identifies the version of the certification API for which the module is implemented. The value of this field is always pkc_V1 for DCE 1.2.

alg_id
An object identifier that identifies the algorithm; the OID that appears in certificates signed by the algorithm.

flags
Describes whether the module's (sign)( ) and (verify)( ) functions are threadsafe, and whether the module supports simultaneous crypto sessions.

The version and alg_id fields are required for all versions of this data structure. Other fields may be version dependent.

Cryptographic Module Functions

Name

(name)( )
Returns the algorithm name as a string for use in diagnostic or auditing message

Synopsis

char * (* name)(void);

Description

The name should be returned in storage allocated using the pkc_alloc( ) function defined in pkc_base.h. Note that this is the only cryptographic module routine that may be called without first calling the (open)( ) routine.

This routine is mandatory.

Name

(open)( )
Opens and initializes the cryptpgraphic module

(close)( )
Closes the cryptographic module
Both routines are optional.

Synopsis

unsigned32 (*open) (void** context

unsigned32 (*close) (void** context);

Parameters

Output

context
An opaque (to the caller) data structure containing any state information required by the module across calls.

Description

Before invoking any of the module's encryption routines (e.g., (sign)( ) or (verify)( ), the certification API will invoke the module's (open)( ) function. Once the module's (close)( ) routine has been invoked, the certification facility will invoke (open)( ) again before making any further calls to the module.

Both the (open)( ) and the (close)( ) routines require only one argument, context. If the cryptographic module requires state information to be maintained between calls, it may use the context parameter to do this. The information is initialized by the (open)( ) routine and returned as an opaque object to the caller, who then passes the parameter to subsequent (sign)( ), (verify)( ), (generate_keypair)( ), or (close)( ) calls.

Note that if the (open)( ) routine stores any state in the context parameter, the (close)( ) routine should free this storage.

Name

(sign)( )
Calculates a signature over the supplied data using the specified key

Synopsis

unsigned32 (*sign) (void ** context

sec_pk_gen_data_t * data,

sec_pk_data_t * private_key,

sec_pk_data_t ** signature)

Parameters

Input

context
An opaque (to the caller) data structure containing any state information required by the module across calls.

data
The certificate data that is to be signed.

private_key
Key to use to generate the signature, provided as a BER-encoded PrivateKeyInfo object, as defined in PKCS#8, as appropriate for the algorithm.

Output

signature
The signature generated on the data passed. Storage allocation should be performed by calling the pkc_alloc( ) and pkc_free( ) functions defined in pkc_base.h.

Description

The (sign)( ) routine calculates a signature over the supplied data, using the specified key. The private_key parameter will be a BER-encoded PrivateKeyInfo data object. The signature should be returned by the function; storage allocation should be performed by calling the pkc_alloc( ) and pkc_free( ) functions defined in pkc_base.h.

This routine is optional.

Name

(verify)( )
Checks the supplied signature against the supplied data, thus verifying the certificate in which the data and the signature appear

Synopsis

unsigned32 (*verify) (void ** context

sec_pk_gen_data_t * data,

sec_pk_data_t * public_key,

sec_pk_data_t * signature,

Parameters

Input

context
An opaque (to the caller) data structure containing any state information required by the module across calls.

data
The entire certificateInfo.

public_key
The public key to use on the signature.

signature
The signature to be verified.

Description

The (verify)( ) routine checks the supplied signature against the supplied data. The public_key parameter is a SubjectPublicKeyInfo data structure, encoded in BER, as found within an X.509 certificate.

The routine should return 0 for a correct signature, pkc_invalid_signature for an incorrect signature, or another DCE-defined error status to indicate any other errors.

This routine must be implemented in any cryptographic module.

Name

(generate_keypair)( )
Generates a pair of public and private keys

Synopsis

unsigned32 (*generate_keypair) (void ** context,

unsigned32 size,

void * alg_info,

sec_pk_data_t * public_key,

sec_pk_data_t * private_key,

Parameters

Input

context
An opaque (to the caller) data structure containing any state information required by the module across calls.

size
Specifies the key size.

alg_info
Specifies the crypto module.

Output

private_key
The generated private key.

public_key
The generated public key.

Description

The (generate_keypair)( ) routine generates a pair of private and public keys. The size parameter should be used by the routine to determine the key size in some way (for the RSA algorithm, for example, it should be treated as the number of bits in the key modulus). The private_key and public_key parameters should return BER-encoded PrivateKeyInfo and SubjectPublicKeyInfo data objects respectively. The alg_info parameter can be used for algorithm-specific information to modify the key generation process. However, all crypto modules that offer this function should be prepared to operate when NULL is provided for this parameter.

This routine is optional.

Related Information

Functions:
pkc_crypto_generate_keypair(3sec)
pkc_crypto_get_registered_algorithms(3sec)
pkc_crypto_lookup_algorithm(3sec)
pkc_crypto_register_signature_alg(3sec)
pkc_crypto_sign(3sec)
pkc_crypto_verify_signature(3sec)