struct Shishi_key
{
  int type;    /* RFC 1510 encryption integer type */
  char *value; /* Cryptographic key data */
  int version; /* RFC 1510 ``kvno'' */
};

— Function: const char * shishi_key_principal (Shishi_key * key)

key: structure that holds key information

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.)

— Function: void shishi_key_principal_set (Shishi_key * key, const char * principal)

key: structure that holds key information

principal: string with new principal name.

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.

— Function: const char * shishi_key_realm (Shishi_key * key)

key: structure that holds key information

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.)

— Function: void shishi_key_realm_set (Shishi_key * key, const char * realm)

key: structure that holds key information

realm: string with new realm name.

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.

— Function: int shishi_key_type (Shishi_key * key)

key: structure that holds key information

Get key type.

Return value: Returns the type of key as an integer as described in the standard.

— Function: void shishi_key_type_set (Shishi_key * key, int32_t type)

key: structure that holds key information

type: type to set in key.

Set the type of key in key structure.

— Function: char * shishi_key_value (Shishi_key * key)

key: structure that holds key information

Get the raw key bytes.

Return value: Returns the key value as a pointer which is valid throughout the lifetime of the key structure.

— Function: void shishi_key_value_set (Shishi_key * key, const char * value)

key: structure that holds key information

value: input array with key data.

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).

— Function: uint32_t shishi_key_version (Shishi_key * key)

key: structure that holds key information

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").

— Function: void shishi_key_version_set (Shishi_key * key, uint32_t kvno)

key: structure that holds key information

kvno: new version integer.

Set the version of key ("kvno") in key structure. Use UINT32_MAX for non-ptermanent keys.

— Function: const char * shishi_key_name (Shishi_key * key)

key: structure that holds key information

Calls shishi_cipher_name for key type.

Return value: Return name of key.

— Function: size_t shishi_key_length (Shishi_key * key)

key: structure that holds key information

Calls shishi_cipher_keylen for key type.

Return value: Returns the length of the key value.

— Function: int shishi_key (Shishi * handle, Shishi_key ** key)

handle: Shishi library handle create by shishi_init().

key: pointer to structure that will hold newly created key information

Create a new Key information structure.

Return value: Returns SHISHI_OK iff successful.

— Function: void shishi_key_done (Shishi_key * key)

key: pointer to structure that holds key information.

Deallocates key information structure.

— Function: void shishi_key_copy (Shishi_key * dstkey, Shishi_key * srckey)

dstkey: structure that holds destination key information

srckey: structure that holds source key information

Copies source key into existing allocated destination key.

