Security Builder Crypto functions use three types of input and output arguments: flag values, length parameters, and byte array data.
There are flag variables in some API functions. For example, you must select a mode of operation for the block ciphers, or a hash algorithm for PKCS#1 v1.5 signing.
These flags are always int types. The alternatives for flag values are documented with their functions.
Your application can query current flag values. These are returned through int * arguments. To see an example, consult the entry for the function hu_AESParamsGet(), here. (Specifically, the mode parameter.)
Length parameters are always of type size_t. The actual machine-level capacity (in bits) of this type depends on your platform, as defined in ANSI C. A length parameter usually refers to a corresponding byte array parameter, indicating the number of bytes taken up by the array. There are some exceptions: the length arguments for public key ciphers often specify bit lengths of certain cryptographic parameters instead of byte counts, and convention dictates that the length of an AES key be specified in bits.
The length of an output byte array buffer is often supplied as a size_t * argument; that is, a pointer to a size_t variable. Through this argument, the API function returns the expected length of the output buffer, or the number of bytes of the output buffer that were actually filled.
The length of the output buffer for symmetric ciphers need not be specified since it is the same as the length of the input buffer.1
The length of output for a message digest is specified as size_t, not size_t *, because the length is set at the Begin stage.
You can dictate the length of certain types of output, such as the number of random bytes returned from the RNG, or the length of output from ANSI KDF. These user- specified lengths are of type size_t.
Any input or output other than a length or flag value is contained in a byte array, represented by unsigned char *. This is an array of arbitrary length, and it is paired with a length argument to indicate how many bytes it contains. The API functions use these byte array buffers to hold plaintext and ciphertext buffers, message digests, MAC keys and tags, keys for symmetric ciphers, and private/public keys for asymmetric algorithms.
Some of the inputs and outputs used by the API functions are mathematical types, such as integers, or some other data types employed in the cryptographic algorithms. In such cases, the format is often an octet string as defined in standards documents such as IEEE 1363-2000, ANSI X9.62, or SEC1.
For output, your application must allocate sufficient memory space and pass it to an API function as unsigned char *. If the buffer is not large enough, the function returns an error: SB_ERR_BAD_OUTPUT_BUF_LEN. You may be able to query the length of output in cases where its potential length is not clear. If NULL is passed to the unsigned char * byte array argument of the function, the function’s required or maximum length is returned through the corresponding pointer to the size_t variable. You can then call the function again after allocating a buffer of this length. An example of this would be calling hu_IDLCDSANoHashSign() to determine the length of the s and r signature components, and then calling hu_IDLCDSANoHashSign() again with those values to sign the message digest.