RSA BSAFE Crypto-C

Cryptographic Components for C

Search

bsafe.h File Reference

This file lists the functions, structures and types used in Crypto-C.

#include "bsfmacro.h"
#include "bsfplatf.h"
#include "aglobal.h"
#include "atypes.h"
#include "bexterr.h"
#include "stdlibrf.h"

Go to the source code of this file.

Data Structures

struct  A_PKCS_OAEP_PARAMS
 This structure holds the information for PKCS V2 OAEP algorithm. More...

struct  B_BLK_CIPHER_W_FEEDBACK_PARAMS
 This structure holds the parameters that specify a block cipher with feedback. More...

struct  B_BSAFE1_ENCRYPTION_PARAMS
 This structure holds the BSAFE encryption type. More...

struct  B_CFB_PARAMS
 This structure holds the CFB parameters. More...

struct  B_DIGEST_SPECIFIER
 This structure holds the information on how a digest algorithm is specified in a signature scheme. More...

struct  B_DSA_PARAM_GEN_PARAMS
 This structure holds the information for DSA parameter generation. More...

struct  B_EC_PARAM_GEN_PARAMS
 This structure holds the information for EC parameter generation. More...

struct  B_EC_PARAMS
 This structure holds an EC parameter name and value. More...

struct  B_EC_PRIVATE_KEY_SPECIAL_CURVE
 This structure holds the private key information for EC defined curve. More...

struct  B_EC_PUBLIC_KEY_SPECIAL_CURVE
 This structure holds the public key information for EC defined curve. More...

struct  B_EC_SPECIAL_CURVE
 This structure holds the EC defined curve data. More...

struct  B_KEY_ATTRIBUTES
 This structure holds the key attributes information. More...

struct  B_KEYPAIR_GEN_PARAMS
 This structure holds the parameters for key pair generation. More...

struct  B_MAC_PARAMS
 This structure holds the information for the MAC lgorithm. More...

struct  B_MGF1_PARAMS
 This structure holds the MGF parameters. More...

struct  B_PBE_PARAMS
 This structure holds the PBE parameters. More...

struct  B_PKCS11_SESSION
 This structure holds the information to set up a chooser for use with a PKCS #11 device when the caller wants to use a pre-established session. More...

struct  B_PKCS5_V2_PBE_PARAMS
 This structure holds the PBE parameters for PKCS #5, v.2. More...

struct  B_PKCS5_V2_PBMAC_PARAMS
 This structure holds the MAC parameters for PKCS #5, v.2. More...

struct  B_PKCS_RSA_PSS_PARAMS
 This structure holds the PKCS RSA PSS parameters. More...

struct  B_RC2_BSAFE1_PARAMS_KEY
 This structure holds the RC2 BSAFE1 parameters key. More...

struct  B_RC2_PBE_PARAMS
 This structure holds the PBE parameters for the RC2 algorithm. More...

struct  B_RC4_WITH_MAC_PARAMS
 This structure holds the information for RC4 with MAC algorithm. More...

struct  B_SECRET_SHARING_PARAMS
 This structure holds the information for a secret sharing algorithm. More...

struct  B_SIGN_VERIFY_PARAMS
 This structure holds the parameters used to specify signing or verifying. More...