— Function: int shishi_key_from_value (Shishi * handle, int32_t type, const char * value, Shishi_key ** 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

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.

— Function: int shishi_key_from_base64 (Shishi * handle, int32_t type, const char * value, Shishi_key ** key)

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

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.

— Function: int shishi_key_random (Shishi * handle, int32_t type, Shishi_key ** key)

handle: Shishi library handle create by shishi_init().

type: type of key.

key: pointer to structure that will hold newly created key information

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.

— Function: int shishi_key_from_random (Shishi * handle, int32_t type, const char * rnd, size_t rndlen, Shishi_key ** outkey)

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

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.

— Function: int shishi_key_from_string (Shishi * handle, int32_t type, const char * password, size_t passwordlen, const char * salt, size_t saltlen, const char * parameter, Shishi_key ** outkey)

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

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.

— Function: int shishi_key_from_name (Shishi * handle, int32_t type, const char * name, const char * password, size_t passwordlen, const char * parameter, Shishi_key ** outkey)

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

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.

— Function: int shishi_keys (Shishi * handle, Shishi_keys ** keys)

handle: shishi handle as allocated by shishi_init().

keys: output pointer to newly allocated keys handle.

Get a new key set handle.

Return value: Returns SHISHI_OK iff successful.

— Function: void shishi_keys_done (Shishi_keys ** keys)

keys: key set handle as allocated by shishi_keys().

Deallocates all resources associated with key set. The key set handle must not be used in calls to other shishi_keys_*() functions after this.

— Function: int shishi_keys_size (Shishi_keys * keys)

keys: key set handle as allocated by shishi_keys().

Get size of key set.

Return value: Returns number of keys stored in key set.

— Function: const Shishi_key * shishi_keys_nth (Shishi_keys * keys, int keyno)

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.

— Function: void shishi_keys_remove (Shishi_keys * keys, int keyno)

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.

Remove a key, indexed by keyno, in given key set.

— Function: int shishi_keys_add (Shishi_keys * keys, Shishi_key * key)

keys: key set handle as allocated by shishi_keys().

key: key to be added to key set.

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 succesful.

— Function: int shishi_keys_add_keytab_mem (Shishi * handle, const char * data, size_t len, Shishi_keys * keys)

handle: shishi handle as allocated by shishi_init().

data: constant memory buffer with keytab of len size.

len: size of memory buffer with keytab data.

keys: allocated key set to store keys in.

Read keys from a MIT keytab data structure, and add them to the key set.

The format of keytab's is proprietary, and this function support the 0x0501 and 0x0502 formats. See the section The MIT Kerberos Keytab Binary File Format in the Shishi manual for a description of the reverse-engineered format.

Returns: Returns SHISHI_KEYTAB_ERROR if the data does not represent a valid keytab structure, and SHISHI_OK on success.

— Function: int shishi_keys_add_keytab_file (Shishi * handle, const char * filename, Shishi_keys * keys)

handle: shishi handle as allocated by shishi_init().

filename: name of file to read.

keys: allocated key set to store keys in.

Read keys from a MIT keytab data structure from a file, and add the keys to the key set.

The format of keytab's is proprietary, and this function support the 0x0501 and 0x0502 formats. See the section The MIT Kerberos Keytab Binary File Format in the Shishi manual for a description of the reverse-engineered format.

Returns: Returns SHISHI_IO_ERROR if the file cannot be read, SHISHI_KEYTAB_ERROR if the data cannot be parsed as a valid keytab structure, and SHISHI_OK on success.

— Function: int shishi_keys_from_keytab_mem (Shishi * handle, const char * data, size_t len, Shishi_keys ** outkeys)

handle: shishi handle as allocated by shishi_init().

data: constant memory buffer with keytab of len size.

len: size of memory buffer with keytab data.

outkeys: pointer to key set that will be allocated and populated, must be deallocated by caller on succes.

Create a new key set populated with keys from a MIT keytab data structure read from a memory block.

The format of keytab's is proprietary, and this function support the 0x0501 and 0x0502 formats. See the section The MIT Kerberos Keytab Binary File Format in the Shishi manual for a description of the reverse-engineered format.

Returns: Returns SHISHI_KEYTAB_ERROR if the data does not represent a valid keytab structure, and SHISHI_OK on success.

— Function: int shishi_keys_from_keytab_file (Shishi * handle, const char * filename, Shishi_keys ** outkeys)

handle: shishi handle as allocated by shishi_init().

filename: name of file to read.

outkeys: pointer to key set that will be allocated and populated, must be deallocated by caller on succes.

Create a new key set populated with keys from a MIT keytab data structure read from a file.

The format of keytab's is proprietary, and this function support the 0x0501 and 0x0502 formats. See the section The MIT Kerberos Keytab Binary File Format in the Shishi manual for a description of the reverse-engineered format.

Returns: Returns SHISHI_IO_ERROR if the file cannot be read, SHISHI_KEYTAB_ERROR if the data cannot be parsed as a valid keytab structure, and SHISHI_OK on success.

— Function: int shishi_keys_print (Shishi_keys * keys, FILE * fh)

keys: key set to print.

fh: file handle, open for writing, to print keys to.

Print all keys in set using shishi_key_print.

Returns: Returns SHISHI_OK on success.

— Function: int shishi_keys_to_file (Shishi * handle, const char * filename, Shishi_keys * keys)

handle: shishi handle as allocated by shishi_init().

filename: filename to append key to.

keys: set of keys to print.

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.

— Function: Shishi_key * shishi_keys_for_serverrealm_in_file (Shishi * handle, const char * filename, const char * server, const char * realm)

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.

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.

— Function: Shishi_key * shishi_keys_for_server_in_file (Shishi * handle, const char * filename, const char * server)

handle: Shishi library handle create by shishi_init().

filename: file to read keys from.

server: server name to get key for.

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.

— Function: Shishi_key * shishi_keys_for_localservicerealm_in_file (Shishi * handle, const char * filename, const char * service, const char * realm)

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.

Get key for specified service and realm from filename.

Return value: Returns the key for the server "SERVICE/HOSTNAMEREALM" (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.

— Function: const char * shishi_hostkeys_default_file (Shishi * handle)

handle: Shishi library handle create by shishi_init().

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.)

— Function: void shishi_hostkeys_default_file_set (Shishi * handle, const char * hostkeysfile)

handle: Shishi library handle create by shishi_init().

hostkeysfile: string with new default hostkeys file name, or NULL to reset to default.

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.

— Function: Shishi_key * shishi_hostkeys_for_server (Shishi * handle, const char * server)

handle: Shishi library handle create by shishi_init().

server: server name to get key for

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.

— Function: Shishi_key * shishi_hostkeys_for_serverrealm (Shishi * handle, const char * server, const char * realm)

handle: Shishi library handle create by shishi_init().

server: server name to get key for

realm: realm of server to get key for.

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.

— Function: Shishi_key * shishi_hostkeys_for_localservicerealm (Shishi * handle, const char * service, const char * realm)

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.

Get host key for service on current host in realm.

Return value: Returns the key for the server "SERVICE/HOSTNAMEREALM" (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.

— Function: Shishi_key * shishi_hostkeys_for_localservice (Shishi * handle, const char * service)

handle: Shishi library handle create by shishi_init().

service: service to get key for.

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.

— Function: int shishi_cipher_supported_p (int32_t type)

type: encryption type, see Shishi_etype.

Find out if cipher is supported.

Return value: Return 0 iff cipher is unsupported.

— Function: const char * shishi_cipher_name (int32_t type)

type: encryption type, see Shishi_etype.

Read humanly readable string for cipher.

Return value: Return name of encryption type, e.g. "des3-cbc-sha1-kd", as defined in the standards.

— Function: int shishi_cipher_blocksize (int32_t type)

type: encryption type, see Shishi_etype.

Get block size for cipher.

Return value: Return block size for encryption type, as defined in the standards.

— Function: int shishi_cipher_confoundersize (int32_t type)

type: encryption type, see Shishi_etype.

Get length of confounder for cipher.

Return value: Returns the size of the confounder (random data) for encryption type, as defined in the standards.

— Function: size_t shishi_cipher_keylen (int32_t type)

type: encryption type, see Shishi_etype.

Get key length for cipher.

Return value: Return length of key used for the encryption type, as defined in the standards.

— Function: size_t shishi_cipher_randomlen (int32_t type)

type: encryption type, see Shishi_etype.

Get length of random data for cipher.

Return value: Return length of random used for the encryption type, as defined in the standards.

— Function: int shishi_cipher_defaultcksumtype (int32_t type)

type: encryption type, see Shishi_etype.

Get the default checksum associated with cipher.

Return value: Return associated checksum mechanism for the encryption type, as defined in the standards.

— Function: int shishi_cipher_parse (const char * cipher)

cipher: name of encryption type, e.g. "des3-cbc-sha1-kd".

Get cipher number by parsing string.

Return value: Return encryption type corresponding to a string.

— Function: int shishi_checksum_supported_p (int32_t type)

type: checksum type, see Shishi_cksumtype.

Find out whether checksum is supported.

Return value: Return 0 iff checksum is unsupported.

— Function: const char * shishi_checksum_name (int32_t type)

type: checksum type, see Shishi_cksumtype.

Get name of checksum.

Return value: Return name of checksum type, e.g. "hmac-sha1-96-aes256", as defined in the standards.

— Function: size_t shishi_checksum_cksumlen (int32_t type)

type: checksum type, see Shishi_cksumtype.

Get length of checksum output.

Return value: Return length of checksum used for the checksum type, as defined in the standards.

— Function: int shishi_checksum_parse (const char * checksum)

checksum: name of checksum type, e.g. "hmac-sha1-96-aes256".

Get checksum number by parsing a string.

Return value: Return checksum type, see Shishi_cksumtype, corresponding to a string.

— Function: int shishi_string_to_key (Shishi * handle, int32_t keytype, const char * password, size_t passwordlen, const char * salt, size_t saltlen, const char * parameter, Shishi_key * outkey)

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.

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.

— Function: int shishi_random_to_key (Shishi * handle, int32_t keytype, const char * rnd, size_t rndlen, Shishi_key * outkey)

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.

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.

— Function: int shishi_checksum (Shishi * handle, Shishi_key * key, int keyusage, int cksumtype, const char * in, size_t inlen, char ** out, size_t * outlen)

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.

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.

— Function: int shishi_verify (Shishi * handle, Shishi_key * key, int keyusage, int cksumtype, const char * in, size_t inlen, const char * cksum, size_t cksumlen)

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.

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.

— Function: int shishi_encrypt_ivupdate_etype (Shishi * handle, Shishi_key * key, int keyusage, int32_t etype, const char * iv, size_t ivlen, char ** ivout, size_t * ivoutlen, const char * in, size_t inlen, char ** out, size_t * outlen)

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.

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.

— Function: int shishi_encrypt_iv_etype (Shishi * handle, Shishi_key * key, int keyusage, int32_t etype, const char * iv, size_t ivlen, const char * in, size_t inlen, char ** out, size_t * outlen)

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.

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.

— Function: int shishi_encrypt_etype (Shishi * handle, Shishi_key * key, int keyusage, int32_t etype, const char * in, size_t inlen, char ** out, size_t * outlen)

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.

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.

— Function: int shishi_encrypt_ivupdate (Shishi * handle, Shishi_key * key, int keyusage, const char * iv, size_t ivlen, char ** ivout, size_t * ivoutlen, const char * in, size_t inlen, char ** out, size_t * outlen)

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.

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.

— Function: int shishi_encrypt_iv (Shishi * handle, Shishi_key * key, int keyusage, const char * iv, size_t ivlen, const char * in, size_t inlen, char ** out, size_t * outlen)

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.

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.

— Function: int shishi_encrypt (Shishi * handle, Shishi_key * key, int keyusage, char * in, size_t inlen, char ** out, size_t * outlen)

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.

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.

— Function: int shishi_decrypt_ivupdate_etype (Shishi * handle, Shishi_key * key, int keyusage, int32_t etype, const char * iv, size_t ivlen, char ** ivout, size_t * ivoutlen, const char * in, size_t inlen, char ** out, size_t * outlen)

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.

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.

— Function: int shishi_decrypt_iv_etype (Shishi * handle, Shishi_key * key, int keyusage, int32_t etype, const char * iv, size_t ivlen, const char * in, size_t inlen, char ** out, size_t * outlen)

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.

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.

— Function: int shishi_decrypt_etype (Shishi * handle, Shishi_key * key, int keyusage, int32_t etype, const char * in, size_t inlen, char ** out, size_t * outlen)

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.

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.

— Function: int shishi_decrypt_ivupdate (Shishi * handle, Shishi_key * key, int keyusage, const char * iv, size_t ivlen, char ** ivout, size_t * ivoutlen, const char * in, size_t inlen, char ** out, size_t * outlen)

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.

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.

— Function: int shishi_decrypt_iv (Shishi * handle, Shishi_key * key, int keyusage, const char * iv, size_t ivlen, const char * in, size_t inlen, char ** out, size_t * outlen)

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.

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.

— Function: int shishi_decrypt (Shishi * handle, Shishi_key * key, int keyusage, const char * in, size_t inlen, char ** out, size_t * outlen)

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.

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.

— Function: int shishi_n_fold (Shishi * handle, const char * in, size_t inlen, char * out, size_t outlen)

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").

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, <URL: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.

— Function: int shishi_dr (Shishi * handle, Shishi_key * key, const char * constant, size_t constantlen, char * derivedrandom, size_t derivedrandomlen)

handle: shishi handle as allocated by shishi_init().

key: input array with cryptographic key to use.

constant: input array with the constant string.

constantlen: size of input array with the constant string.

derivedrandom: output array with derived random data.

derivedrandomlen: size of output array with derived random data.

Derive "random" data from a key and a constant thusly: DR(KEY, CONSTANT) = TRUNCATE(DERIVEDRANDOMLEN, SHISHI_ENCRYPT(KEY, CONSTANT)).

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_dk (Shishi * handle, Shishi_key * key, const char * constant, size_t constantlen, Shishi_key * derivedkey)

handle: shishi handle as allocated by shishi_init().

key: input cryptographic key to use.

constant: input array with the constant string.

constantlen: 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, CONSTANT) = SHISHI_RANDOM-TO-KEY(SHISHI_DR(KEY, CONSTANT)).

Return value: Returns SHISHI_OK iff successful.

— Function: Shishi_crypto * shishi_crypto (Shishi * handle, Shishi_key * key, int keyusage, int32_t etype, const char * iv, size_t ivlen)

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.

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_done().

Return value: Return a newly allocated crypto context.

— Function: int shishi_crypto_encrypt (Shishi_crypto * ctx, const char * in, size_t inlen, char ** out, size_t * outlen)

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.

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_done().

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_crypto_decrypt (Shishi_crypto * ctx, const char * in, size_t inlen, char ** out, size_t * outlen)

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.

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_done().

Return value: Returns SHISHI_OK iff successful.

— Function: void shishi_crypto_close (Shishi_crypto * ctx)

ctx: crypto context as returned by shishi_crypto().

Deallocate resources associated with the crypto context.

— Function: int shishi_randomize (Shishi * handle, int strong, void * data, size_t datalen)

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.

Store cryptographically random data of given size in the provided buffer.

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_crc (Shishi * handle, const char * in, size_t inlen, char * out[4])

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.

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.

— Function: int shishi_md4 (Shishi * handle, const char * in, size_t inlen, char * out[16])

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.

Compute hash of data using MD4. The out buffer must be deallocated by the caller.

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_md5 (Shishi * handle, const char * in, size_t inlen, char * out[16])

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.

Compute hash of data using MD5. The out buffer must be deallocated by the caller.

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_hmac_md5 (Shishi * handle, const char * key, size_t keylen, const char * in, size_t inlen, char * outhash[16])

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.

Compute keyed checksum of data using HMAC-MD5. The outhash buffer must be deallocated by the caller.

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_hmac_sha1 (Shishi * handle, const char * key, size_t keylen, const char * in, size_t inlen, char * outhash[20])

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.

Compute keyed checksum of data using HMAC-SHA1. The outhash buffer must be deallocated by the caller.

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_des_cbc_mac (Shishi * handle, const char key[8], const char iv[8], const char * in, size_t inlen, char * out[8])

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.

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.

— Function: int shishi_arcfour (Shishi * handle, int decryptp, const char * key, size_t keylen, const char iv[258], char * ivout[258], const char * in, size_t inlen, char ** out)

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.

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.

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.

— Function: int shishi_des (Shishi * handle, int decryptp, const char key[8], const char iv[8], char * ivout[8], const char * in, size_t inlen, char ** out)

handle: shishi handle as allocated by shishi_init().

decryptp: 0 to indicate encryption, non-0 to indicate decryption.

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.

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.

— Function: int shishi_3des (Shishi * handle, int decryptp, const char key[8], const char iv[8], char * ivout[8], const char * in, size_t inlen, char ** out)

handle: shishi handle as allocated by shishi_init().

decryptp: 0 to indicate encryption, non-0 to indicate decryption.

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.

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.

— Function: int shishi_aes_cts (Shishi * handle, int decryptp, const char * key, size_t keylen, const char iv[16], char * ivout[16], const char * in, size_t inlen, char ** out)

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.

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.

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.

— Function: int shishi_pbkdf2_sha1 (Shishi * handle, const char * P, size_t Plen, const char * S, size_t Slen, unsigned int c, unsigned int dkLen, char * DK)

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

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.