[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The cipher functions are used for symmetrical cryptography, i.e. cryptography using a shared key. The programming model follows an open/process/close paradigm and is in that similar to other building blocks provided by Libgcrypt.
5.1 Available ciphers | List of ciphers supported by the library. | |
5.2 Cipher modules | How to work with cipher modules. | |
5.3 Available cipher modes | List of cipher modes supported by the library. | |
5.4 Working with cipher handles | How to perform operations related to cipher handles. | |
5.5 General cipher functions | General cipher functions independent of cipher handles. |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GCRY_CIPHER_NONE
GCRY_CIPHER_IDEA
GCRY_CIPHER_3DES
GCRY_CIPHER_CAST5
GCRY_CIPHER_BLOWFISH
GCRY_CIPHER_SAFER_SK128
GCRY_CIPHER_DES_SK
GCRY_CIPHER_AES
GCRY_CIPHER_AES128
GCRY_CIPHER_RIJNDAEL
GCRY_CIPHER_RIJNDAEL128
GCRY_CIPHER_AES192
GCRY_CIPHER_RIJNDAEL128
GCRY_CIPHER_AES256
GCRY_CIPHER_RIJNDAEL256
GCRY_CIPHER_TWOFISH
GCRY_CIPHER_TWOFISH128
GCRY_CIPHER_ARCFOUR
GCRY_CIPHER_DES
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Libgcrypt makes it possible to load additional `cipher modules'; these cipher can be used just like the cipher algorithms that are built into the library directly. For an introduction into extension modules, see See section 3.2 Modules.
const char *name
const char **aliases
gcry_cipher_oid_spec_t *oids
size_t blocksize
size_t keylen
size_t contextsize
gcry_cipher_setkey_t setkey
gcry_cipher_encrypt_t encrypt
gcry_cipher_decrypt_t decrypt
gcry_cipher_stencrypt_t stencrypt
gcry_cipher_stdecrypt_t stdecrypt
const char *oid
int mode
Register a new cipher module whose specification can be found in cipher. On success, a new algorithm ID is stored in algorithm_id and a pointer representhing this module is stored in module.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GCRY_CIPHER_MODE_NONE
GCRY_CIPHER_MODE_ECB
GCRY_CIPHER_MODE_CFB
GCRY_CIPHER_MODE_CBC
GCRY_CIPHER_MODE_STREAM
GCRY_CIPHER_MODE_OFB
GCRY_CIPHER_MODE_CTR
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To use a cipher algorithm, you must first allocate an according handle. This is to be done using the open function:
This function creates the context handle required for most of the other cipher functions and returns a handle to it in `hd'. In case of an error, an according error code is returned.
The ID of algorithm to use must be specified via algo. See See section 5.1 Available ciphers, for a list of supported ciphers and the according constants.
Besides using the constants directly, the function
gcry_cipher_map_name
may be used to convert the textual name of
an algorithm into the according numeric ID.
The cipher mode to use must be specified via mode. See See section 5.3 Available cipher modes, for a list of supported cipher modes and the according constants. Note, that some modes do not work together with all algorithms.
The third argument flags can either be passed as 0
or as
the bit-wise OR of the following constants.
GCRY_CIPHER_SECURE
GCRY_CIPHER_ENABLE_SYNC
gcry_cipher_sync
.
GCRY_CIPHER_CBC_CTS
GCRY_CIPHER_CBC_MAC
Use the following function to release an existing handle:
This function releases the context created by gcry_cipher_open
.
In order to use a handle for performing cryptographic operations, a `key' has to be set first:
Set the key k used for encryption or decryption in the context denoted by the handle h. The length l of the key k must match the required length of the algorithm set for this context or be in the allowed range for algorithms with variable key size. The function checks this and returns an error if there is a problem. A caller should always check for an error.
Note, this is currently implemented as a macro but may be changed to a function in the future.
Most crypto modes requires an initialization vector (IV), which usually is a non-secret random string acting as a kind of salt value. The CTR mode requires a counter, which is also similar to a salt value. To set the IV or CTR, use these functions:
Set the initialization vector used for encryption or decryption. The vector is passed as the buffer K of length l and copied to internal data structures. The function checks that the IV matches the requirement of the selected algorithm and mode. Note, that this is implemented as a macro.
Set the counter vector used for encryption or decryption. The counter is passed as the buffer c of length l and copied to internal data structures. The function checks that the counter matches the requirement of the selected algorithm (i.e., it must be the same size as the block size). Note, that this is implemented as a macro.
Set the given handle's context back to the state it had after the last call to gcry_cipher_setkey and clear the initialization vector.
Note, that gcry_cipher_reset is implemented as a macro.
The actual encryption and decryption is done by using one of the following functions. They may be used as often as required to process all the data.
gcry_cipher_encrypt
is used to encrypt the data. This function
can either work in place or with two buffers. It uses the cipher
context already setup and described by the handle h. There are 2
ways to use the function: If in is passed as NULL
and
inlen is 0
, in-place encryption of the data in out or
length outsize takes place. With in being not NULL
,
inlen bytes are encrypted to the buffer out which must have
at least a size of inlen. outlen must be set to the
allocated size of out, so that the function can check that there
is sufficient space. Note, that overlapping buffers are not allowed.
Depending on the selected algorithms and encryption mode, the length of the buffers must be a multiple of the block size.
The function returns 0
on success or an error code.
gcry_cipher_decrypt
is used to decrypt the data. This function
can either work in place or with two buffers. It uses the cipher
context already setup and described by the handle h. There are 2
ways to use the function: If in is passed as NULL
and
inlen is 0
, in-place decryption of the data in out or
length outsize takes place. With in being not NULL
,
inlen bytes are decrypted to the buffer out which must have
at least a size of inlen. outlen must be set to the
allocated size of out, so that the function can check that there
is sufficient space. Note, that overlapping buffers are not allowed.
Depending on the selected algorithms and encryption mode, the length of the buffers must be a multiple of the block size.
The function returns 0
on success or an error code.
OpenPGP (as defined in RFC-2440) requires a special sync operation in some places, the following function is used for this:
Perform the OpenPGP sync operation on context h. Note, that this
is a no-op unless the context was created with the flag
GCRY_CIPHER_ENABLE_SYNC
Some of the described functions are implemented as macros utilizing a catch-all control function. This control function is rarely used directly but there is nothing which would inhibit it:
gcry_cipher_ctl
controls various aspects of the cipher module and
specific cipher contexts. Usually some more specialized functions or
macros are used for this purpose. The semantics of the function and its
parameters depends on the the command cmd and the passed context
handle h. Please see the comments in the source code
(src/global.c
) for details.
gcry_cipher_info
is used to retrieve various
information about a cipher context or the cipher module in general.
Currently no information is available.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To work with the algorithms, several functions are available to map algorithm names to the internal identifiers, as well as ways to retrieve information about an algorithm or the current cipher context.
This function is used to retrieve information on a specific algorithm. You pass the cipher algorithm ID as algo and the type of information requested as what. The result is either returned as the return code of the function or copied to the provided buffer whose allocated length must be available in an integer variable with the address passed in nbytes. This variable will also receive the actual used length of the buffer.
Here is a list of supported codes for what:
GCRYCTL_GET_KEYLEN:
GCRYCTL_GET_BLKLEN:
GCRYCTL_TEST_ALGO:
0
when the specified algorithm is available for use.
buffer and nbytes must be zero.
gcry_cipher_algo_name
returns a string with the name of the
cipher algorithm algo. If the algorithm is not known or another
error occurred, an empty string is returned. This function will never
return NULL
.
gcry_cipher_map_name
returns the algorithm identifier for the
cipher algorithm described by the string name. If this algorithm
is not available 0
is returned.
Return the cipher mode associated with an ASN.1 object
identifier. The object identifier is expected to be in the
IETF-style dotted decimal notation. The function returns
0
for an unknown object identifier or when no mode is associated
with it.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |