typhoon.h

IBM的Linux上的PKCS#11实现

          seq_num - The sequence number with MSB in byte 0 location
          update_key - Whether the IVs/StateVars for ciphers be read back. For
                 ARCFOUR, the state array, state_x, state_y will be updated.
                 For (T)DES CBC, the original IV will be updated with that read
                 from CR7020 DDR.
   output: sslv3_ciphertext - The encrypted/HMACed SSLv3 record data and size
 */
RC CR_encrypt_sslv3_with_key( token *sslv3_ciphertext, BYTE *trans_id,
                              BYTE *seq_num, token *sslv3_compressed,
                              INT32 key_struct_address, BYTE update_key ) ;

/* The following function performs entire TLS1.0 outbound record layer
   processing, which has a key passed along with the record.  This function is
   a combination of the CR_insert_tlsv1_key() and CR_encrypt_tlsv1_record(),
   which performs these 2 tasks using a single ioctl command. This function
   will also update the SA and chip numbers in the library.
   input: trans_id - The transaction identifier that identifies the key
                     and cipher/hash, inside the library
          tlsv1_compressed - The compressed TLS record data and size
          seq_num - The sequence number with MSB in byte 0 location
          update_key - Whether the IVs/StateVars for ciphers be read back. For
                 ARCFOUR, the state array, state_x, state_y will be updated.
                 For (T)DES CBC, the original IV will be updated with that read
                 from CR7020 DDR.
   output: tlsv1_ciphertext - The encrypted/HMACed SSLv3 record data and size
 */
RC CR_encrypt_tlsv1_with_key( token *tlsv1_ciphertext, BYTE *trans_id,
                              BYTE *seq_num, token *tlsv1_compressed,
                              INT32 key_struct_address, BYTE update_key ) ;

/* Encrypts an IPsec packet using the ESP protocol. The input token
 * esp_plaintext should contain the outer IP header, followed by 8 bytes
 * for the SPI & sequence number, followed by the data packet, followed by
 * the 1 byte for the next header. oheader_len should be set to the length
 * of the outer IP header in bytes. The returned esp_ciphertext will be
 * filled with the encrypted packet, padding, and authentication MAC if
 * used.
 */
RC CR_encrypt_ipsec_esp( token *esp_ciphertext, BYTE *trans_id,
                         token *esp_plaintext, unsigned int oheader_len );

/* Decrypts an IPsec packet using the ESP protocol. The input token
 * esp_ciphertext should contain the outer IP header, followed by 8 bytes
 * for the SPI & sequence number, followed by the IV & encrypted data
 * packet (including pad & next header bytes), followed by an optional
 * MAC. The oheader_len should be set to the length of the outer header in
 * bytes. The MAC, if used, is verified and discarded and the payload
 * decrypted. The outer header, next header, and IV will be either returned
 * or stripped depending on the SA flags used when initializing the
 * transaction.
 */
RC CR_decrypt_ipsec_esp( token* esp_plaintext, BYTE* trans_id,
                         token* esp_ciphertext, unsigned int oheader_len );

/* Computes the MAC for an IPsec packet using the AH protocol. The input
 * token ah_plaintext should contain the outer IP header followed by
 * 8 bytes for the SPI and sequence number followed by the packet.
 * The oheader_len should contain the length of the outer header in
 * bytes. The MAC is computed and returned in ah_ciphertext. Note that
 * the payload data itself is not returned. Also note that any mutable
 * fields in the outer IP header must be zeroed out before calling this
 * function.
 */
RC CR_encrypt_ipsec_ah( token* ah_ciphertext, BYTE* trans_id,
                        token* ah_plaintext, unsigned int oheader_len );

/* Verifies the MAC for an IPsec packet using the AH protocol. The input
 * token ah_ciphertext should contain the outer IP header followed by 8
 * bytes for the SPI and sequence number followed by the MAC followed by
 * the packet. The oheader_len should contain the length of the outer header
 * in bytes. The MAC is verified and SUCCESS returned if it is valid. Note
 * that no data is returned. Also note that any mutable fields in the outer
 * IP header must be zeroed out before calling this function.
 */
RC CR_decrypt_ipsec_ah( BYTE* trans_id, token* ah_ciphertext,
                        unsigned int oheader_len );