struct  B_SSLC_KEY_WRAP_PARAMS
 This structure holds the key wrapping parameters for RSA BSAFE SSL-C, (RSA Security's C-language SSL SDK). More...

struct  B_TOKEN_KEYPAIR_GEN_INFO
 This structure holds the information that specifies key pair tokens at generation time. More...

struct  KI_EXTENDED_TOKEN_INFO
 This structure holds the extended information contained in key token types. More...

struct  KI_KEYPAIR_TOKEN_INFO
 This structure holds key pair attribute information contained in key token types. More...

struct  KI_TOKEN_INFO
 This structure holds the information contained in key token types. More...


Defines

#define BE_ALGORITHM_ALREADY_SET
 Indicates that the value of the algorithm object has already been set by a call to B_SetAlgorithmInfo() or by algorithm parameter generation.

#define BE_ALGORITHM_INFO
 Indicates that there is an invalid format for the AI in the algorithm object.

#define BE_ALGORITHM_NOT_INITIALIZED
 Indicates that the algorithm object has not been initialized by a call to the initialization procedure.

#define BE_ALGORITHM_NOT_SET
 Indicates that the algorithm object has not been set by a call to B_SetAlgorithmInfo().

#define BE_ALGORITHM_OBJ
 Indicates an invalid algorithm object.

#define BE_ALG_OPERATION_UNKNOWN
 Indicates an unknown operation for an algorithm or AI.

#define BE_ALLOC
 Indicates that there is insufficient memory for the operation.

#define BE_CANCEL
 Indicates that the operation was canceled by the surrender function.

#define BE_DATA
 Indicates a generic data error.

#define BE_EXPONENT_EVEN
 Indicates an invalid even value for the public exponent in key pair generation.

#define BE_EXPONENT_LEN
 Indicates an invalid exponent length for the public exponent in key pair generation.

#define BE_HARDWARE
 Indicates a cryptographic hardware error.

#define BE_INPUT_DATA
 Indicates an invalid encoding format for input data.

#define BE_INPUT_LEN
 Indicates an invalid total length for input data.

#define BE_KEY_ALREADY_SET
 Indicates that the value of the key object has already been set by a call to B_SetKeyInfo() or by key generation.

#define BE_KEY_INFO
 Indicates an invalid format for the KI in the key object.

#define BE_KEY_LEN
 Indicates an invalid key length.

#define BE_KEY_NOT_SET
 Indicates that the key object has not been set by a call to B_SetKeyInfo() or by key generation.

#define BE_KEY_OBJ
 Indicates an invalid key object.

#define BE_KEY_OPERATION_UNKNOWN
 Indicates an unknown operation for a KI.

#define BE_MEMORY_OBJ
 Indicates an invalid internal memory object.

#define BE_MODULUS_LEN
 Indicates an unsupported modulus length for a key or algorithm parameters.

#define BE_NOT_INITIALIZED
 Indicates that the algorithm is not properly initialized.

#define BE_NOT_SUPPORTED
 Indicates that the algorithm chooser does not support the KI in the key object for the specified algorithm.

#define BE_OUTPUT_LEN
 Indicates that the maximum size of the output buffer is too small to receive the output.

#define BE_OVER_32K
 Indicates that the data block exceeds 32,767 Bytes.

#define BE_RANDOM_NOT_INITIALIZED
 Indicates that the random algorithm has not been initialized by a call to B_RandomInit().

#define BE_RANDOM_OBJ
 Indicates an invalid algorithm object for the random algorithm.

#define BE_SIGNATURE
 Indicates that the signature does not verify.

#define BE_WRONG_ALGORITHM_INFO
 Indicates that the required AI is not in the algorithm object.

#define BE_WRONG_KEY_INFO
 Indicates that the required KI is not in the key object.

#define BE_INPUT_COUNT
 Indicates that update was called an invalid number of times for inputting data.

#define BE_OUTPUT_COUNT
 Indicates that update was called an invalid number of times for outputting data.

#define BE_METHOD_NOT_IN_CHOOSER
 Indicates that the algorithm chooser does not contain the AM for the algorithm specified by the previous call to B_SetAlgorithmInfo().

#define BE_KEY_WEAK
 Indicates that the key data supplied generates a known weak key.

#define BE_EXPONENT_ONE
 Indicates that the value of the public exponent cannot be 1.

#define BE_BAD_POINTER
 Indicates an invalid pointer.

#define BE_BAD_PASSPHRASE
 Indicates an invalid password.

#define BE_AM_DOMESTIC_ONLY
 Indicates that an attempt was made to call an unavailable function in the export version of Crypto-C.

#define BE_BAD_SEEDING
 Indicates that bad seeding was passed to AI_X931Random.

#define BE_BER_HAS_NO_OID
 Indicates that the given encoding contains no OID for B_DecodeAlgorithmBER().

#define BE_BER_OID_NOT_IN_LIST
 Indicates that the given encoding contains an OID unknown to Crypto-C for B_DecodeAlgorithmBER().

#define BE_BER_FIELDS_TOO_LONG
 Indicates that when decoding a BER-encoding the length of an element is described by more than 4 Bytes (4,294,967,295 Bytes) and is too long for Crypto-C to handle.

#define BE_HASH_DF_BAD_REQUEST
 Indicates too many bits requested from Hash_DF.

#define BE_EC_RAND_CURVE
 Indicates no curve available for requested strength.

#define BE_RAND_ENTROPY
 Indicates entropy failure for random generator.

#define BE_RAND_RESEED
 Reseed interval reached, DBRG can no longer be used. More...

#define BE_RAND_NOSELFTEST
 Indicates missing selftest vectors for the random generator selftests.

#define BE_RAND_SELFTEST_FAILED
 Indicates a selftest failure for the random generator.

#define PKCS_RSA_PSS_NO_HASH_ID
 Flag to use for tfOption.

#define PKCS_RSA_PSS_WITH_HASH_ID
 Flag to use for tfOption.


Functions

int B_EncodeDigestInfo (unsigned char *, unsigned int *, unsigned int, ITEM *, unsigned char *, unsigned int)
 Encodes the DER encoding of a PKCS #1 digest information type. More...

int B_DecodeDigestInfo (ITEM *, ITEM *, unsigned char *, unsigned int)
 Decodes the BER encoding of a PKCS #1 digest information type that is given by digestInfo of length digestInfoLen. More...

int B_BuildTableInit (B_ALGORITHM_OBJ, B_ALGORITHM_CHOOSER, A_SURRENDER_CTX *)
 Initializes a table-building object used to build acceleration tables for elliptic curve cryptography. More...

int B_BuildTableGetBufSize (B_ALGORITHM_OBJ, unsigned int *)
 Sets bufSiz to the buffer size needed to accommodate the generated table. More...

int B_BuildTableFinal (B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int, A_SURRENDER_CTX *)
 Generates and outputs the acceleration table to statsBuf and sets lengthOfStats to the number of Bytes output. More...

int B_DecodeAlgorithmBER (unsigned char *encoding, unsigned int len, unsigned int *algorithmFlag)
 Accepts the BER-encoding of an AI or KI, and, if successful, sets algorithmFlag. More...

int B_CreateKeyObject (B_KEY_OBJ *)
 Allocates and initializes a new key object and stores the result in keyObject. More...

void B_DestroyKeyObject (B_KEY_OBJ *)
 Destroys keyObject, resets any sensitive information, frees the memory the key object occupied, and sets keyObject to (B_KEY_OBJ)NULL_PTR. More...

int B_SetKeyInfo (B_KEY_OBJ, B_INFO_TYPE, POINTER)
 Sets the value of keyObject to the information pointed to by info. More...

void B_GetKeyExtendedErrorInfo (B_KEY_OBJ, ITEM *, POINTER *)
 Sets errorDataItem->data to point at the error data, and errorDataItem->len to the length in Bytes of the error data. More...

int B_GetKeyInfo (POINTER *, B_KEY_OBJ, B_INFO_TYPE)
 Retrieves the information held by keyObject in the format specified by infoType, and stores the result in info. More...

int B_WrapKeyInit (B_ALGORITHM_OBJ, B_KEY_OBJ, B_ALGORITHM_CHOOSER, A_SURRENDER_CTX *)
 Initializes a key wrapping operation using the algorithm specified by a previous call to B_SetAlgorithmInfo(). More...

int B_WrapKey (B_ALGORITHM_OBJ algorithmObject, unsigned char *wrappedKey, unsigned int *wrappedKeyLen, unsigned int maxOutLen, B_KEY_OBJ keyToWrap, B_KEY_CHOOSER keyChooser, B_ALGORITHM_OBJ randomAlgorithm, A_SURRENDER_CTX *surrenderContext)
 Encrypts the key data in keyToWrap. More...

int B_UnwrapKeyInit (B_ALGORITHM_OBJ, B_KEY_OBJ, B_ALGORITHM_CHOOSER, A_SURRENDER_CTX *)
 Initializes an algorithm object for a key unwrapping operation using the algorithm specified by a previous call to B_SetAlgorithmInfo(). More...

int B_UnwrapKey (B_ALGORITHM_OBJ algorithmObject, B_KEY_OBJ unwrappedKey, unsigned char *wrappedKey, unsigned int wrappedKeyLen, B_KEY_CHOOSER keyChooser, B_ALGORITHM_OBJ randomAlgorithm, A_SURRENDER_CTX *surrenderContext)
 Decrypts the key data in wrappedKey and sets unwrappedKey to the appropriate KI based on keyChooser. More...

int B_CreateAlgorithmObject (B_ALGORITHM_OBJ *)
 Allocates and initializes a new algorithm object and stores the result in algorithmObject. More...

void B_DestroyAlgorithmObject (B_ALGORITHM_OBJ *)
 Destroys algorithmObject and resets any sensitive information. More...

int B_SetAlgorithmInfo (B_ALGORITHM_OBJ, B_INFO_TYPE, POINTER)
 Sets the parameters of algorithmObject to the information pointed to by info. More...

int B_GetAlgorithmInfo (POINTER *, B_ALGORITHM_OBJ, B_INFO_TYPE)
 Retrieves the information held by algorithmObject in the format specified by infoType, and stores the result in info. More...

int B_GetAlgorithmState (ITEM *, B_ALGORITHM_OBJ)
 Saves the current operating state of an algorithm object for reuse at a later time. More...

int B_SetAlgorithmState (B_ALGORITHM_OBJ, B_INFO_TYPE, ITEM *, B_ALGORITHM_CHOOSER)
 Restores the algorithmObject to the previous state as contained in algState. More...

void B_GetExtendedErrorInfo (B_ALGORITHM_OBJ, ITEM *, POINTER *)
 Sets errorDataItem->data to point at the error data, and errorDataItem->len to point at the length in Bytes of the error data. More...

unsigned int B_IntegerBits (unsigned char *, unsigned int)
 Determines the key size in bits of an RSA key by passing in the modulus. More...

int B_RandomInit (B_ALGORITHM_OBJ, B_ALGORITHM_CHOOSER, A_SURRENDER_CTX *)
 Initializes algorithmObject to generate random Bytes using the algorithm specified by a previous call to B_SetAlgorithmInfo(). More...

int B_GenerateRandomBytes (B_ALGORITHM_OBJ, unsigned char *, unsigned int, A_SURRENDER_CTX *)
 Generates outputLen pseudo-random Bytes from algorithmObject, and stores the result in output. More...

int B_RandomUpdate (B_ALGORITHM_OBJ, unsigned char *, unsigned int, A_SURRENDER_CTX *)
 Mixes inputLen Bytes from input into algorithmObject. More...

int B_DigestInit (B_ALGORITHM_OBJ, B_KEY_OBJ, B_ALGORITHM_CHOOSER, A_SURRENDER_CTX *)
 Initializes algorithmObject to compute a message digest using the algorithm specified by a previous call to B_SetAlgorithmInfo(). More...

int B_DigestUpdate (B_ALGORITHM_OBJ, unsigned char *, unsigned int, A_SURRENDER_CTX *)
 Updates algorithmObject with partInLen Bytes from partIn. More...

int B_DigestFinal (B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int, A_SURRENDER_CTX *)
 Finalizes the digest process for algorithmObject. More...

int B_EncryptInit (B_ALGORITHM_OBJ, B_KEY_OBJ, B_ALGORITHM_CHOOSER, A_SURRENDER_CTX *)
 Initializes algorithmObject for encrypting data using the algorithm specified by a previous call to B_SetAlgorithmInfo(). More...

int B_EncryptUpdate (B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int, unsigned char *, unsigned int, B_ALGORITHM_OBJ, A_SURRENDER_CTX *)
 Updates the encryption process specified by algorithmObject with partInLen Bytes from partIn. More...

int B_EncryptFinal (B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int, B_ALGORITHM_OBJ, A_SURRENDER_CTX *)
 Finalizes the encryption process specified by algorithmObject. More...

int B_DecryptInit (B_ALGORITHM_OBJ, B_KEY_OBJ, B_ALGORITHM_CHOOSER, A_SURRENDER_CTX *)
 Initializes algorithmObject for decrypting data using the algorithm specified by a previous call to B_SetAlgorithmInfo(). More...

int B_DecryptUpdate (B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int, unsigned char *, unsigned int, B_ALGORITHM_OBJ, A_SURRENDER_CTX *)
 Updates the decryption process specified by algorithmObject with partInLen Bytes from partIn. More...

int B_DecryptFinal (B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int, B_ALGORITHM_OBJ, A_SURRENDER_CTX *)
 Finalizes the decryption process specified by algorithmObject. More...

int B_EncodeInit (B_ALGORITHM_OBJ)
 Initializes algorithmObject for encoding data using the algorithm specified by a previous call to B_SetAlgorithmInfo(). More...

int B_EncodeUpdate (B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int, unsigned char *, unsigned int)
 Updates the encoding process specified by algorithmObject with partInLen Bytes from partIn. More...

int B_EncodeFinal (B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int)
 Finalizes the encoding process specified by algorithmObject. More...

int B_DecodeInit (B_ALGORITHM_OBJ)
 Allocates and initializes algorithmObject for decoding (not decrypting) data using the algorithm specified by a previous call to B_SetAlgorithmInfo(). More...

int B_DecodeUpdate (B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int, unsigned char *, unsigned int)
 Updates the decoding process specified by algorithmObject with partInLen Bytes from partIn. More...

int B_DecodeFinal (B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int)
 Finalizes the decoding process specified by algorithmObject. More...

int B_SignInit (B_ALGORITHM_OBJ, B_KEY_OBJ, B_ALGORITHM_CHOOSER, A_SURRENDER_CTX *)
 Initializes the algorithm object for computing a digital signature using the algorithm specified by a previous call to B_SetAlgorithmInfo(). More...

int B_SignUpdate (B_ALGORITHM_OBJ, unsigned char *, unsigned int, A_SURRENDER_CTX *)
 Updates the digest process for algorithmObject with partInLen Bytes from partIn. More...

int B_SignFinal (B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int, B_ALGORITHM_OBJ, A_SURRENDER_CTX *)
 Finalizes the digest process and computes the digital signature. More...

int B_VerifyInit (B_ALGORITHM_OBJ, B_KEY_OBJ, B_ALGORITHM_CHOOSER, A_SURRENDER_CTX *)
 Initializes the algorithm object for digital signature verification using the algorithm specified by a previous call to B_SetAlgorithmInfo(). More...

int B_VerifyUpdate (B_ALGORITHM_OBJ, unsigned char *, unsigned int, A_SURRENDER_CTX *)
 Updates the digest process for algorithmObject with partInLen Bytes from partIn. More...

int B_VerifyFinal (B_ALGORITHM_OBJ, unsigned char *, unsigned int, B_ALGORITHM_OBJ, A_SURRENDER_CTX *)
 Finalizes the digest process and verifies the digital signature supplied by signature of signatureLen Bytes. More...

int B_KeyAgreeInit (B_ALGORITHM_OBJ, B_KEY_OBJ, B_ALGORITHM_CHOOSER, A_SURRENDER_CTX *)
 Initializes the algorithm object to perform key agreement using the algorithm specified by a previous call to B_SetAlgorithmInfo(). More...

int B_KeyAgreePhase1 (B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int, B_ALGORITHM_OBJ, A_SURRENDER_CTX *)
 Generates the initial value for the other party in a key agreement operation. More...

int B_KeyAgreePhase2 (B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int, unsigned char *, unsigned int, A_SURRENDER_CTX *)
 Performs a round of key agreement as specified by algorithmObject, receiving inputLen Bytes from input, which is the other party's intermediate value. More...

int B_GenerateInit (B_ALGORITHM_OBJ, B_ALGORITHM_CHOOSER, A_SURRENDER_CTX *)
 Initializes Crypto-C's parameter generation algorithms such as B_GenerateKeypair() and B_GenerateParameters(). More...

int B_GenerateParameters (B_ALGORITHM_OBJ, B_ALGORITHM_OBJ, B_ALGORITHM_OBJ, A_SURRENDER_CTX *)
 Uses algorithmObject to generate algorithm parameters, and sets resultAlgorithmObject to the result. More...

int B_GenerateKeypair (B_ALGORITHM_OBJ, B_KEY_OBJ, B_KEY_OBJ, B_ALGORITHM_OBJ, A_SURRENDER_CTX *)
 Uses algorithmObject to generate a key pair, and sets publicKey and privateKey to the result. More...

int B_SymmetricKeyGenerateInit (B_ALGORITHM_OBJ, B_ALGORITHM_CHOOSER, A_SURRENDER_CTX *)
 Initializes a key generation object. More...

int B_SymmetricKeyGenerate (B_ALGORITHM_OBJ, B_KEY_OBJ, B_ALGORITHM_OBJ, A_SURRENDER_CTX *)
 Creates a symmetric key in accordance with data specified by a previous call to B_SetAlgorithmInfo(). More...

int B_CreateSessionChooser (B_ALGORITHM_CHOOSER, B_ALGORITHM_CHOOSER *, POINTER *, ITEM *, POINTER *, unsigned char ***)
 Replicates the fixed chooser and makes private copies of the AM structures. More...

int B_FreeSessionChooser (B_ALGORITHM_CHOOSER *, unsigned char ***)
 Frees the memory allocated in the process of creating sessionChooser and oemTagList. More...

int B_CreateHardwareChooser (B_ALGORITHM_CHOOSER currentChooser, B_ALGORITHM_CHOOSER *newChooser, B_ALGORITHM_CHOOSER swReplacements, B_INFO_TYPE hwInfoType, POINTER info)
 Creates a new algorithm chooser from an existing chooser. More...

void B_DestroyHardwareChooser (B_ALGORITHM_CHOOSER *chooser)
 Destroys the hwChooser, resets any sensitive information and frees allocated memory. More...

int B_GetDevice (ITEM *device, B_ALGORITHM_OBJ algorithmObject)
 Retrieves a description of the device that will be used by algorithmObject to perform the operation. More...

Function Documentation

int B_BuildTableFinal (  B_ALGORITHM_OBJ    algorithmObject,
unsigned char *    statsBuf,
unsigned int *    lengthOfStats,
unsigned int    sizeOfStatBuf,
A_SURRENDER_CTX *    surrenderContext
)  ;
 

Generates and outputs the acceleration table to statsBuf and sets lengthOfStats to the number of Bytes output.

Parameters:
algorithmObject [In] The table-building object.
statsBuf [Out] The acceleration table buffer.
lengthOfStats [Out] The size of the created acceleration table in Bytes.
sizeOfStatBuf [Out] The size of the acceleration table buffer.
surrenderContext [In] The surrender context.
Returns:
0 indicates success.
BE_OUTPUT_LEN indicates sizeOfStatBuf is smaller than required.
Samples:
ecutil.c.

int B_BuildTableGetBufSize (  B_ALGORITHM_OBJ    algorithmObject,
unsigned int *    bufSize
)  ;
 

Sets bufSiz to the buffer size needed to accommodate the generated table.

Parameters:
algorithmObject [In] The table-building object.
bufSize [Out] The size of the table in Bytes.
Returns:
0 indicates success.
See Error Identifiers for valid values.
Samples:
ecutil.c.

int B_BuildTableInit (  B_ALGORITHM_OBJ    algorithmObject,
B_ALGORITHM_CHOOSER    algorithmChooser,
A_SURRENDER_CTX *    surrenderContext
)  ;
 

Initializes a table-building object used to build acceleration tables for elliptic curve cryptography.

Parameters:
algorithmObject [In] The table-building object.
algorithmChooser [In] The algorithm chooser.
surrenderContext [In] The surrender context.
Returns:
0 indicates success.
See Error Identifiers for valid values.
Samples:
ecutil.c.

int B_CreateAlgorithmObject (  B_ALGORITHM_OBJ *    algorithmObject )  ;
 

Allocates and initializes a new algorithm object and stores the result in algorithmObject. If the operation is unsuccessful, no memory is allocated and algorithmObject is set to (B_ALGORITHM_OBJ)NULL_PTR.

Parameters:
algorithmObject [Out] The new algorithm object.
Returns:
0 indicates success.
See Error Identifiers for valid values.
Samples:
aes.c, aesfb.c, alginfo.c, b64.c, berder.c, bslec.c, bslite.c, bsliteds.c, descbc.c, dhagree.c, dhagrsv.c, dhparam.c, dintroex.c, dsasign.c, ecdh.c, ecdsa.c, ecdsadig.c, eces.c, ecrand.c, ecspecial.c, ecutil.c, encdec.c, entrpycb.c, feedback.c, genbytes.c, hmac.c, intelrnd.c, introex.c, keywrap.c, mdber.c, mdigest.c, mdigsv.c, multdecr.c, multencr.c, p11dsakeygen.c, p11dsasign.c, p11rsaencrypt.c, p11rsakeygen.c, p11rsasign.c, parsepkcs5.c, pbe.c, pbkdf2.c, pkcs12pbe.c, pkcs5v2pbe.c, rc2.c, rc2ecb.c, rc4.c, rc4sv.c, rc5.c, rc5ofb.c, rsaoaep.c, rsapkcs.c, rsapkcs2.c, rsapss.c, rsasign.c, rsasign2.c, rsautil.c, scrtshar.c, seed.c, seedfb.c, setoaep.c, sha512.c, tdescfb.c, x931.c, x931rand.c, and x962.c.

int B_CreateHardwareChooser (  B_ALGORITHM_CHOOSER    currentChooser,
B_ALGORITHM_CHOOSER *    newChooser,
B_ALGORITHM_CHOOSER    swReplacements,
B_INFO_TYPE    hwInfoType,
POINTER    info
)  ;
 

Creates a new algorithm chooser from an existing chooser. Uses hwInfoType to determine which of the AMs in the currentChooser are to be supplemented with hardware functionality, and then uses this information to create a new AM. Finally, the function creates a new chooser that contains all the AMs in currentChooser plus any new AMs.

If the user passes in swReplacements, and the function is unable to create the hardware versions of the methods, the software versions will be used instead. The new chooser is located at the address specified by newChooser.

Parameters:
currentChooser [In] The chooser to replace.
newChooser [Out] The resulting new chooser.
swReplacements [In] The AMs to use if a hardware AM cannot be created.
hwInfoType [In] The HI specifying the hardware device.
info [In] The HI-specific information.
Returns:
0 indicates success.
See Error Identifiers for valid values.
Samples:
p11dsasign.c.

int B_CreateKeyObject (  B_KEY_OBJ *    keyObject )  ;
 

Allocates and initializes a new key object and stores the result in keyObject. If this function is unsuccessful, no memory is allocated and keyObject is set to (B_KEY_OBJ)NULL_PTR.

Parameters:
keyObject [Out] The new key object.
Returns:
0 indicates success.
See Error Identifiers for valid values.
Samples:
aes.c, aesfb.c, alginfo.c, berder.c, bslec.c, bslite.c, bsliteds.c, descbc.c, dintroex.c, dsasign.c, ecspecial.c, ecutil.c, feedback.c, hmac.c, introex.c, keywrap.c, multdecr.c, multencr.c, p11dsakeygen.c, p11dsasign.c, p11rsaencrypt.c, p11rsakeygen.c, p11rsasign.c, parsepkcs5.c, pbe.c, pbkdf2.c, pkcs5v2pbe.c, rc2.c, rc2ecb.c, rc4.c, rc4sv.c, rc5.c, rc5ofb.c, rsautil.c, seed.c, seedfb.c, tdescfb.c, and x931.c.

int B_CreateSessionChooser (  B_ALGORITHM_CHOOSER    fixedChooser,
B_ALGORITHM_CHOOSER *    sessionChooser,
POINTER *    staticHardwareList,
ITEM *    passPhrase,
POINTER *    amTagList,
unsigned char ***    listOfOEMTags
)  ;
 

Replicates the fixed chooser and makes private copies of the AM structures. Whenever possible the software-based methods are replaced with the hardware-based methods defined either statically by staticHardwareList, or dynamically by platform-specific routines.

All methods in the fixedChooser are represented in the sessionChooser and will appear multiple times if there are multiple hardware substitutes available.

Parameters:
fixedChooser [In] The chooser consisting of software-based AMs.
sessionChooser [Out] The runtime chooser dynamically bound to available hardware-based methods.
staticHardwareList [In] The list of statically defined hardware methods terminated by a properly cast NULL_PTR.
passPhrase [In] The hardware passphrase.
amTagList [In] The address list of hardware AMs.
Pass (*)NULL_PTR.
listOfOEMTags [Out] Returns list of OEM tags for methods in sessionChooser.
Returns:
0 indicates success.
See Error Identifiers for valid values.
note.gif
It is simple to limit the binding of hardware methods to exclusively static or dynamically defined entries. The AM structures that constitute sessionChooser are B_METHOD structures extended to include an information pointer and a finalization function to destroy it.
Samples:
intelrnd.c.

int B_DecodeAlgorithmBER (  unsigned char *    encoding,
unsigned int    len,
unsigned int *    algorithmFlag
)  ;
 

Accepts the BER-encoding of an AI or KI, and, if successful, sets algorithmFlag. If the encoding is not recognized by this subroutine, it will set algorithmFlag to UNKNOWN_ENCODING.

Parameters:
encoding [In] The encoding AI or KI.
len [In] The length of the identifier.
algorithmFlag [Out] The flag.
Returns:
0 indicates success.
BE_BER_HAS_NO_OID indicates that no OID was found in the caller's BER octets.
BE_BER_OID_NOT_IN_LIST indicates that an unsupported OID was found.
BE_BER_FIELDS_TOO_LONG indicates that the caller's BER-encoding contained indefinite length or extremely long (>232 Bytes) fields.
note.gif
There are two valid AIs for ALGORITHM_RSA_PKCS_ENCRYPTION:
AI_PKCS_RSAPublicBER and AI_PKCS_RSAPrivateBER. The AI for RSA public encryption (creating a digital envelope) and RSA private decryption (opening a digital envelope) is the same. The same is true for ALGORITHM_RSA_OAEP_ENCRYPTION, another form of digital envelope.
See Algorithm Flags for a list of algorithm flags and corresponding AIs and KIs.
Example:

/*Assume that BERinfo contains some BER encoded key or algorithm data*/
ITEM *BERinfo;
int keyflag;

if ((status = B_DecodeAlgorithmBER (BERinfo->data, BERinfo->len,
                                    &keyFlag)) != 0)
      break;
Samples:
alginfo.c.

int B_DecodeDigestInfo (  ITEM *    algorithmID,
ITEM *    digest,
unsigned char *    digestInfo,
unsigned int    digestInfoLen
)  ;
 

Decodes the BER encoding of a PKCS #1 digest information type that is given by digestInfo of length digestInfoLen. On output, the algorithmID ITEM indicates the digest AI and the digest ITEM indicates the digest value. The ITEM type is defined by KI_Item.

Parameters:
algorithmID [Out] The message digest AI.
digest [Out] The message digest value.
digestInfo [In] The digest information encoding.
digestInfoLen [In] The length of digestInfo.
Returns:
0 indicates success.
See Error Identifiers for valid values.
Samples:
mdber.c.

int B_DecodeFinal (  B_ALGORITHM_OBJ    algorithmObject,
unsigned char *    partOut,
unsigned int *    partOutLen,
unsigned int    maxPartOutLen
)  ;
 

Finalizes the decoding process specified by algorithmObject. Writes any remaining decoded output to partOut, which is a buffer supplied by the caller of at least maxPartOutLen Bytes. Sets partOutLen to the number of Bytes written to partOut. algorithmObject is reset to the state it was in after the call to B_DecodeInit() in order to perform another decoding operation.

Parameters:
algorithmObject [In] The algorithm object.
partOut [Out] The output data buffer.
partOutLen [Out] The length of output data.
maxPartOutLen [In, Out] The size of output data buffer.
Returns:
0 indicates success.
See Error Identifiers for valid values.
See also:
B_DecodeInit() and B_DecodeUpdate().
Samples:
b64.c.

int B_DecodeInit (  B_ALGORITHM_OBJ    algorithmObject )  ;
 

Allocates and initializes algorithmObject for decoding (not decrypting) data using the algorithm specified by a previous call to B_SetAlgorithmInfo(). This function only needs to be called once to set up a decoding algorithm as B_DecodeFinal() completes the operation. There are no cryptographic keys for encoding or decoding.

For example, the AI_RFC1113Recode algorithm provides Base64 encoding and decoding to convert binary data to and from a printable form suitable for most e-mail systems.

Parameters:
algorithmObject [In, Out] The algorithm object.
Returns:
0 indicates success.
See Error Identifiers for valid values.
See also:
B_DecodeUpdate() and B_DecodeFinal().
Samples:
b64.c, and encdec.c.

int B_DecodeUpdate (  B_ALGORITHM_OBJ    algorithmObject,
unsigned char *    partOut,
unsigned int *    partOutLen,
unsigned int    maxPartOutLen,
unsigned char *    partIn,
unsigned int    partInLen
)  ;
 

Updates the decoding process specified by algorithmObject with partInLen Bytes from partIn. Writes the decoded output to partOut, which is a buffer supplied by the caller of at least maxPartOutLen Bytes. Sets partOutLen to the number of Bytes written to partOut. This function may be called zero or more times to supply the data by parts.

Parameters:
algorithmObject [In] The algorithm object.
partOut [Out] The output data buffer.
partOutLen [Out] The length of output data.
maxPartOutLen [In] The size of output data buffer.
partIn [In] The input data.
partInLen [In] The length of input data.
Returns:
0 indicates success.
See Error Identifiers for valid values.
See also:
B_DecodeInit() and B_DecodeFinal().
Samples:
b64.c, and encdec.c.

int B_DecryptFinal (  B_ALGORITHM_OBJ    algorithmObject,
unsigned char *    partOut,
unsigned int *    partOutLen,
unsigned int    maxPartOutLen,
B_ALGORITHM_OBJ    randomAlgorithm,
A_SURRENDER_CTX *    surrenderContext
)  ;
 

Finalizes the decryption process specified by algorithmObject. Writes any remaining decrypted output to partOut, which is a buffer supplied by the caller of at least maxPartOutLen Bytes, and sets partOutLen to the number of Bytes written to partOut.

algorithmObject is reset to the state it was in after the call to B_DecryptInit(), so that another decryption process may be performed.

Parameters:
algorithmObject [In] The algorithm object.
partOut [Out] The output data buffer.
partOutLen [Out] The length of the output data.
maxPartOutLen [In] The size of the output data buffer.
randomAlgorithm [In] The random Byte source.
May be (B_ALGORITHM_OBJ)NULL_PTR for decryption algorithms that do not need random numbers.
surrenderContext [In] The surrender context.
Ignored if the value is (A_SURRENDER_CTX *)NULL_PTR.
Returns:
0 indicates success.
See Error Identifiers for valid values.
See also:
B_DecryptInit() and B_DecryptUpdate().
Samples:
berder.c, descbc.c, dintroex.c, eces.c, ecspecial.c, feedback.c, multdecr.c, p11rsaencrypt.c, pbe.c, pkcs5v2pbe.c, rc2.c, rc2ecb.c, rc4sv.c, rsaoaep.c, rsapkcs.c, rsapkcs2.c, scrtshar.c, setoaep.c, and tdescfb.c.

int B_DecryptInit (  B_ALGORITHM_OBJ    algorithmObject,
B_KEY_OBJ    keyObject,
B_ALGORITHM_CHOOSER    algorithmChooser,
A_SURRENDER_CTX *    surrenderContext
)  ;
 

Initializes algorithmObject for decrypting data using the algorithm specified by a previous call to B_SetAlgorithmInfo().

This function only needs to be called once to set up a key. B_DecryptUpdate() can be called multiple times to process blocks of data, and B_DecryptFinal() is called once to process the last block, which includes removing the trailing pad Bytes. After B_DecryptFinal() is called, B_DecryptUpdate() can be called to start processing another sequence of blocks that were encrypted in the same key.

For example, if a different CBC IV is used with each sequence of blocks, call B_SetAlgorithmInfo() with AI_CBC_IV8 to set the new IV before calling B_DecryptUpdate(). There is no need to call B_DecryptInit() again with the same key.

Parameters:
algorithmObject [In, Out] The algorithm object.
keyObject [In, Out] The key object.
algorithmChooser [In] The algorithm chooser.
surrenderContext [In] The surrender context.
Ignored if the value is (A_SURRENDER_CTX *)NULL_PTR.
Returns:
0 indicates success.
See Error Identifiers for valid values.
See also:
B_DecryptUpdate() and B_DecryptFinal().
Samples:
aes.c, aesfb.c, alginfo.c, berder.c, descbc.c, dintroex.c, eces.c, ecspecial.c, feedback.c, multdecr.c, p11rsaencrypt.c, pbe.c, pkcs5v2pbe.c, rc2.c, rc2ecb.c, rc4.c, rc4sv.c, rc5.c, rc5ofb.c, rsaoaep.c, rsapkcs.c, rsapkcs2.c, scrtshar.c, seed.c, seedfb.c, setoaep.c, and tdescfb.c.

int B_DecryptUpdate (  B_ALGORITHM_OBJ    algorithmObject,
unsigned char *    partOut,
unsigned int *    partOutLen,
unsigned int    maxPartOutLen,
unsigned char *    partIn,
unsigned int    partInLen,
B_ALGORITHM_OBJ    randomAlgorithm,
A_SURRENDER_CTX *    surrenderContext
)  ;
 

Updates the decryption process specified by algorithmObject with partInLen Bytes from partIn. Writes the decrypted output to partOut, which is a buffer supplied by the caller of at least maxPartOutLen Bytes, and sets partOutLen to the number of Bytes written to partOut.

B_DecryptUpdate() may be called zero or more times to supply the data by parts.

Parameters:
algorithmObject [In, Out] The algorithm object.
partOut [Out] The output data buffer.
partOutLen [Out] The length of the output data.
maxPartOutLen [In] The size of the output data buffer.
partIn [In] The input data.
partInLen [In] The length of the input data.
randomAlgorithm [In] The random Byte source.
May be (B_ALGORITHM_OBJ)NULL_PTR for decryption algorithms that do not need random numbers.
surrenderContext [In] The surrender context.
Ignored if the value is (A_SURRENDER_CTX *)NULL_PTR.
Returns:
0 indicates success.
See Error Identifiers for valid values.
See also:
B_DecryptInit() and B_DecryptFinal().
Samples:
berder.c, descbc.c, dintroex.c, eces.c, ecspecial.c, feedback.c, multdecr.c, p11rsaencrypt.c, pbe.c, pkcs5v2pbe.c, rc2.c, rc2ecb.c, rc4sv.c, rsaoaep.c, rsapkcs.c, rsapkcs2.c, scrtshar.c, setoaep.c, and tdescfb.c.

void B_DestroyAlgorithmObject (  B_ALGORITHM_OBJ *    algorithmObject )  ;
 

Destroys algorithmObject and resets any sensitive information. Frees the memory occupied by the algorithm object and sets algorithmObject to (B_ALGORITHM_OBJ)NULL_PTR.

No action is taken if algorithmObject is already set to this value, or if it is not a valid algorithm object.

After this routine is called, all the pointers to information blocks returned by calls to B_GetAlgorithmInfo() are no longer valid as the memory associated with those blocks has been reset and freed.

Parameters:
algorithmObject [In] A pointer to an algorithm object.
See also:
B_CreateAlgorithmObject().
Samples:
aes.c, aesfb.c, alginfo.c, b64.c, berder.c, bslec.c, bslite.c, bsliteds.c, descbc.c, dhagree.c, dhagrsv.c, dhparam.c, dintroex.c, dsasign.c, ecdh.c, ecdsa.c, ecdsadig.c, eces.c, ecparam.c, ecrand.c, ecspecial.c, ecutil.c, encdec.c, entrpycb.c, feedback.c, genbytes.c, hmac.c, intelrnd.c, introex.c, keywrap.c, mdber.c, mdigest.c, mdigsv.c, multdecr.c, multencr.c, p11dsakeygen.c, p11dsasign.c, p11rsaencrypt.c, p11rsakeygen.c, p11rsasign.c, parsepkcs5.c, pbe.c, pbkdf2.c, pkcs12pbe.c, pkcs5v2pbe.c, rc2.c, rc2ecb.c, rc4.c, rc4sv.c, rc5.c, rc5ofb.c, rsaoaep.c, rsapkcs.c, rsapkcs2.c, rsapss.c, rsasign.c, rsasign2.c, rsautil.c, scrtshar.c, seed.c, seedfb.c, setoaep.c, sha512.c, tdescfb.c, x931.c, x931rand.c, and x962.c.

void B_DestroyHardwareChooser (  B_ALGORITHM_CHOOSER *    hwChooser )  ;
 

Destroys the hwChooser, resets any sensitive information and frees allocated memory. The routine will not do anything if the chooser was not created by calling B_CreateHardwareChooser(), or if the value at the given address is NULL_PTR.

Parameters:
hwChooser [In] The created chooser.
Samples:
p11dsakeygen.c, p11dsasign.c, p11rsaencrypt.c, p11rsakeygen.c, and p11rsasign.c.

void B_DestroyKeyObject (  B_KEY_OBJ *    keyObject )  ;
 

Destroys keyObject, resets any sensitive information, frees the memory the key object occupied, and sets keyObject to (B_KEY_OBJ)NULL_PTR. No action is taken if the keyObject is already set to this value, or is not a valid key object.

After this routine is called, all the pointers to information blocks returned by calls to B_GetKeyInfo() are no longer valid as the memory associated with those blocks has been zeroized and freed.

Parameters:
keyObject [In] A pointer to a key object.
See also:
B_CreateKeyObject().
Samples:
aes.c, aesfb.c, alginfo.c, berder.c, bslec.c, bslite.c, bsliteds.c, descbc.c, dintroex.c, dsasign.c, ecdsa.c, ecdsadig.c, eces.c, ecparam.c, ecspecial.c, ecutil.c, feedback.c, hmac.c, introex.c, keywrap.c, multdecr.c, multencr.c, p11dsakeygen.c, p11dsasign.c, p11rsaencrypt.c, p11rsakeygen.c, p11rsasign.c, parsepkcs5.c, pbe.c, pbkdf2.c, pkcs5v2pbe.c, rc2.c, rc2ecb.c, rc4.c, rc4sv.c, rc5.c, rc5ofb.c, rsamultp.c, rsaoaep.c, rsapkcs.c, rsapkcs2.c, rsapss.c, rsasign.c, rsasign2.c, rsautil.c, seed.c, seedfb.c, setoaep.c, tdescfb.c, x931.c, and x962.c.

int B_DigestFinal (  B_ALGORITHM_OBJ    algorithmObject,
unsigned char *    digest,
unsigned int *    digestLen,
unsigned int    maxDigestLen,
A_SURRENDER_CTX *    surrenderContext
)  ;
 

Finalizes the digest process for algorithmObject. Writes the message digest to digest, which is a buffer supplied by the caller of at least maxDigestLen Bytes, and sets digestLen to the length of the digest.

algorithmObject is reset to the state it was in after the call to B_DigestInit(), in order to perform another message digest process.

Parameters:
algorithmObject [In, Out] The algorithm object.
digest [Out] The message digest output buffer.
digestLen [Out] The length of the message digest output.
maxDigestLen [In] The size of the output buffer.
surrenderContext [In] The surrender context.
Ignored if the value is (A_SURRENDER_CTX *)NULL_PTR.
Returns:
0 indicates success.
See Error Identifiers for valid values.
See also:
B_DigestInit() and B_DigestUpdate().
Samples:
hmac.c, mdber.c, mdigest.c, mdigsv.c, pbkdf2.c, pkcs12pbe.c, and sha512.c.

int B_DigestInit (  B_ALGORITHM_OBJ    algorithmObject,
B_KEY_OBJ    keyObject,
B_ALGORITHM_CHOOSER    algorithmChooser,
A_SURRENDER_CTX *    surrenderContext
)  ;
 

Initializes algorithmObject to compute a message digest using the algorithm specified by a previous call to B_SetAlgorithmInfo(). The chooser for selecting the AM is algorithmChooser.

This function only needs to be called once to set up a digest algorithm. B_DigestUpdate() can be called multiple times to process blocks of data, and B_DigestFinal() is called once to process the last block which includes producing the result. After B_DigestFinal() is called, B_DigestUpdate() can be called to start digesting another sequence of blocks. There is no need to call B_DigestInit() again.

Parameters:
algorithmObject [In, Out] The algorithm object.
keyObject [In, Out] The key object.
Enter (B_KEY_OBJ)NULL_PTR for keyless digesting algorithms.
algorithmChooser [In] The algorithm chooser.
surrenderContext [In] The surrender context.
Ignored if the value is (A_SURRENDER_CTX *)NULL_PTR.
Returns:
0 indicates success.
See Error Identifiers for valid values.
See also:
B_DigestUpdate() and B_DigestFinal().
Samples:
hmac.c, mdber.c, mdigest.c, mdigsv.c, pbkdf2.c, pkcs12pbe.c, and sha512.c.

int B_DigestUpdate (  B_ALGORITHM_OBJ    algorithmObject,
unsigned char *    partIn,
unsigned int    partInLen,
A_SURRENDER_CTX *    surrenderContext
)  ;
 

Updates algorithmObject with partInLen Bytes from partIn. This function can be called zero or more times to supply the data by parts.

Parameters:
algorithmObject [In, Out] The algorithm object.
partIn [In] The input data.
partInLen [In] The length of the input data.
surrenderContext [In] The surrender context.
Ignored if the value is (A_SURRENDER_CTX *)NULL_PTR.
Returns:
0 indicates success.
See Error Identifiers for valid values.
See also:
B_DigestInit() and B_DigestFinal().
Samples:
hmac.c, mdber.c, mdigest.c, mdigsv.c, pbkdf2.c, pkcs12pbe.c, and sha512.c.

int B_EncodeDigestInfo (  unsigned char *    digestInfo,
unsigned int *    digestInfoLen,
unsigned int    maxDigestInfoLen,
ITEM *    algorithmID,
unsigned char *    digest,
unsigned int    digestLen
)  ;
 

Encodes the DER encoding of a PKCS #1 digest information type. Writes the encoding to digestInfo, which is a buffer supplied by the caller of at least maxDigestInfoLen Bytes, and sets digestInfoLen to the length of the encoding. algorithmID points to an ITEM that indicates the DER encoding of the message digest algorithm. The ITEM type is defined by the KI_Item KI.
Typically, algorithmID is the value of digestInfo returned by calling B_GetAlgorithmInfo(). digest points to the message digest value of length digestLen. digest is typically returned by B_DigestFinal().

Parameters:
digestInfo [Out] The encoded output buffer.
digestInfoLen [Out] The length of encoded output.
maxDigestInfoLen [In] The size of digestInfo buffer.
algorithmID [In] The message digest AI.
digest [In] The message digest value.
digestLen [In] The length of digest.
Returns:
0 indicates success.
See Error Identifiers for valid values.
Samples:
mdber.c.

int B_EncodeFinal (  B_ALGORITHM_OBJ    algorithmObject,
unsigned char *    partOut,
unsigned int *    partOutLen,
unsigned int    maxPartOutLen
)  ;
 

Finalizes the encoding process specified by algorithmObject. Writes any remaining encoded output to partOut, which is a buffer supplied by the caller of at least maxPartOutLen Bytes. Sets partOutLen to the number of Bytes written to partOut. algorithmObject is reset to the state it was in after the call to B_EncodeInit(), in order to perform another encoding operation.

Parameters:
algorithmObject [in, Out] The algorithm object.
partOut [Out] The output data buffer.
partOutLen [Out] The length of output data.
maxPartOutLen [In] The size of output data buffer.
Returns:
0 indicates success.
See Error Identifiers for valid values.
See also:
B_EncodeInit() and B_EncodeUpdate().

int B_EncodeInit (  B_ALGORITHM_OBJ    algorithmObject )  ;
 

Initializes algorithmObject for encoding data using the algorithm specified by a previous call to B_SetAlgorithmInfo(). This function only needs to be called once to set up an encoding algorithm as B_EncodeFinal() completes the operation. There are no cryptographic keys for encoding or decoding.

For example, the AI_RFC1113Recode algorithm provides Base64 encoding and decoding to convert binary data to and from a printable form suitable for most e-mail systems.

Parameters:
algorithmObject [In, Out] The algorithm object.
Returns:
0 indicates success.
See Error Identifiers for valid values.
See also:
B_EncodeUpdate() and B_EncodeFinal().
Samples:
b64.c, and encdec.c.

int B_EncodeUpdate (  B_ALGORITHM_OBJ    algorithmObject,
unsigned char *    partOut,
unsigned int *    partOutLen,
unsigned int    maxPartOutLen,
unsigned char *    partIn,
unsigned int    partInLen
)  ;
 

Updates the encoding process specified by algorithmObject with partInLen Bytes from partIn. Writes the encoded output to partOut, which is a buffer supplied by the caller of at least maxPartOutLen Bytes. Sets partOutLen to the number of Bytes written to partOut. This function may be called zero or more times to supply the data by parts.

Parameters:
algorithmObject [In, Out] The algorithm object.
partOut [Out] The output data buffer.
partOutLen [Out] The length of output data.
maxPartOutLen [Out] The size of output data buffer.
partIn [In] The input data.
partInLen [In] The length of input data.
Returns:
0 indicates success.
See Error Identifiers for valid values.
See also:
B_EncodeInit() and B_EncodeFinal().
Samples:
encdec.c.

int B_EncryptFinal (  B_ALGORITHM_OBJ    algorithmObject,
unsigned char *    partOut,
unsigned int *    partOutLen,
unsigned int    maxPartOutLen,
B_ALGORITHM_OBJ    randomAlgorithm,
A_SURRENDER_CTX *    surrenderContext
)  ;
 

Finalizes the encryption process specified by algorithmObject. Writes any remaining encrypted output to partOut, which is a buffer supplied by the caller of at least maxPartOutLen Bytes, and sets partOutLen to the number of Bytes written to partOut.

algorithmObject is reset to the state it was in after the call to B_EncryptInit() in order to perform another encryption process.

Parameters:
algorithmObject [In, Out] The algorithm object.
partOut [Out] The output data buffer.
partOutLen [Out] The length of the output data.
maxPartOutLen [In] The size of the output data buffer.
randomAlgorithm [In] The random Byte source.
May be (B_ALGORITHM_OBJ)NULL_PTR for encryption algorithms that do not need random numbers.
surrenderContext [In] The surrender context.
Ignored if the value is (A_SURRENDER_CTX *)NULL_PTR.
Returns:
0 indicates success.
See Error Identifiers for valid values.
See also:
B_EncryptInit() and B_EncryptUpdate().
Samples:
berder.c, descbc.c, dintroex.c, eces.c, ecspecial.c, feedback.c, introex.c, multencr.c, p11rsaencrypt.c, parsepkcs5.c, pbe.c, pkcs5v2pbe.c, rc2.c, rc2ecb.c, rsaoaep.c, rsapkcs.c, rsapkcs2.c, scrtshar.c, setoaep.c, and tdescfb.c.

int B_EncryptInit (  B_ALGORITHM_OBJ    algorithmObject,
B_KEY_OBJ    keyObject,
B_ALGORITHM_CHOOSER    algorithmChooser,
A_SURRENDER_CTX *    surrenderContext
)  ;
 

Initializes algorithmObject for encrypting data using the algorithm specified by a previous call to B_SetAlgorithmInfo().

This function only needs to be called once to set up a key. The B_EncryptUpdate() routine can be called multiple times to process blocks of data, and B_EncryptFinal() is called once to process the last block, which includes adding the trailing pad Bytes. After B_EncryptFinal() is called, B_EncryptUpdate() can be called to start processing another sequence of blocks.

If a different CBC IV is used with each sequence of blocks, call B_SetAlgorithmInfo() with AI_CBC_IV8 to set the new IV before calling B_EncryptUpdate(). There is no need to call this function again with the same key.

Parameters:
algorithmObject [In, Out] The algorithm object.
keyObject [In] The key object.
algorithmChooser [In] The algorithm chooser.
surrenderContext [In] The surrender context.
Ignored if the value is (A_SURRENDER_CTX *)NULL_PTR.
Returns:
0 indicates success.
See Error Identifiers for valid values.
See also:
B_EncryptUpdate() and B_EncryptFinal().
Samples:
aes.c, aesfb.c, alginfo.c, berder.c, descbc.c, dintroex.c, eces.c, ecspecial.c, feedback.c, introex.c, multencr.c, p11rsaencrypt.c, parsepkcs5.c, pbe.c, pkcs5v2pbe.c, rc2.c, rc2ecb.c, rc4.c, rc4sv.c, rc5.c, rc5ofb.c, rsaoaep.c, rsapkcs.c, rsapkcs2.c, scrtshar.c, seed.c, seedfb.c, setoaep.c, and tdescfb.c.

int B_EncryptUpdate (  B_ALGORITHM_OBJ    algorithmObject,
unsigned char *    partOut,
unsigned int *    partOutLen,
unsigned int    maxPartOutLen,
unsigned char *    partIn,
unsigned int    partInLen,
B_ALGORITHM_OBJ    randomAlgorithm,
A_SURRENDER_CTX *    surrenderContext
)  ;
 

Updates the encryption process specified by algorithmObject with partInLen Bytes from partIn. Writes the encrypted output to partOut, which is a buffer supplied by the caller of at least maxPartOutLen Bytes, and sets partOutLen to the number of Bytes written to partOut. This function may be called zero or more times to supply the data by parts.

Parameters:
algorithmObject [In, Out] The algorithm object.
partOut [Out] The output data buffer.
partOutLen [Out] The length of the output data.
maxPartOutLen [In] The size of the output data buffer.
partIn [In] The input data.
partInLen [In] The length of the input data.
randomAlgorithm [In] The random Byte source.
May be (B_ALGORITHM_OBJ)NULL_PTR for encryption algorithms that do not need random numbers.
surrenderContext [In] The surrender context.
Ignored if the value is (A_SURRENDER_CTX *)NULL_PTR.
Returns:
0 indicates success.
See Error Identifiers for valid values.
See also:
B_EncryptInit() and B_EncryptFinal().
Samples:
berder.c, descbc.c, dintroex.c, eces.c, ecspecial.c, feedback.c, introex.c, multencr.c, p11rsaencrypt.c, parsepkcs5.c, pbe.c, pkcs5v2pbe.c, rc2.c, rc2ecb.c, rc4sv.c, rsaoaep.c, rsapkcs.c, rsapkcs2.c, scrtshar.c, setoaep.c, and tdescfb.c.

int B_FreeSessionChooser (  B_ALGORITHM_CHOOSER *    sessionChooser,
unsigned char ***    oemTagList
)  ;
 

Frees the memory allocated in the process of creating sessionChooser and oemTagList. Whenever a non-null information pointer from the extended AM is encountered, its corresponding final function is called to destroy it.

Parameters:
sessionChooser [In] The address of the runtime chooser dynamically bound to available hardware-based methods.
oemTagList [In] The address list of the OEM hardware method tags.
Returns:
0 indicates success.
See Error Identifiers for valid values.
Samples:
intelrnd.c.

int B_GenerateInit (  B_ALGORITHM_OBJ    algorithmObject,
B_ALGORITHM_CHOOSER    algorithmChooser,
A_SURRENDER_CTX *    surrenderContext
)  ;
 

Initializes Crypto-C's parameter generation algorithms such as B_GenerateKeypair() and B_GenerateParameters(). Initializes algorithmObject using the algorithm specified by a previous call to B_SetAlgorithmInfo().

Parameters:
algorithmObject [In, Out] The algorithm object.
algorithmChooser [In] The algorithm chooser.
surrenderContext [In] The surrender context.
Ignored if the value is (A_SURRENDER_CTX *)NULL_PTR.
Returns:
0 indicates success.
See Error Identifiers for valid values.
note.gif
Call B_RandomInit() to initialize the generator for B_GenerateRandomBytes().
See also:
B_GenerateKeypair() and B_GenerateParameters.
Samples:
dhparam.c, dsasign.c, ecspecial.c, ecutil.c, p11dsakeygen.c, p11dsasign.c, p11rsakeygen.c, rsautil.c, and x931.c.

int B_GenerateKeypair (  B_ALGORITHM_OBJ    algorithmObject,
B_KEY_OBJ    publicKey,
B_KEY_OBJ    privateKey,
B_ALGORITHM_OBJ    randomAlgorithm,
A_SURRENDER_CTX *    surrenderContext
)  ;
 

Uses algorithmObject to generate a key pair, and sets publicKey and privateKey to the result.

algorithmObject is reset to the state it was in after the call to B_GenerateInit() in order to perform another key pair generation.

Parameters:
algorithmObject [In, Out] The algorithm object.
publicKey [Out] The new public key.
privateKey [Out] The new private key.
randomAlgorithm [In] The random algorithm.
surrenderContext [In] The surrender context.
Ignored if the value is (A_SURRENDER_CTX *)NULL_PTR.
Returns:
0 indicates success.
See Error Identifiers for valid values.
See also:
B_GenerateInit().
Samples:
dsasign.c, ecspecial.c, ecutil.c, p11dsakeygen.c, p11dsasign.c, p11rsakeygen.c, and x931.c.

int B_GenerateParameters (  B_ALGORITHM_OBJ    algorithmObject,
B_ALGORITHM_OBJ    resultAlgorithmObject,
B_ALGORITHM_OBJ    randomAlgorithm,
A_SURRENDER_CTX *    surrenderContext
)  ;
 

Uses algorithmObject to generate algorithm parameters, and sets resultAlgorithmObject to the result. The application may then use B_GetAlgorithmInfo() to retrieve the new parameters from resultAlgorithmObject.

algorithmObject is reset to the state it was in after the call to B_GenerateInit() in order to perform another parameter generation.

Parameters:
algorithmObject [In] The algorithm object.
resultAlgorithmObject [Out] The result algorithm object.
randomAlgorithm [In] The random algorithm.
surrenderContext [In] The surrender context.
Ignored if the value is (A_SURRENDER_CTX *)NULL_PTR.
Returns:
0 indicates success.
See Error Identifiers for valid values.
See also:
B_GenerateInit().
Samples:
dhparam.c, dsasign.c, ecutil.c, p11dsakeygen.c, and p11dsasign.c.

int B_GenerateRandomBytes (  B_ALGORITHM_OBJ    algorithmObject,
unsigned char *    output,
unsigned int    outputLen,
A_SURRENDER_CTX *    surrenderContext
)  ;
 

Generates outputLen pseudo-random Bytes from algorithmObject, and stores the result in output. The algorithmObject must have been seeded.

Parameters:
algorithmObject [In] The random algorithm.
output [Out] The buffer for output Bytes.
outputLen [Out] The number of Bytes to output.
surrenderContext [In] The surrender context.
Ignored if the value is (A_SURRENDER_CTX *)NULL_PTR.
Returns:
0 indicates success.
See Error Identifiers for valid values.
See also:
B_RandomInit().
Samples:
descbc.c, ecrand.c, encdec.c, entrpycb.c, genbytes.c, hmac.c, intelrnd.c, keywrap.c, parsepkcs5.c, pbe.c, pkcs5v2pbe.c, rc2.c, rc2ecb.c, rc5ofb.c, rsaoaep.c, setoaep.c, tdescfb.c, x931.c, and x931rand.c.

int B_GetAlgorithmInfo (  POINTER *    info,
B_ALGORITHM_OBJ    algorithmObject,
B_INFO_TYPE    infoType
)  ;
 

Retrieves the information held by algorithmObject in the format specified by infoType, and stores the result in info. The format of the information returned by this function is the same as the format supplied to B_SetAlgorithmInfo().

This function can be used to convert between external representations of information. For example, an algorithm can be set up to perform encryption using AI_MD2WithDES_CBCPad, and later the BER representation of that algorithm can be computed by calling B_GetAlgorithmInfo() with AI_MD2WithDES_CBCPadBER.

Parameters:
info [Out] The algorithm information.
algorithmObject [In] The algorithm object.
infoType [In] The type of AI.
See Algorithm Identifiers for valid values.
Returns:
0 indicates success.
See Error Identifiers for valid values.
Samples:
alginfo.c, berder.c, dhagree.c, dhagrsv.c, dhparam.c, ecdh.c, ecdsa.c, ecdsadig.c, eces.c, ecutil.c, mdber.c, parsepkcs5.c, pbe.c, and x962.c.

int B_GetAlgorithmState (  ITEM *    algState,
B_ALGORITHM_OBJ    algorithmObject
)  ;
 

Saves the current operating state of an algorithm object for reuse at a later time. Retrieves the current state held by algorithmObject and stores the result in algState. The information returned in algState is the data and len elements of the ITEM provided by the caller, which provides the address and length of the current state information. The memory allocated for the data in the ITEM belongs to the Crypto-C object and will be freed upon calling B_DestroyAlgorithmObject(). Copy this information to your own buffer if you want to save it. The state information returned is opaque; that is, no interfacing information is provided to the application.

Saving the state of an algorithm object is useful in key agreement operations. For example, if performing a key agreement operation, set up an algorithm with AI_DHKeyAgree. Then call B_KeyAgreeInit() and B_KeyAgreePhase1() to create a Diffie-Hellman Phase 1 result. Call B_GetAlgorithmState() to save the state of the AI_DHKeyAgree algorithm object. When it is time to compute the Diffie-Hellman Phase 2 result, call B_SetAlgorithmState() to recreate the AI_DHKeyAgree algorithm object in its prior state. Then call B_KeyAgreePhase2() to complete the operation.

This function differs from B_GetAlgorithmInfo() as that function returns only the initial parameters that were used by B_SetAlgorithmInfo(). This function obtains all of the intermediate values of the encryption process, including keying data. Consequently, the calling application is responsible for protecting the data obtained by B_GetAlgorithmState() from unwanted access during storage.

note.gif
This function is currently implemented for the Diffie-Hellman key agreement, RC4, MD2, MD5 and SHA1.
Parameters:
algState [Out] The current algorithm information.
algorithmObject [In] The algorithm object.
Returns:
0 indicates success.
See Error Identifiers for valid values.
See also:
B_SetAlgorithmState().
Samples:
dhagrsv.c, mdigsv.c, and rc4sv.c.

int B_GetDevice (  ITEM *    device,
B_ALGORITHM_OBJ    algorithmObject
)  ;
 

Retrieves a description of the device that will be used by algorithmObject to perform the operation. This is useful only after an Init() call, when the AM from the chooser has been loaded.

The return value is placed into device. Crypto-C expects to find an ITEM at the address given. It will place a pointer into the .data field of that ITEM and a length into the .len field. The pointer points to a description (NULL-terminated) of the device. Do not overwrite or free the memory associated with that field as it belongs to Crypto-C.

Parameters:
device [Out] The location of the return value.
algorithmObject [In] The object to use.
Returns:
0 indicates success.
See Error Identifiers for valid values.
note.gif
This function is generally for use with algorithm objects initialized using choosers created by B_CreateHardwareChooser(). The return value after initializing with any other chooser will be software.
Samples:
p11dsakeygen.c, p11dsasign.c, p11rsaencrypt.c, p11rsakeygen.c, and p11rsasign.c.

void B_GetExtendedErrorInfo (  B_ALGORITHM_OBJ    algorithmObject,
ITEM *    errorDataItem,
POINTER *    am
)  ;
 

Sets errorDataItem->data to point at the error data, and errorDataItem->len to point at the length in Bytes of the error data. If required, am is set to the address of the AM where the error originated.

Parameters:
algorithmObject [In, Out] The algorithm object.
errorDataItem [Out] Returns pointers to error data and the length of the data.
am [Out] The AM. Points at the method table.
note.gif
A NULL-extended error is indicated by a length of zero. The error data may be a data structure that includes pointers to allocated memory. These allocations are cleaned up using an error destruction routine assigned during the creation of the extended error data.
Samples:
intelrnd.c.

void B_GetKeyExtendedErrorInfo (  B_KEY_OBJ    keyObject,
ITEM *    errorDataItem,
POINTER *    am
)  ;
 

Sets errorDataItem->data to point at the error data, and errorDataItem->len to the length in Bytes of the error data. am is optionally set by the hardware manufacturer. See the documentation supplied by your hardware vendor for more information.

Parameters:
keyObject [In] The key object.
errorDataItem [Out] Returns a pointer to error data and the length of the data.
am [In] The AM. Points at the method table.
note.gif
A NULL-extended error is indicated by a length of zero. The error data may be a data structure that includes pointers to allocated memory. These allocations are cleaned up using an error destruction routine assigned during the creation of the extended error data.

int B_GetKeyInfo (  POINTER *    info,
B_KEY_OBJ    keyObject,
B_INFO_TYPE    infoType
)  ;
 

Retrieves the information held by keyObject in the format specified by infoType, and stores the result in info. The value of infoType is one of the KIs listed in Key Identifiers.
The format of the information returned by this function is not always identical to the format supplied to B_SetKeyInfo() because it may convert the key data to another form before storing it in the key object. For example,KI_DES8 sets the DES parity before storing, KI_RSAPublicBER converts a BER encoding to DER, and KI_RSAPublic strips off leading zeros from the modulus and exponent integers.

Parameters:
info [Out] The key information.
keyObject [In] The key object.
infoType [In] The KI.
Returns:
0 indicates success.
See Error Identifiers for valid values.
Samples:
alginfo.c, bslec.c, bslite.c, descbc.c, ecutil.c, p11dsakeygen.c, p11rsaencrypt.c, p11rsakeygen.c, rsamultp.c, rsapkcs.c, rsapkcs2.c, and tdescfb.c.

unsigned int B_IntegerBits (  unsigned char *    integer,
unsigned int    integerLen
)  ;
 

Determines the key size in bits of an RSA key by passing in the modulus. Returns the number of significant bits in an arbitrary-length integer, where integer points to an unsigned Byte array with the most significant Byte first. Leading zeroes are ignored. The integer is considered unsigned; that is, the most significant bit is counted and is not considered a sign bit.

This function can be used to examine the value of a large integer such as those returned by B_GetKeyInfo() for KIs such as KI_RSAPublic.

Parameters:
integer [In] The canonical integer.
If integerLen is 0, integer is ignored and 0 is returned.
integerLen [In] The length in Bytes.
Returns:
0 indicates success.
See Error Identifiers for valid values.

int B_KeyAgreeInit (  B_ALGORITHM_OBJ    algorithmObject,
B_KEY_OBJ    keyObject,
B_ALGORITHM_CHOOSER    algorithmChooser,
A_SURRENDER_CTX *    surrenderContext
)  ;
 

Initializes the algorithm object to perform key agreement using the algorithm specified by a previous call to B_SetAlgorithmInfo().

This function can be used for Diffie-Hellman key agreement. Call this function to set up the algorithm. Each party then calls B_KeyAgreePhase1() to generate the value that is then sent to the other party. The parties then pass the received value to B_KeyAgreePhase2(), which computes the agreed-upon key.

Parameters:
algorithmObject [In, Out] The algorithm object.
keyObject [In, Out] The key object that supplies the key information.
Enter (B_KEY_OBJ)NULL_PTR for key algorithms that do not need an input key.
algorithmChooser [In, Out] The algorithm chooser.
surrenderContext [In] The surrender context.
Ignored if the value is (A_SURRENDER_CTX *)NULL_PTR.
Returns:
0 indicates success.
See Error Identifiers for valid values.
note.gif
There is no need to call this function again if several key agreements are performed using the same algorithm.
See also:
B_KeyAgreePhase1() and B_KeyAgreePhase2().
Samples:
dhagree.c, dhagrsv.c, and ecdh.c.

int B_KeyAgreePhase1 (  B_ALGORITHM_OBJ    algorithmObject,
unsigned char *    output,
unsigned int *    outputLen,
unsigned int    maxOutputLen,
B_ALGORITHM_OBJ    randomAlgorithm,
A_SURRENDER_CTX *    surrenderContext
)  ;
 

Generates the initial value for the other party in a key agreement operation. Writes it to output, which is a buffer supplied by the caller of at least maxOutputLen Bytes, and sets outputLen to the number of Bytes written to output.

Parameters:
algorithmObject [In, Out] The algorithm object.
output [Out] The output data buffer.
outputLen [Out] The length of the output data.
maxOutputLen [In] The size of the output data buffer.
randomAlgorithm [In] The random Byte source.
surrenderContext [In] The surrender context.
Ignored if the value is (A_SURRENDER_CTX *)NULL_PTR.
Returns:
0 indicates success.
See Error Identifiers for valid values.
See also:
B_KeyAgreeInit() and B_KeyAgreePhase2().
Samples:
dhagree.c, dhagrsv.c, and ecdh.c.

int B_KeyAgreePhase2 (  B_ALGORITHM_OBJ    algorithmObject,
unsigned char *    output,
unsigned int *    outputLen,
unsigned int    maxOutputLen,
unsigned char *    input,
unsigned int    inputLen,
A_SURRENDER_CTX *    surrenderContext
)  ;
 

Performs a round of key agreement as specified by algorithmObject, receiving inputLen Bytes from input, which is the other party's intermediate value. Writes the output to output, which is a buffer supplied by the caller of at least maxOutputLen Bytes, and sets outputLen to the number of Bytes written to output.

If input is the other party's final intermediate value, output is the agreed-upon key. Otherwise, output is a new intermediate value to send to the other party.

This function can be called one or more times to process intermediate values, depending on how many other parties are involved in the key agreement. This function is called once for the Diffie-Hellman algorithm.

Parameters:
algorithmObject [I. Out] The algorithm object.
output [Out] The output data buffer.
outputLen [Out] The length of the output data.
maxOutputLen [In] The size of the output data buffer.
input [In] The input data.
inputLen [In] The length of the input data.
surrenderContext [In] The surrender context.
Ignored if the value is (A_SURRENDER_CTX *)NULL_PTR.
Returns:
0 indicates success.
See Error Identifiers for valid values.
Samples:
dhagree.c, dhagrsv.c, and ecdh.c.

int B_RandomInit (  B_ALGORITHM_OBJ    algorithmObject,
B_ALGORITHM_CHOOSER    algorithmChooser,
A_SURRENDER_CTX *    surrenderContext
)  ;
 

Initializes algorithmObject to generate random Bytes using the algorithm specified by a previous call to B_SetAlgorithmInfo(). algorithmObject is ready to generate Bytes after the call to this function. However, it is necessary to mix in random seed values with B_RandomUpdate(). Without seed values, the Bytes generated by the algorithm follow a default unseeded Byte sequence.

Call this function once to create the generator and then call B_RandomUpdate() one or more times to add seed Bytes (values that are hard for an attacker to predict) to the generator.

After enough seed is added, for example, at least 128 Bytes, call B_GenerateRandomBytes() one or more times to generate blocks of pseudo-random data.

If B_RandomUpdate() is called only once before B_GenerateRandomBytes(), then the BSAFE 2 algorithms will be used. Two or more calls to B_RandomUpdate() mean the BSAFE 3 algorithms will be used.

To add more hard-to-predict values to the generator, call B_RandomUpdate() after calling B_GenerateRandomBytes(). There is no need to call B_RandomInit() again.

Parameters:
algorithmObject [In, Out] The random algorithm object.
algorithmChooser [In] The algorithm chooser.
surrenderContext [In] The surrender context.
Ignored if the value is (A_SURRENDER_CTX *)NULL_PTR.
Returns:
0 indicates success.
See Error Identifiers for valid values.
See also:
B_RandomUpdate() and B_GenerateRandomBytes().
Samples:
ecrand.c, entrpycb.c, genbytes.c, intelrnd.c, x931.c, and x931rand.c.

int B_RandomUpdate (  B_ALGORITHM_OBJ    algorithmObject,
unsigned char *    input,
unsigned int    inputLen,
A_SURRENDER_CTX *    surrenderContext
)  ;
 

Mixes inputLen Bytes from input into algorithmObject.

Parameters:
algorithmObject [In, Out] The random algorithm.
input [In] The block values to mix.
inputLen [In] The length of the input block.
surrenderContext [In] The surrender context.
Ignored if the value is (A_SURRENDER_CTX *)NULL_PTR.
Returns:
0 indicates success.
See Error Identifiers for valid values.
See also:
B_RandomInit().
Samples:
ecrand.c, genbytes.c, and intelrnd.c.

int B_SetAlgorithmInfo (  B_ALGORITHM_OBJ    algorithmObject,
B_INFO_TYPE    infoType,
POINTER    info
)  ;
 

Sets the parameters of algorithmObject to the information pointed to by info. infoType specifies the type of algorithm and the format of the parameters. A separate copy of the information supplied by info is allocated inside the algorithm object so that info can be changed after the call to this function.

Do not reset an algorithm with a different algorithm. Either create a new algorithm object, or destroy an existing one and recreate it.

Parameters:
algorithmObject [In, Out] The algorithm object.
infoType [In] The type of algorithm information.
See Algorithm Identifiers for valid values.
info [In] The algorithm information.
Returns:
0 indicates success.
BE_WRONG_ALGORITHM_INFO indicates the algorithm type encoded in info is not the type expected by infoType.
Samples:
aesfb.c, alginfo.c, alginfoutil.c, b64.c, berder.c, bslec.c, bslite.c, bsliteds.c, descbc.c, dhagree.c, dhagrsv.c, dhparam.c, dintroex.c, dsasign.c, ecdh.c, ecdsa.c, ecdsadig.c, eces.c, ecrand.c, ecspecial.c, ecutil.c, encdec.c, entrpycb.c, feedback.c, genbytes.c, hmac.c, intelrnd.c, introex.c, keywrap.c, mdber.c, mdigest.c, mdigsv.c, multdecr.c, multencr.c, p11dsakeygen.c, p11dsasign.c, p11rsaencrypt.c, p11rsakeygen.c, p11rsasign.c, parsepkcs5.c, pbe.c, pbkdf2.c, pkcs12pbe.c, pkcs5v2pbe.c, rc2.c, rc2ecb.c, rc4.c, rc4sv.c, rc5ofb.c, rsaoaep.c, rsapkcs.c, rsapkcs2.c, rsapss.c, rsasign.c, rsasign2.c, rsautil.c, scrtshar.c, seedfb.c, setoaep.c, sha512.c, tdescfb.c, x931.c, x931rand.c, and x962.c.

int B_SetAlgorithmState (  B_ALGORITHM_OBJ    algorithmObject,
B_INFO_TYPE    infoType,
ITEM *    algState,
B_ALGORITHM_CHOOSER    algorithmChooser
)  ;
 

Restores the algorithmObject to the previous state as contained in algState. algState must have been previously obtained by a call to B_GetAlgorithmState().

infoType specifies the type of algorithm and the format of the parameters and must be compatible with the original infoType used to initialize the original algorithm object. See Algorithm Identifiers.

This function differs from B_SetAlgorithmInfo() as that function sets only the initial parameters to be used by an AI. This function restores the full intermediate values of the encryption process, including keying data and the results of all B_ calls made after the original call to this function.

Do not re-restore or reset an algorithm object that has been restored. That is, do not call B_SetAlgorithmInfo() twice on a single created algorithm object. Instead, create a new algorithm object, or destroy an existing one and restore or create it again.

This function is currently implemented for Diffie-Hellman key agreement, RC4, MD2, MD5, and SHA-1.

Parameters:
algorithmObject [In, Out] The created algorithm object to set.
infoType [In] The AI.
algState [In] The previous algorithm state from B_GetAlgorithmState().
algorithmChooser [In] The algorithm chooser.
Returns:
0 indicates success.
BE_WRONG_ALGORITHM_INFO indicates that the data encoded in algState is not compatible with the data expected by infoType.
See also:
B_GetAlgorithmState.
Samples:
dhagrsv.c, mdigsv.c, and rc4sv.c.

int B_SetKeyInfo (  B_KEY_OBJ    keyObject,
B_INFO_TYPE    infoType,
POINTER    info
)  ;
 

Sets the value of keyObject to the information pointed to by info. infoType specifies the format of the information, which is one of the KIs listed in Key Identifiers.
Algorithm Identifiers specify the KI that should be used to set the key object required by the algorithm.

A separate copy of the information supplied by info is allocated inside the key object so info can be changed after the call to this function.

Do not reset a key object once it has been set. Either create a new key object, or destroy an existing one and create it again.

Parameters:
keyObject [In, Out] The key object.
infoType [In] The type of key information.
info [In] The key information.
Returns:
0 indicates success.
BE_WRONG_KEY_INFO indicates the key type encoded in info is not the type expected by infoType.
Samples:
aes.c, aesfb.c, alginfo.c, alginfoutil.c, berder.c, bslec.c, bslite.c, bsliteds.c, descbc.c, dintroex.c, feedback.c, hmac.c, introex.c, keywrap.c, multdecr.c, multencr.c, p11dsasign.c, p11rsaencrypt.c, p11rsasign.c, parsepkcs5.c, pbe.c, pbkdf2.c, pkcs5v2pbe.c, rc2.c, rc2ecb.c, rc4.c, rc4sv.c, rc5.c, rc5ofb.c, seed.c, seedfb.c, and tdescfb.c.

int B_SignFinal (  B_ALGORITHM_OBJ    algorithmObject,
unsigned char *    signature,
unsigned int *    signatureLen,
unsigned int    maxSignatureLen,
B_ALGORITHM_OBJ    randomAlgorithm,
A_SURRENDER_CTX *    surrenderContext
)  ;
 

Finalizes the digest process and computes the digital signature. Writes the signature to signature, which is a buffer supplied by the caller of at least maxSignatureLen Bytes, and sets signatureLen to the length of the signature.

algorithmObject is reset to the state it was in after the call to B_SignInit(), in order to perform another signing operation.

Parameters:
algorithmObject [In, Out] The algorithm object.
signature [Out] The signature output buffer.
signatureLen [Out] The length of signature output.
maxSignatureLen [In] The size of output buffer.
randomAlgorithm [In] The random Byte source.
May be (B_ALGORITHM_OBJ)NULL_PTR for signature algorithms that do not need random numbers.
surrenderContext [In] The surrender context.
Ignored if the value is (A_SURRENDER_CTX *)NULL_PTR.
Returns:
0 indicate success.
See Error Identifiers for valid values.
See also:
B_SignInit() and B_SignUpdate().
Samples:
dsasign.c, ecdsa.c, ecdsadig.c, p11dsasign.c, p11rsasign.c, rsapss.c, rsasign.c, rsasign2.c, x931.c, and x962.c.

int B_SignInit (  B_ALGORITHM_OBJ    algorithmObject,
B_KEY_OBJ    keyObject,
B_ALGORITHM_CHOOSER    algorithmChooser,
A_SURRENDER_CTX *    surrenderContext
)  ;
 

Initializes the algorithm object for computing a digital signature using the algorithm specified by a previous call to B_SetAlgorithmInfo().

This function only needs to be called once to set up a signature algorithm. B_SignUpdate() can be called multiple times to process blocks of data, and B_SignFinal() is called once to process the last block, which includes producing the result. After B_SignFinal() is called, B_SignUpdate() can be called to start signing another sequence of blocks. There is no need to call this function again.

Parameters:
algorithmObject [In, Out] The algorithm object.
keyObject [In] The key object. Typically a private key.
algorithmChooser [In] The algorithm chooser.
surrenderContext [In] The surrender context.
Ignored if the value is (A_SURRENDER_CTX *)NULL_PTR.
Returns:
0 indicates success.
See Error Identifiers for valid values.
See also:
B_SignUpdate() and B_SignFinal().
Samples:
dsasign.c, ecdsa.c, ecdsadig.c, p11dsasign.c, p11rsasign.c, rsapss.c, rsasign.c, rsasign2.c, x931.c, and x962.c.

int B_SignUpdate (  B_ALGORITHM_OBJ    algorithmObject,
unsigned char *    partIn,
unsigned int    partInLen,
A_SURRENDER_CTX *    surrenderContext
)  ;
 

Updates the digest process for algorithmObject with partInLen Bytes from partIn. This function can be called zero or more times to supply the data by parts.

Parameters:
algorithmObject [In, Out] The algorithm object.
partIn [In] The input data.
partInLen [In] The length of the input data.
surrenderContext [In] The surrender context.
Ignored if the value is (A_SURRENDER_CTX *)NULL_PTR.
Returns:
0 indicates success.
See Error Identifiers for valid values.
See also:
B_SignInit() and B_SignFinal().
Samples:
dsasign.c, ecdsa.c, ecdsadig.c, p11dsasign.c, p11rsasign.c, rsapss.c, rsasign.c, rsasign2.c, x931.c, and x962.c.

int B_SymmetricKeyGenerate (  B_ALGORITHM_OBJ    algorithmObject,
B_KEY_OBJ    symmetricKey,
B_ALGORITHM_OBJ    randomObject,
A_SURRENDER_CTX *    surrenderContext
)  ;
 

Creates a symmetric key in accordance with data specified by a previous call to B_SetAlgorithmInfo(). If hardware is present, the key information is stored in a KI_TOKEN_INFO structure. If no hardware is present, the key information is stored in KI_EXTENDED_TOKEN_INFO format, which extends the Token Types base type.

Parameters:
algorithmObject [In, Out] The algorithm object.
symmetricKey [Out] The symmetric key.
randomObject [In] The random object.
surrenderContext [In] The surrender context.
Returns:
0 indicates success.
See Error Identifiers for valid values.

int B_SymmetricKeyGenerateInit (  B_ALGORITHM_OBJ    algorithmObject,
B_ALGORITHM_CHOOSER    algorithmChooser,
A_SURRENDER_CTX *    surrenderContext
)  ;
 

Initializes a key generation object.

Parameters:
algorithmObject [In, Out] The algorithm object.
algorithmChooser [In] The algorithm chooser.
surrenderContext [In] The surrender context.
Returns:
0 indicates success.
See Error Identifiers for valid values.

int B_UnwrapKey (  B_ALGORITHM_OBJ    algorithmObject,
B_KEY_OBJ    unwrappedKey,
unsigned char *    wrappedKey,
unsigned int    wrappedKeyLen,
B_KEY_CHOOSER    keyChooser,
B_ALGORITHM_OBJ    randomAlgorithm,
A_SURRENDER_CTX *    surrenderContext
)  ;
 

Decrypts the key data in wrappedKey and sets unwrappedKey to the appropriate KI based on keyChooser.

A key chooser is a NULL_PTR terminated array of pointers. The series of flags in the array are function pointers which contain the possible KIs.

  • KM_PKCS_RSA_PRIVATE_BER_KEY
  • KM_SYMMETRIC_KEY.

KM_PKCS_RSA_PRIVATE_BER_KEY loads: 







A key chooser contains the possible types of key you are wrapping. It is created as follows:



 B_KEY_CHOOSER *KEY_WRAP_CHOOSER[] = {
   &KM_PKCS_RSA_PRIVATE_BER_KEY,
   &KM_SYMMETRIC_KEY,
  (B_KEY_METHOD *)NULL_PTR
 }







To unwrap a key, set an algorithm with the same encryption algorithm used to wrap it. Call B_UnwrapKeyInit() with the key unwrapping key and then call this function.

Parameters: 




algorithmObject
[In] The algorithm object. 


unwrappedKey
[Out] The resulting key object. 


wrappedKey
[In] The encrypted key. 


wrappedKeyLen
[In] The length of the encrypted key. 


keyChooser
[In] The key type. 


randomAlgorithm
[In] The random Byte source. 


surrenderContext
[In] The surrender context.





Returns: 

0 indicates success.

 See Error Identifiers for valid values.

See also: 

B_UnwrapKeyInit(). 

Samples: 

keywrap.c.
    		
  







  

    
      

        

           int B_UnwrapKeyInit 
          ( 
          B_ALGORITHM_OBJ 
            algorithmObject, 
        

        

          
          
          B_KEY_OBJ 
            keyObject, 
        

        

          
          
          B_ALGORITHM_CHOOSER 
            algorithmChooser, 
        

        

          
          
          A_SURRENDER_CTX * 
            surrenderContext
        

        

          
          ) 
          ;
        


      

    		
  





  

    
       
    
    



Initializes an algorithm object for a key unwrapping operation using the algorithm specified by a previous call to B_SetAlgorithmInfo(). 

Parameters: 




algorithmObject
[In, Out] The algorithm object. 


keyObject
[In] The key wrapping object. 


algorithmChooser
[In] The algorithm chooser. 


surrenderContext
[In] The surrender context.

Ignored if the value is (A_SURRENDER_CTX *)NULL_PTR.





Returns: 

0 indicates success.

 See Error Identifiers for valid values.

See also: 

B_UnwrapKey(). 

Samples: 

keywrap.c.
    		
  







  

    
      

        

           int B_VerifyFinal 
          ( 
          B_ALGORITHM_OBJ 
            algorithmObject, 
        

        

          
          
          unsigned char * 
            signature, 
        

        

          
          
          unsigned int 
            signatureLen, 
        

        

          
          
          B_ALGORITHM_OBJ 
            randomAlgorithm, 
        

        

          
          
          A_SURRENDER_CTX * 
            surrenderContext
        

        

          
          ) 
          ;
        


      

    		
  





  

    
       
    
    



Finalizes the digest process and verifies the digital signature supplied by signature of signatureLen Bytes. algorithmObject is reset to the state it was in after the call to B_VerifyInit(), in order to perform another verification operation.

Parameters: 




algorithmObject
[In, Out] The algorithm object. 


signature
[In] The signature to verify. 


signatureLen
[In] The length of signature. 


randomAlgorithm
[In] The random Byte source.

May be (B_ALGORITHM_OBJ)NULL_PTR for signature algorithms that do not need random numbers. 


surrenderContext
[In] The surrender context.

Ignored if the value is (A_SURRENDER_CTX *)NULL_PTR.





Returns: 

0 indicates success.

 See Error Identifiers for valid values.

See also: 

B_VerifyInit() and B_VerifyUpdate(). 

Samples: 

dsasign.c, ecdsa.c, ecdsadig.c, p11dsasign.c, p11rsasign.c, rsapss.c, rsasign.c, rsasign2.c, x931.c, and x962.c.
    		
  







  

    
      

        

           int B_VerifyInit 
          ( 
          B_ALGORITHM_OBJ 
            algorithmObject, 
        

        

          
          
          B_KEY_OBJ 
            keyObject, 
        

        

          
          
          B_ALGORITHM_CHOOSER 
            algorithmChooser, 
        

        

          
          
          A_SURRENDER_CTX * 
            surrenderContext
        

        

          
          ) 
          ;
        


      

    		
  





  

    
       
    
    



Initializes the algorithm object for digital signature verification using the algorithm specified by a previous call to B_SetAlgorithmInfo(). This function only needs to be called once to set up a verification algorithm. B_VerifyUpdate() can be called multiple times to process blocks of data, and B_VerifyFinal() is called once to process the last block which includes checking the computed signature against the expected signature that is passed to B_VerifyFinal(). After B_VerifyFinal() is called, B_VerifyUpdate() can be called to start verifying another sequence of blocks. There is no need to call B_VerifyInit() again.

Parameters: 




algorithmObject
[In, Out] The algorithm object. 


keyObject
[In] The key object. Typically a public key. 


algorithmChooser
[In] The algorithm chooser. 


surrenderContext
[In] The surrender context.

Ignored if the value is (A_SURRENDER_CTX *)NULL_PTR.





Returns: 

0 indicates success.

 See Error Identifiers for valid values.

See also: 

B_VerifyUpdate() and B_VerifyFinal(). 

Samples: 

dsasign.c, ecdsa.c, ecdsadig.c, p11dsasign.c, p11rsasign.c, rsapss.c, rsasign.c, rsasign2.c, x931.c, and x962.c.
    		
  







  

    
      

        

           int B_VerifyUpdate 
          ( 
          B_ALGORITHM_OBJ 
            algorithmObject, 
        

        

          
          
          unsigned char * 
            partIn, 
        

        

          
          
          unsigned int 
            partInLen, 
        

        

          
          
          A_SURRENDER_CTX * 
            surrenderContext
        

        

          
          ) 
          ;
        


      

    		
  





  

    
       
    
    



Updates the digest process for algorithmObject with partInLen Bytes from partIn. This function can be called zero or more times to supply the data by parts.

Parameters: 




algorithmObject
[In, Out] The algorithm object. 


partIn
[In] The input data. 


partInLen
[In] The length of the input data. 


surrenderContext
[In] The surrender context.

Ignored if the value is (A_SURRENDER_CTX *)NULL_PTR.





Returns: 

0 indicates success.

 See Error Identifiers for valid values.

See also: 

B_VerifyInit() and B_VerifyFinal(). 

Samples: 

dsasign.c, ecdsa.c, ecdsadig.c, p11dsasign.c, p11rsasign.c, rsapss.c, rsasign.c, rsasign2.c, x931.c, and x962.c.
    		
  







  

    
      

        

           int B_WrapKey 
          ( 
          B_ALGORITHM_OBJ 
            algorithmObject, 
        

        

          
          
          unsigned char * 
            wrappedKey, 
        

        

          
          
          unsigned int * 
            wrappedKeyLen, 
        

        

          
          
          unsigned int 
            maxOutLen, 
        

        

          
          
          B_KEY_OBJ 
            keyToWrap, 
        

        

          
          
          B_KEY_CHOOSER 
            keyChooser, 
        

        

          
          
          B_ALGORITHM_OBJ 
            randomAlgorithm, 
        

        

          
          
          A_SURRENDER_CTX * 
            surrenderContext
        

        

          
          ) 
          ;
        


      

    		
  





  

    
       
    
    



Encrypts the key data in keyToWrap. To wrap a key, set an algorithm object with an encryption algorithm, call B_WrapKeyInit() with the key wrapping key, and then call this function. The result is the BER encoding of an encrypted key, following the ASN.1 definition in PKCS #8 format.



EncryptedPrivateKeyInfo ::= SEQUENCE {
   encryptionAlgorithm EncryptionAlgorithmIdentifier,
   encryptedData EncryptedData }

EncryptionAlgorithmIdentifier ::= AlgorithmIdentifier

EncryptedData ::= OCTET STRING








A key chooser is a NULL_PTR terminated array of pointers. The series of flags in the array are function pointers which contain the possible KIs. 
    

  • KM_PKCS_RSA_PRIVATE_BER_KEY 
  • KM_SYMMETRIC_KEY. 

A key chooser contains the possible types of key you are wrapping. It is created as follows:



 B_KEY_CHOOSER *KEY_WRAP_CHOOSER[] = {
   &KM_PKCS_RSA_PRIVATE_BER_KEY,
   &KM_SYMMETRIC_KEY,
   (B_ALGORITHM_METHOD *)NULL_PTR
   };







If you are wrapping a symmetric key object, this function will encrypt the raw data to produce EncryptedData. If you are wrapping an asymmetric key object, this function will encrypt the BER encoding of the key. 


The key encodings are defined in PKCS #8 (private keys) and X.509 (public keys). These encodings match the KI_*BER KIs. The exception to this rule is if the encrypting algorithm is AI_SSLC_KeyWrap. When using this AI the key is encrypted as above, but then PEM-encoded. PEM encoding includes Base64 encoding and appropriate headers and footers.

Parameters: 




algorithmObject
[In] The algorithm object that performs the wrapping. 


wrappedKey
[Out] The result buffer. 


wrappedKeyLen
[Out] The length of the output. 


maxOutLen
[In] The size of the output buffer. 


keyToWrap
[In] The key to wrap. 


keyChooser
[In] The key type. 


randomAlgorithm
[In] The random Byte source. 


surrenderContext
[In] The surrender context.





Returns: 

0 indicates success.

 See Error Identifiers for valid values.

See also: 

B_WrapKeyInit(). 

Samples: 

keywrap.c.
    		
  







  

    
      

        

           int B_WrapKeyInit 
          ( 
          B_ALGORITHM_OBJ 
            algorithmObject, 
        

        

          
          
          B_KEY_OBJ 
            keyObject, 
        

        

          
          
          B_ALGORITHM_CHOOSER 
            algorithmChooser, 
        

        

          
          
          A_SURRENDER_CTX * 
            surrenderContext
        

        

          
          ) 
          ;
        


      

    		
  





  

    
       
    
    



Initializes a key wrapping operation using the algorithm specified by a previous call to B_SetAlgorithmInfo(). 

Parameters: 




algorithmObject
[In] The algorithm object. 


keyObject
[In, Out] The key wrapping object. 


algorithmChooser
[In] The algorithm chooser. 


surrenderContext
[In] The surrender context.

Ignored if the value is (A_SURRENDER_CTX *)NULL_PTR.





Returns: 

0 indicates success.

 See Error Identifiers for valid values.

See also: 

B_WrapKey(). 

Samples: 

keywrap.c.
    		
  







Copyright (c) 1999-2005 RSA Security Inc. All rights reserved.
068-001001-6210-001-000 - 6.2.1