Next: X.509 Functions, Previous: KRB-ERROR Functions, Up: Programming Manual [Contents][Index]
Underneath the high-level functions described earlier, cryptographic operations are happening. If you need to access these cryptographic primitives directly, this section describes the functions available.
Most cryptographic operations need keying material, and cryptographic
keys have been isolated into it’s own data structure
Shishi_key. The following illustrates it’s contents, but note
that you cannot access it’s elements directly but must use the
accessor functions described below.
struct Shishi_key
{
int type; /* RFC 1510 encryption integer type */
char *value; /* Cryptographic key data */
int version; /* RFC 1510 ``kvno'' */
};
All functions that operate on this data structure are described now.
key: structure that holds key information
Description: Get the principal part of the key owner principal name, i.e., except the realm.
Return value: Returns the principal owning the key. (Not a copy of it, so don’t modify or deallocate it.)
key: structure that holds key information
principal: string with new principal name.
Description: Set the principal owning the key. The string is copied into the key, so you can dispose of the variable immediately after calling this function.
key: structure that holds key information
Description: Get the realm part of the key owner principal name.
Return value: Returns the realm for the principal owning the key. (Not a copy of it, so don’t modify or deallocate it.)
key: structure that holds key information
realm: string with new realm name.
Description: Set the realm for the principal owning the key. The string is copied into the key, so you can dispose of the variable immediately after calling this function.
key: structure that holds key information
Description: Get key type.
Return value: Returns the type of key as an integer as described in the standard.
key: structure that holds key information
type: type to set in key.
Description: Set the type of key in key structure.
key: structure that holds key information
Description: Get the raw key bytes.
Return value: Returns the key value as a pointer which is valid throughout the lifetime of the key structure.
key: structure that holds key information
value: input array with key data.
Description: Set the key value and length in key structure. The value is copied into the key (in other words, you can deallocate value right after calling this function without modifying the value inside the key).
key: structure that holds key information
Description: Get the "kvno" (key version) of key. It will be UINT32_MAX if the key is not long-lived.
Return value: Returns the version of key ("kvno").
key: structure that holds key information
kvno: new version integer.
Description: Set the version of key ("kvno") in key structure. Use UINT32_MAX for non-ptermanent keys.
key: structure that holds key information
Description: Get the time the key was established. Typically only present when the key was imported from a keytab format.
Return value: Returns the time the key was established, or (time_t)-1 if not available.
Since: 0.0.42
key: structure that holds key information
timestamp: new timestamp.
Description: Set the time the key was established. Typically only relevant when exporting the key to keytab format.
Since: 0.0.42
key: structure that holds key information
Description: Calls shishi_cipher_name for key type.
Return value: Return name of key.
key: structure that holds key information
Description: Calls shishi_cipher_keylen for key type.
Return value: Returns the length of the key value.
handle: Shishi library handle create by shishi_init().
key: pointer to structure that will hold newly created key information
Description: Create a new Key information structure.
Return value: Returns SHISHI_OK iff successful.
key: pointer to structure that holds key information.
Description: Deallocates key information structure.
dstkey: structure that holds destination key information
srckey: structure that holds source key information
Description: Copies source key into existing allocated destination key.
handle: Shishi library handle create by shishi_init().
type: type of key.
value: input array with key value, or NULL.
key: pointer to structure that will hold newly created key information
Description: Create a new Key information structure, and set the key type and key value. KEY contains a newly allocated structure only if this function is successful.
Return value: Returns SHISHI_OK iff successful.
handle: Shishi library handle create by shishi_init().
type: type of key.
value: input string with base64 encoded key value, or NULL.
key: pointer to structure that will hold newly created key information
Description: Create a new Key information structure, and set the key type and key value. KEY contains a newly allocated structure only if this function is successful.
Return value: Returns SHISHI_INVALID_KEY if the base64 encoded key length doesn’t match the key type, and SHISHI_OK on success.
handle: Shishi library handle create by shishi_init().
type: type of key.
key: pointer to structure that will hold newly created key information
Description: Create a new Key information structure for the key type and some random data. KEY contains a newly allocated structure only if this function is successful.
Return value: Returns SHISHI_OK iff successful.
handle: Shishi library handle create by shishi_init().
type: type of key.
rnd: random data.
rndlen: length of random data.
outkey: pointer to structure that will hold newly created key information
Description: Create a new Key information structure, and set the key type and
key value using shishi_random_to_key(). KEY contains a newly
allocated structure only if this function is successful.
Return value: Returns SHISHI_OK iff successful.
handle: Shishi library handle create by shishi_init().
type: type of key.
password: input array containing password.
passwordlen: length of input array containing password.
salt: input array containing salt.
saltlen: length of input array containing salt.
parameter: input array with opaque encryption type specific information.
outkey: pointer to structure that will hold newly created key information
Description: Create a new Key information structure, and set the key type and
key value using shishi_string_to_key(). KEY contains a newly
allocated structure only if this function is successful.
Return value: Returns SHISHI_OK iff successful.
handle: Shishi library handle create by shishi_init().
type: type of key.
name: principal name of user.
password: input array containing password.
passwordlen: length of input array containing password.
parameter: input array with opaque encryption type specific information.
outkey: pointer to structure that will hold newly created key information
Description: Create a new Key information structure, and derive the key from
principal name and password using shishi_key_from_name(). The salt
is derived from the principal name by concatenating the decoded
realm and principal.
Return value: Returns SHISHI_OK iff successful.
Applications that run uninteractively may need keying material. In
these cases, the keys are stored in a file, a file that is normally
stored on the local host. The file should be protected from
unauthorized access. The file is in ASCII format and contains keys as
outputed by shishi_key_print. All functions that handle these
keys sets are described now.
handle: shishi handle as allocated by shishi_init().
keys: output pointer to newly allocated keys handle.
Description: Get a new key set handle.
Return value: Returns SHISHI_OK iff successful.
keys: key set handle as allocated by shishi_keys().
Description: Deallocates all resources associated with key set. The key set handle must not be used in calls to other shishi_keys_*() functions after this.
keys: key set handle as allocated by shishi_keys().
Description: Get size of key set.
Return value: Returns number of keys stored in key set.
keys: key set handle as allocated by shishi_keys().
keyno: integer indicating requested key in key set.
Get the n: th ticket in key set.
Return value: Returns a key handle to the keyno:th key in the key set, or NULL if keys is invalid or keyno is out of bounds. The first key is keyno 0, the second key keyno 1, and so on.
keys: key set handle as allocated by shishi_keys().
keyno: key number of key in the set to remove. The first
key is key number 0.
Description: Remove a key, indexed by keyno, in given key set.
keys: key set handle as allocated by shishi_keys().
key: key to be added to key set.
Description: Add a key to the key set. A deep copy of the key is stored, so changing key, or deallocating it, will not modify the value stored in the key set.
Return value: Returns SHISHI_OK iff successful.
keys: key set to print.
fh: file handle, open for writing, to print keys to.
Description: Print all keys in set using shishi_key_print.
Returns: Returns SHISHI_OK on success.
handle: shishi handle as allocated by shishi_init().
filename: filename to append key to.
keys: set of keys to print.
Description: Print an ASCII representation of a key structure to a file, for
each key in the key set. The file is appended to if it exists.
See shishi_key_print() for the format of the output.
Return value: Returns SHISHI_OK iff successful.
keys: key set handle as allocated by shishi_keys().
filename: filename to read keys from.
Description: Read zero or more keys from file filename and append them to the
keyset keys. See shishi_key_print() for the format of the input.
Return value: Returns SHISHI_OK iff successful.
Since: 0.0.42
handle: Shishi library handle create by shishi_init().
filename: file to read keys from.
server: server name to get key for.
realm: realm of server to get key for.
Description: Get keys that match specified server and realm from the key set file filename.
Return value: Returns the key for specific server and realm, read from the indicated file, or NULL if no key could be found or an error encountered.
handle: Shishi library handle create by shishi_init().
filename: file to read keys from.
server: server name to get key for.
Description: Get key for specified server from filename.
Return value: Returns the key for specific server, read from the indicated file, or NULL if no key could be found or an error encountered.
handle: Shishi library handle create by shishi_init().
filename: file to read keys from.
service: service to get key for.
realm: realm of server to get key for, or NULL for default realm.
Description: Get key for specified service and realm from filename.
Return value: Returns the key for the server
"SERVICE/HOSTNAME@REALM" (where HOSTNAME is the current system’s
hostname), read from the default host keys file (see
shishi_hostkeys_default_file()), or NULL if no key could be found
or an error encountered.
The previous functions require that the filename is known. For some applications, servers, it makes sense to provide a system default. These key sets used by server applications are known as “hostkeys”. Here are the functions that operate on hostkeys (they are mostly wrappers around generic key sets).
handle: Shishi library handle create by shishi_init().
Description: Get file name of default host key file.
Return value: Returns the default host key filename used in the library. (Not a copy of it, so don’t modify or deallocate it.)
handle: Shishi library handle create by shishi_init().
hostkeysfile: string with new default hostkeys file name, or
NULL to reset to default.
Description: Set the default host key filename used in the library. The string is copied into the library, so you can dispose of the variable immediately after calling this function.
handle: Shishi library handle create by shishi_init().
server: server name to get key for
Description: Get host key for server.
Return value: Returns the key for specific server, read from the
default host keys file (see shishi_hostkeys_default_file()), or
NULL if no key could be found or an error encountered.
handle: Shishi library handle create by shishi_init().
server: server name to get key for
realm: realm of server to get key for.
Description: Get host key for server in realm.
Return value: Returns the key for specific server and realm, read
from the default host keys file (see
shishi_hostkeys_default_file()), or NULL if no key could be found
or an error encountered.
handle: Shishi library handle create by shishi_init().
service: service to get key for.
realm: realm of server to get key for, or NULL for default realm.
Description: Get host key for service on current host in realm.
Return value: Returns the key for the server
"SERVICE/HOSTNAME@REALM" (where HOSTNAME is the current system’s
hostname), read from the default host keys file (see
shishi_hostkeys_default_file()), or NULL if no key could be found
or an error encountered.
handle: Shishi library handle create by shishi_init().
service: service to get key for.
Description: Get host key for service on current host in default realm.
Return value: Returns the key for the server "SERVICE/HOSTNAME"
(where HOSTNAME is the current system’s hostname), read from the
default host keys file (see shishi_hostkeys_default_file()), or
NULL if no key could be found or an error encountered.
After creating the key structure, it can be used to encrypt and decrypt data, calculate checksum on data etc. All available functions are described now.
type: encryption type, see Shishi_etype.
Description: Find out if cipher is supported.
Return value: Return 0 iff cipher is unsupported.
type: encryption type, see Shishi_etype.
Description: Read humanly readable string for cipher.
Return value: Return name of encryption type, e.g. "des3-cbc-sha1-kd", as defined in the standards.
type: encryption type, see Shishi_etype.
Description: Get block size for cipher.
Return value: Return block size for encryption type, as defined in the standards.
type: encryption type, see Shishi_etype.
Description: Get length of confounder for cipher.
Return value: Returns the size of the confounder (random data) for encryption type, as defined in the standards, or (size_t)-1 on error (e.g., unsupported encryption type).
type: encryption type, see Shishi_etype.
Description: Get key length for cipher.
Return value: Return length of key used for the encryption type, as defined in the standards.
type: encryption type, see Shishi_etype.
Description: Get length of random data for cipher.
Return value: Return length of random used for the encryption type, as defined in the standards, or (size_t)-1 on error (e.g., unsupported encryption type).
type: encryption type, see Shishi_etype.
Description: Get the default checksum associated with cipher.
Return value: Return associated checksum mechanism for the encryption type, as defined in the standards.
cipher: name of encryption type, e.g. "des3-cbc-sha1-kd".
Description: Get cipher number by parsing string.
Return value: Return encryption type corresponding to a string.
type: checksum type, see Shishi_cksumtype.
Description: Find out whether checksum is supported.
Return value: Return 0 iff checksum is unsupported.
type: checksum type, see Shishi_cksumtype.
Description: Get name of checksum.
Return value: Return name of checksum type, e.g. "hmac-sha1-96-aes256", as defined in the standards.
type: checksum type, see Shishi_cksumtype.
Description: Get length of checksum output.
Return value: Return length of checksum used for the checksum type, as defined in the standards.
checksum: name of checksum type, e.g. "hmac-sha1-96-aes256".
Description: Get checksum number by parsing a string.
Return value: Return checksum type, see Shishi_cksumtype, corresponding to a string.
handle: shishi handle as allocated by shishi_init().
keytype: cryptographic encryption type, see Shishi_etype.
password: input array with password.
passwordlen: length of input array with password.
salt: input array with salt.
saltlen: length of input array with salt.
parameter: input array with opaque encryption type specific information.
outkey: allocated key handle that will contain new key.
Description: Derive key from a string (password) and salt (commonly concatenation of realm and principal) for specified key type, and set the type and value in the given key to the computed values. The parameter value is specific for each keytype, and can be set if the parameter information is not available.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
keytype: cryptographic encryption type, see Shishi_etype.
rnd: input array with random data.
rndlen: length of input array with random data.
outkey: allocated key handle that will contain new key.
Description: Derive key from random data for specified key type, and set the type and value in the given key to the computed values.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
key: key to compute checksum with.
keyusage: integer specifying what this key is used for.
cksumtype: the checksum algorithm to use.
in: input array with data to integrity protect.
inlen: size of input array with data to integrity protect.
out: output array with newly allocated integrity protected data.
outlen: output variable with length of output array with checksum.
Description: Integrity protect data using key, possibly altered by supplied key usage. If key usage is 0, no key derivation is used. The OUT buffer must be deallocated by the caller.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
key: key to verify checksum with.
keyusage: integer specifying what this key is used for.
cksumtype: the checksum algorithm to use.
in: input array with data that was integrity protected.
inlen: size of input array with data that was integrity protected.
cksum: input array with alleged checksum of data.
cksumlen: size of input array with alleged checksum of data.
Description: Verify checksum of data using key, possibly altered by supplied key usage. If key usage is 0, no key derivation is used.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
key: key to encrypt with.
keyusage: integer specifying what this key is encrypting.
etype: integer specifying what cipher to use.
iv: input array with initialization vector
ivlen: size of input array with initialization vector.
ivout: output array with newly allocated updated initialization vector.
ivoutlen: size of output array with updated initialization vector.
in: input array with data to encrypt.
inlen: size of input array with data to encrypt.
out: output array with newly allocated encrypted data.
outlen: output variable with size of newly allocated output array.
Description: Encrypts data as per encryption method using specified initialization vector and key. The key actually used is derived using the key usage. If key usage is 0, no key derivation is used. The OUT buffer must be deallocated by the caller. If IVOUT or IVOUTLEN is NULL, the updated IV is not saved anywhere.
Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data exactly. Some encryption types add pad to make the data fit into the block size of the encryption algorithm. Furthermore, the pad is not guaranteed to look in any special way, although existing implementations often pad with the zero byte. This means that you may have to "frame" data, so it is possible to infer the original length after decryption. Compare ASN.1 DER which contains such information.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
key: key to encrypt with.
keyusage: integer specifying what this key is encrypting.
etype: integer specifying what cipher to use.
iv: input array with initialization vector
ivlen: size of input array with initialization vector.
in: input array with data to encrypt.
inlen: size of input array with data to encrypt.
out: output array with newly allocated encrypted data.
outlen: output variable with size of newly allocated output array.
Description: Encrypts data as per encryption method using specified initialization vector and key. The key actually used is derived using the key usage. If key usage is 0, no key derivation is used. The OUT buffer must be deallocated by the caller. The next IV is lost, see shishi_encrypt_ivupdate_etype if you need it.
Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data exactly. Some encryption types add pad to make the data fit into the block size of the encryption algorithm. Furthermore, the pad is not guaranteed to look in any special way, although existing implementations often pad with the zero byte. This means that you may have to "frame" data, so it is possible to infer the original length after decryption. Compare ASN.1 DER which contains such information.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
key: key to encrypt with.
keyusage: integer specifying what this key is encrypting.
etype: integer specifying what cipher to use.
in: input array with data to encrypt.
inlen: size of input array with data to encrypt.
out: output array with newly allocated encrypted data.
outlen: output variable with size of newly allocated output array.
Description: Encrypts data as per encryption method using specified initialization vector and key. The key actually used is derived using the key usage. If key usage is 0, no key derivation is used. The OUT buffer must be deallocated by the caller. The default IV is used, see shishi_encrypt_iv_etype if you need to alter it. The next IV is lost, see shishi_encrypt_ivupdate_etype if you need it.
Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data exactly. Some encryption types add pad to make the data fit into the block size of the encryption algorithm. Furthermore, the pad is not guaranteed to look in any special way, although existing implementations often pad with the zero byte. This means that you may have to "frame" data, so it is possible to infer the original length after decryption. Compare ASN.1 DER which contains such information.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
key: key to encrypt with.
keyusage: integer specifying what this key is encrypting.
iv: input array with initialization vector
ivlen: size of input array with initialization vector.
ivout: output array with newly allocated updated initialization vector.
ivoutlen: size of output array with updated initialization vector.
in: input array with data to encrypt.
inlen: size of input array with data to encrypt.
out: output array with newly allocated encrypted data.
outlen: output variable with size of newly allocated output array.
Description: Encrypts data using specified initialization vector and key. The key actually used is derived using the key usage. If key usage is 0, no key derivation is used. The OUT buffer must be deallocated by the caller. If IVOUT or IVOUTLEN is NULL, the updated IV is not saved anywhere.
Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data exactly. Some encryption types add pad to make the data fit into the block size of the encryption algorithm. Furthermore, the pad is not guaranteed to look in any special way, although existing implementations often pad with the zero byte. This means that you may have to "frame" data, so it is possible to infer the original length after decryption. Compare ASN.1 DER which contains such information.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
key: key to encrypt with.
keyusage: integer specifying what this key is encrypting.
iv: input array with initialization vector
ivlen: size of input array with initialization vector.
in: input array with data to encrypt.
inlen: size of input array with data to encrypt.
out: output array with newly allocated encrypted data.
outlen: output variable with size of newly allocated output array.
Description: Encrypts data using specified initialization vector and key. The key actually used is derived using the key usage. If key usage is 0, no key derivation is used. The OUT buffer must be deallocated by the caller. The next IV is lost, see shishi_encrypt_ivupdate if you need it.
Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data exactly. Some encryption types add pad to make the data fit into the block size of the encryption algorithm. Furthermore, the pad is not guaranteed to look in any special way, although existing implementations often pad with the zero byte. This means that you may have to "frame" data, so it is possible to infer the original length after decryption. Compare ASN.1 DER which contains such information.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
key: key to encrypt with.
keyusage: integer specifying what this key is encrypting.
in: input array with data to encrypt.
inlen: size of input array with data to encrypt.
out: output array with newly allocated encrypted data.
outlen: output variable with size of newly allocated output array.
Description: Encrypts data using specified key. The key actually used is derived using the key usage. If key usage is 0, no key derivation is used. The OUT buffer must be deallocated by the caller. The default IV is used, see shishi_encrypt_iv if you need to alter it. The next IV is lost, see shishi_encrypt_ivupdate if you need it.
Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data exactly. Some encryption types add pad to make the data fit into the block size of the encryption algorithm. Furthermore, the pad is not guaranteed to look in any special way, although existing implementations often pad with the zero byte. This means that you may have to "frame" data, so it is possible to infer the original length after decryption. Compare ASN.1 DER which contains such information.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
key: key to decrypt with.
keyusage: integer specifying what this key is decrypting.
etype: integer specifying what cipher to use.
iv: input array with initialization vector
ivlen: size of input array with initialization vector.
ivout: output array with newly allocated updated initialization vector.
ivoutlen: size of output array with updated initialization vector.
in: input array with data to decrypt.
inlen: size of input array with data to decrypt.
out: output array with newly allocated decrypted data.
outlen: output variable with size of newly allocated output array.
Description: Decrypts data as per encryption method using specified initialization vector and key. The key actually used is derived using the key usage. If key usage is 0, no key derivation is used. The OUT buffer must be deallocated by the caller. If IVOUT or IVOUTLEN is NULL, the updated IV is not saved anywhere.
Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data exactly. Some encryption types add pad to make the data fit into the block size of the encryption algorithm. Furthermore, the pad is not guaranteed to look in any special way, although existing implementations often pad with the zero byte. This means that you may have to "frame" data, so it is possible to infer the original length after decryption. Compare ASN.1 DER which contains such information.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
key: key to decrypt with.
keyusage: integer specifying what this key is decrypting.
etype: integer specifying what cipher to use.
iv: input array with initialization vector
ivlen: size of input array with initialization vector.
in: input array with data to decrypt.
inlen: size of input array with data to decrypt.
out: output array with newly allocated decrypted data.
outlen: output variable with size of newly allocated output array.
Description: Decrypts data as per encryption method using specified initialization vector and key. The key actually used is derived using the key usage. If key usage is 0, no key derivation is used. The OUT buffer must be deallocated by the caller. The next IV is lost, see shishi_decrypt_ivupdate_etype if you need it.
Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data exactly. Some encryption types add pad to make the data fit into the block size of the encryption algorithm. Furthermore, the pad is not guaranteed to look in any special way, although existing implementations often pad with the zero byte. This means that you may have to "frame" data, so it is possible to infer the original length after decryption. Compare ASN.1 DER which contains such information.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
key: key to decrypt with.
keyusage: integer specifying what this key is decrypting.
etype: integer specifying what cipher to use.
in: input array with data to decrypt.
inlen: size of input array with data to decrypt.
out: output array with newly allocated decrypted data.
outlen: output variable with size of newly allocated output array.
Description: Decrypts data as per encryption method using specified key. The key actually used is derived using the key usage. If key usage is 0, no key derivation is used. The OUT buffer must be deallocated by the caller. The default IV is used, see shishi_decrypt_iv_etype if you need to alter it. The next IV is lost, see shishi_decrypt_ivupdate_etype if you need it.
Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data exactly. Some encryption types add pad to make the data fit into the block size of the encryption algorithm. Furthermore, the pad is not guaranteed to look in any special way, although existing implementations often pad with the zero byte. This means that you may have to "frame" data, so it is possible to infer the original length after decryption. Compare ASN.1 DER which contains such information.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
key: key to decrypt with.
keyusage: integer specifying what this key is decrypting.
iv: input array with initialization vector
ivlen: size of input array with initialization vector.
ivout: output array with newly allocated updated initialization vector.
ivoutlen: size of output array with updated initialization vector.
in: input array with data to decrypt.
inlen: size of input array with data to decrypt.
out: output array with newly allocated decrypted data.
outlen: output variable with size of newly allocated output array.
Description: Decrypts data using specified initialization vector and key. The key actually used is derived using the key usage. If key usage is 0, no key derivation is used. The OUT buffer must be deallocated by the caller. If IVOUT or IVOUTLEN is NULL, the updated IV is not saved anywhere.
Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data exactly. Some encryption types add pad to make the data fit into the block size of the encryption algorithm. Furthermore, the pad is not guaranteed to look in any special way, although existing implementations often pad with the zero byte. This means that you may have to "frame" data, so it is possible to infer the original length after decryption. Compare ASN.1 DER which contains such information.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
key: key to decrypt with.
keyusage: integer specifying what this key is decrypting.
iv: input array with initialization vector
ivlen: size of input array with initialization vector.
in: input array with data to decrypt.
inlen: size of input array with data to decrypt.
out: output array with newly allocated decrypted data.
outlen: output variable with size of newly allocated output array.
Description: Decrypts data using specified initialization vector and key. The key actually used is derived using the key usage. If key usage is 0, no key derivation is used. The OUT buffer must be deallocated by the caller. The next IV is lost, see shishi_decrypt_ivupdate_etype if you need it.
Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data exactly. Some encryption types add pad to make the data fit into the block size of the encryption algorithm. Furthermore, the pad is not guaranteed to look in any special way, although existing implementations often pad with the zero byte. This means that you may have to "frame" data, so it is possible to infer the original length after decryption. Compare ASN.1 DER which contains such information.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
key: key to decrypt with.
keyusage: integer specifying what this key is decrypting.
in: input array with data to decrypt.
inlen: size of input array with data to decrypt.
out: output array with newly allocated decrypted data.
outlen: output variable with size of newly allocated output array.
Description: Decrypts data specified key. The key actually used is derived using the key usage. If key usage is 0, no key derivation is used. The OUT buffer must be deallocated by the caller. The default IV is used, see shishi_decrypt_iv if you need to alter it. The next IV is lost, see shishi_decrypt_ivupdate if you need it.
Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data exactly. Some encryption types add pad to make the data fit into the block size of the encryption algorithm. Furthermore, the pad is not guaranteed to look in any special way, although existing implementations often pad with the zero byte. This means that you may have to "frame" data, so it is possible to infer the original length after decryption. Compare ASN.1 DER which contains such information.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
in: input array with data to decrypt.
inlen: size of input array with data to decrypt ("M").
out: output array with decrypted data.
outlen: size of output array ("N").
Description: Fold data into a fixed length output array, with the intent to give each input bit approximately equal weight in determining the value of each output bit.
The algorithm is from "A Better Key Schedule For DES-like Ciphers" by Uri Blumenthal and Steven M. Bellovin, http://www.research.att.com/~smb/papers/ides.pdf, although the sample vectors provided by the paper are incorrect.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
key: input array with cryptographic key to use.
prfconstant: input array with the constant string.
prfconstantlen: size of input array with the constant string.
derivedrandom: output array with derived random data.
derivedrandomlen: size of output array with derived random data.
Description: Derive "random" data from a key and a constant thusly: DR(KEY, PRFCONSTANT) = TRUNCATE(DERIVEDRANDOMLEN, SHISHI_ENCRYPT(KEY, PRFCONSTANT)).
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
key: input cryptographic key to use.
prfconstant: input array with the constant string.
prfconstantlen: size of input array with the constant string.
derivedkey: pointer to derived key (allocated by caller).
Derive a key from a key and a constant thusly: DK(KEY, PRFCONSTANT) = SHISHI_RANDOM-TO-KEY(SHISHI_DR(KEY, PRFCONSTANT)).
Return value: Returns SHISHI_OK iff successful.
An easier way to use encryption and decryption if your application
repeatedly calls, e.g., shishi_encrypt_ivupdate, is to use the
following functions. They store the key, initialization vector, etc,
in a context, and the encryption and decryption operations update the
IV within the context automatically.
handle: shishi handle as allocated by shishi_init().
key: key to encrypt with.
keyusage: integer specifying what this key will encrypt/decrypt.
etype: integer specifying what cipher to use.
iv: input array with initialization vector
ivlen: size of input array with initialization vector.
Description: Initialize a crypto context. This store a key, keyusage,
encryption type and initialization vector in a "context", and the
caller can then use this context to perform encryption via
shishi_crypto_encrypt() and decryption via shishi_crypto_encrypt()
without supplying all those details again. The functions also
takes care of propagating the IV between calls.
When the application no longer need to use the context, it should
deallocate resources associated with it by calling
shishi_crypto_close().
Return value: Return a newly allocated crypto context.
ctx: crypto context as returned by shishi_crypto().
in: input array with data to encrypt.
inlen: size of input array with data to encrypt.
out: output array with newly allocated encrypted data.
outlen: output variable with size of newly allocated output array.
Description: Encrypt data, using information (e.g., key and initialization vector) from context. The IV is updated inside the context after this call.
When the application no longer need to use the context, it should
deallocate resources associated with it by calling
shishi_crypto_close().
Return value: Returns SHISHI_OK iff successful.
ctx: crypto context as returned by shishi_crypto().
in: input array with data to decrypt.
inlen: size of input array with data to decrypt.
out: output array with newly allocated decrypted data.
outlen: output variable with size of newly allocated output array.
Description: Decrypt data, using information (e.g., key and initialization vector) from context. The IV is updated inside the context after this call.
When the application no longer need to use the context, it should
deallocate resources associated with it by calling
shishi_crypto_close().
Return value: Returns SHISHI_OK iff successful.
ctx: crypto context as returned by shishi_crypto().
Description: Deallocate resources associated with the crypto context.
Also included in Shishi is an interface to the really low-level cryptographic primitives. They map directly on the underlying cryptographic library used (i.e., Gnulib or Libgcrypt) and is used internally by Shishi.
handle: shishi handle as allocated by shishi_init().
strong: 0 iff operation should not block, non-0 for very strong randomness.
data: output array to be filled with random data.
datalen: size of output array.
Description: Store cryptographically random data of given size in the provided buffer.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
in: input character array of data to checksum.
inlen: length of input character array of data to checksum.
out: newly allocated character array with checksum of data.
Description: Compute checksum of data using CRC32 modified according to RFC 1510. The out buffer must be deallocated by the caller.
The modifications compared to standard CRC32 is that no initial and final XOR is performed, and that the output is returned in LSB-first order.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
in: input character array of data to hash.
inlen: length of input character array of data to hash.
out: newly allocated character array with hash of data.
Description: Compute hash of data using MD4. The out buffer must be deallocated by the caller.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
in: input character array of data to hash.
inlen: length of input character array of data to hash.
out: newly allocated character array with hash of data.
Description: Compute hash of data using MD5. The out buffer must be deallocated by the caller.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
key: input character array with key to use.
keylen: length of input character array with key to use.
in: input character array of data to hash.
inlen: length of input character array of data to hash.
outhash: newly allocated character array with keyed hash of data.
Description: Compute keyed checksum of data using HMAC-MD5. The outhash buffer must be deallocated by the caller.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
key: input character array with key to use.
keylen: length of input character array with key to use.
in: input character array of data to hash.
inlen: length of input character array of data to hash.
outhash: newly allocated character array with keyed hash of data.
Description: Compute keyed checksum of data using HMAC-SHA1. The outhash buffer must be deallocated by the caller.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
key: input character array with key to use.
iv: input character array with initialization vector to use, can be NULL.
in: input character array of data to hash.
inlen: length of input character array of data to hash.
out: newly allocated character array with keyed hash of data.
Description: Computed keyed checksum of data using DES-CBC-MAC. The out buffer must be deallocated by the caller.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
decryptp: 0 to indicate encryption, non-0 to indicate decryption.
key: input character array with key to use.
keylen: length of input key array.
iv: input character array with initialization vector to use, or NULL.
ivout: output character array with updated initialization vector, or NULL.
in: input character array of data to encrypt/decrypt.
inlen: length of input character array of data to encrypt/decrypt.
out: newly allocated character array with encrypted/decrypted data.
Description: Encrypt or decrypt data (depending on decryptp) using ARCFOUR. The out buffer must be deallocated by the caller.
The "initialization vector" used here is the concatenation of the sbox and i and j, and is thus always of size 256 + 1 + 1. This is a slight abuse of terminology, and assumes you know what you are doing. Don’t use it if you can avoid to.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
decryptp: 0 to indicate encryption, non-0 to indicate decryption.
key: input character array with key to use.
iv: input character array with initialization vector to use, or NULL.
ivout: output character array with updated initialization vector, or NULL.
in: input character array of data to encrypt/decrypt.
inlen: length of input character array of data to encrypt/decrypt.
out: newly allocated character array with encrypted/decrypted data.
Description: Encrypt or decrypt data (depending on decryptp) using DES in CBC mode. The out buffer must be deallocated by the caller.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
decryptp: 0 to indicate encryption, non-0 to indicate decryption.
key: input character array with key to use.
iv: input character array with initialization vector to use, or NULL.
ivout: output character array with updated initialization vector, or NULL.
in: input character array of data to encrypt/decrypt.
inlen: length of input character array of data to encrypt/decrypt.
out: newly allocated character array with encrypted/decrypted data.
Description: Encrypt or decrypt data (depending on decryptp) using 3DES in CBC mode. The out buffer must be deallocated by the caller.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
decryptp: 0 to indicate encryption, non-0 to indicate decryption.
key: input character array with key to use.
keylen: length of input character array with key to use.
iv: input character array with initialization vector to use, or NULL.
ivout: output character array with updated initialization vector, or NULL.
in: input character array of data to encrypt/decrypt.
inlen: length of input character array of data to encrypt/decrypt.
out: newly allocated character array with encrypted/decrypted data.
Description: Encrypt or decrypt data (depending on decryptp) using AES in CBC-CTS mode. The length of the key, keylen, decide if AES 128 or AES 256 should be used. The out buffer must be deallocated by the caller.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
P: input password, an octet string
Plen: length of password, an octet string
S: input salt, an octet string
Slen: length of salt, an octet string
c: iteration count, a positive integer
dkLen: intended length in octets of the derived key, a positive integer,
at most (2^32 - 1) * hLen. The DK array must have room for this many
characters.
DK: output derived key, a dkLen-octet string
Description: Derive key using the PBKDF2 defined in PKCS5. PBKDF2 applies a pseudorandom function to derive keys. The length of the derived key is essentially unbounded. (However, the maximum effective search space for the derived key may be limited by the structure of the underlying pseudorandom function, which is this function is always SHA1.)
Return value: Returns SHISHI_OK iff successful.
Next: X.509 Functions, Previous: KRB-ERROR Functions, Up: Programming Manual [Contents][Index]