/* This function is used for performing hash/HMAC operations on the argument. This
   function requires an algorithm auth_code. The secret key(s) for HMAC were passed in 
   separately, if trans_id is not NULL. If trans_id is NULL, then the secret_key must be
   valid for HMAC.  
              Definition: HMAC_hash(secret_key, argument)    
   For performing hash operation without secret_key: trans_id will be NULL, and 
   secret_key will be NULL. For hash operation with secret_key, the key must be
   part of the argument(s), and trans_id must be NULL, and secret_key components
   must be NULL.
   inner_argument will be NULL for single hash and HMAC operations. outer_argument
   will be used for single, double, and HMAC operations.                         */
RC CR_authenticate(token *digest, BYTE *trans_id, CR_AUTH_CODE auth_code, token *inner_argument,
                   token *outer_argument, hmac_key *secret_key) ; 

/* The following function will be used for performing the Hash_Init
   operation for SHA1 and MD5. This function will internally create
   a context for a new hash operation series and associate it with the
   given transaction id.
   input: trans_id - The transaction id.
          auth_code - The Hash code, either SHA1 or MD5
   output: context - Not used.
           RC must be SUCCESS */
RC CR_HashInit(BYTE *trans_id, void **context, CR_AUTH_CODE auth_code) ;

/* The following function will be used for performing incremental hash operations
   for MD5 and SHA1. The application will pass-in the address to the cr_hash_ctx
   structure. This function will accumulate the passed-in data until the size
   exceeds 64 Bytes, in which case, this function will pass all data with a
   size which is a multiple of 64 to the device for processing.
   input: trans_id - Transaction id passed to HashInit
          context - Ignored
                previous successful call to CR_HashInit
          arg - The input data and size to be incrementally processed for
                the hash op specified in the cr_hash_ctx struct.
   output: RC must be SUCCESS */
RC CR_HashUpdate(BYTE *trans_id, void *context, token *arg) ;

/* The following function will be used for performing the final hash operation
   for MD5 and SHA1. The application will pass-in the address to the cr_hash_ctx
   structure. This function will add necessary padding to the remaining bytes in
   the ctx buffer, and perform the final hash processing. This function will also
   cleanup the ctx data structure and the SA in the device.
   input: trans_id - Transaction id passed to HashInit
          context - Ignored
   output: result - The application must allocate memory (16B for MD5/20B for SHA1)
                    for getting the final digest
           RC must be SUCCESS */
RC CR_HashFinal(BYTE *result, BYTE *trans_id, void *context) ;

/* The following function is used for performing the Pseudo Random Function (PRF)
   operation on the argument (seed) and label, and setting the desired length in the 
   result parameter. The prf output hash will be placed in result.  If the trans_id
   is NULL, all the components of prf_key: secret, OR, idigest_md5, odigest_md5, 
   idigest_sha1, odigest_sha1 must be valid. If trans_id is not NULL, the secret keys 
   were passed in separately, and if passed in here, they will be ignored.
          Definition: PRF(secret_key,label,seed)[desired_length]               */
RC CR_prf(token *result, BYTE *trans_id, token *seed, token *label, prf_key *secret_key) ;

/**************************************************************************
                         Transaction Functions 
***************************************************************************/

/* The following function is used for initiating a new transaction. This function
   returns a pointer to the transaction identifier, if success, or 
   NULL, if failed.    */
BYTE *CR_new_transaction(void) ;

/* The following function is used for removing a transaction from the system.
   This function requires that a valid pointer, preferably the same as returned
   by CR_new_transaction(), is used as the argument. This function will free
   the memory associated to store the trans_id value. */
RC CR_delete_transaction(BYTE *trans_id) ;

/* The following function returns the SA address in Typhoon's DDR memory,
   corresponding to the transaction identifier that is passed into this
   function. */
RC CR_get_sa_address(INT32 *sa_address, BYTE *trans_id) ;

/* The following function is used to upload a new key into the system. The
   op_code/auth_code will identify the crypto/hash algorithm for these keys.
   The library will use these codes to interpret the address pointer of
   the appropriate crypto/hash struct like des_key, aes_key, and other key
   structures identified in the header file.  Please note that for auth_code
   to be used, the value of op_code must be AUTHENTICATE_OP, otherwise the
   value of auth_code will be ignored. Application doesn't create a key for
   hash operations, the library will generate those keys. The application 
   needs to create the keys for HMAC operations only. Also, the application
   cannot establish keys for RSA and DSA operations.                    */
RC CR_insert_cipher_key(BYTE *trans_id, CR_OP_CODE op_code, CR_AUTH_CODE auth_code, 
                        INT32 key_struct_address) ; 

/* The following function will be used for inserting SSLv3 security parameter
   values into the library. The address pointer will point to the sslv3_tls_key 
   struct. This function will cross verify the input data parameters. This security
   parameter struct contains all the keys necessary to perform encryption/decryption
   and MAC operations.                                                                */
RC CR_insert_sslv3_key(BYTE *trans_id, INT32 key_struct_address) ;

/* The following function will be used for inserting TLS1.0 security parameter
   values into the library. The address pointer will point to the sslv3_tls_key 
   struct. This function will cross verify the input data parameters. This security
   parameter struct contains all the keys necessary to perform encryption/decryption
   and HMAC operations.                                                                */
RC CR_insert_tls_key(BYTE *trans_id, INT32 key_struct_address) ;

/* Inserts an ipsec_key into the device SA memory. If crypto_code in the
 * device is set or NULL then the key is inserted as an ESP packet. If
 * crypto_code is set to CR_AUTHENTICATE_OP then the key is inserted as
 * an AH packet.
 */
RC CR_insert_ipsec_key( BYTE* trans_id, INT32 key_struct_address ) ;

/* The following function will be used for inserting the PRF keys in the library.
   The key_struct_address is the address of the structure prf_key */
RC CR_insert_prf_key(BYTE *trans_id, INT32 key_struct_address) ;

/* The following function is used to delete a key from the system. */
RC CR_delete_key(BYTE *trans_id) ; 

/**************************************************************************
                         Administrative Functions 
***************************************************************************/

/* The following function will return the version number of the CR702X
   library.
   Returns the library version number in lib_ver buffer. Make sure at least
   20 bytes are allocated for this buffer. */
RC CR_get_libver(BYTE *lib_ver) ;

/* This function will initialize the entire software library. This means
   cleaning all the on-going operations, deleting all stored data, freeing
   all allocated memory, and insering intial data (as required). This function
   also contains (optional) error and warning file pointers. If these are NULL,
   then the function will create the files identified in this header file  */
RC CR_init_lib(FILE *error_file, FILE *warning_file) ;

/* This function will be called to close all existing devices that the
   library is using. In addition, all unused data structures. */
RC CR_close_lib(void) ;

/* This function will set the endian-ness of the library to BIG, LITTLE, or
   NETWORK endian order.  This means that the library will accept/interpret
   data from the application in the order that is set by this function. By
   default, the library is set to BIG endian.   */
void CR_set_endian(CR_ENDIAN endian) ;

/* The following function is used for testing the random number generator. The 
   randomizer runs the FIPS tests on a sample of random data, which is generated
   internally, and returns a SUCCESS if the random data passed the FIPS test, 
   and FAILURE, otherwise.        */
RC CR_test_random(void) ;

/* This function will be used for resetting the various sub-components
   of the device driver.                                             */
RC CR_init_random(void) ;

/* The following function deletes all on-going transactions in the library,
   and resets the transaction related data structures */
RC CR_init_transaction(void) ;

/* The following function will fill the stats table in the library,
   and add the key names to the table.  This function will be called a single
   time, as part of the library initialization. The stat table will be updated
   by the CR_get_stat() function.
*/
RC CR_init_stat(void) ;
 
/* The following function is used for capturing the stats from the
   driver, and returning the data to the calling application. The
   library allocated static memory structure (stat table) at init time (in
   the function CR_init_stat()), which is cleaned up when program ends.
   Input:  None
   Output: cr_stat_table: Pointer to the stat table in library memory.
                          Returns NULL pointer on FAILURE.
*/
cr_stat_table *CR_get_stat(void) ;

/* The following function is used for obtaining device information from
   the driver.
   Input:  None
   Output: cr_device_info: Pointer to the device info structure in library.
                           memory. 
                           Returns NULL pointer on FAILURE.
*/
cr_device_info *CR_get_device_info(void) ;

/* The following function is used to perform a selftest on the CR7020/CR7120
   device.
   Input:  None
   Output: SUCCESS if selftest passed or FAILURE, otherwise.
*/
RC CR_perform_selftest( void );

/***************************************************************************
                               END OF APIs 
***************************************************************************/


#ifdef __cplusplus
}
#endif

#endif