nettle: Cipher functions
1
1 6.2 Cipher functions
1 ====================
1
1 A “cipher” is a function that takes a message or “plaintext” and a
1 secret “key” and transforms it to a “ciphertext”. Given only the
1 ciphertext, but not the key, it should be hard to find the plaintext.
1 Given matching pairs of plaintext and ciphertext, it should be hard to
1 find the key.
1
1 There are two main classes of ciphers: Block ciphers and stream
1 ciphers.
1
1 A block cipher can process data only in fixed size chunks, called
1 “blocks”. Typical block sizes are 8 or 16 octets. To encrypt arbitrary
1 messages, you usually have to pad it to an integral number of blocks,
1 split it into blocks, and then process each block. The simplest way is
1 to process one block at a time, independent of each other. That mode of
1 operation is called “ECB”, Electronic Code Book mode. However, using
1 ECB is usually a bad idea. For a start, plaintext blocks that are equal
1 are transformed to ciphertext blocks that are equal; that leaks
1 information about the plaintext. Usually you should apply the cipher is
1 some “feedback mode”, “CBC” (Cipher Block Chaining) and “CTR” (Counter
1 mode) being two of of the most popular. See ⇒Cipher modes, for
1 information on how to apply CBC and CTR with Nettle.
1
1 A stream cipher can be used for messages of arbitrary length. A
1 typical stream cipher is a keyed pseudo-random generator. To encrypt a
1 plaintext message of N octets, you key the generator, generate N octets
1 of pseudo-random data, and XOR it with the plaintext. To decrypt,
1 regenerate the same stream using the key, XOR it to the ciphertext, and
1 the plaintext is recovered.
1
1 *Caution:* The first rule for this kind of cipher is the same as for
1 a One Time Pad: _never_ ever use the same key twice.
1
1 A common misconception is that encryption, by itself, implies
1 authentication. Say that you and a friend share a secret key, and you
1 receive an encrypted message. You apply the key, and get a plaintext
1 message that makes sense to you. Can you then be sure that it really
1 was your friend that wrote the message you’re reading? The answer is
1 no. For example, if you were using a block cipher in ECB mode, an
1 attacker may pick up the message on its way, and reorder, delete or
1 repeat some of the blocks. Even if the attacker can’t decrypt the
1 message, he can change it so that you are not reading the same message
1 as your friend wrote. If you are using a block cipher in CBC mode
1 rather than ECB, or are using a stream cipher, the possibilities for
1 this sort of attack are different, but the attacker can still make
1 predictable changes to the message.
1
1 It is recommended to _always_ use an authentication mechanism in
1 addition to encrypting the messages. Popular choices are Message
1 Authentication Codes like HMAC-SHA1 (⇒Keyed hash functions), or
1 digital signatures like RSA.
1
1 Some ciphers have so called “weak keys”, keys that results in
1 undesirable structure after the key setup processing, and should be
1 avoided. In Nettle, most key setup functions have no return value, but
1 for ciphers with weak keys, the return value indicates whether or not
1 the given key is weak. For good keys, key setup returns 1, and for weak
1 keys, it returns 0. When possible, avoid algorithms that have weak
1 keys. There are several good ciphers that don’t have any weak keys.
1
1 To encrypt a message, you first initialize a cipher context for
1 encryption or decryption with a particular key. You then use the
1 context to process plaintext or ciphertext messages. The initialization
1 is known as “key setup”. With Nettle, it is recommended to use each
1 context struct for only one direction, even if some of the ciphers use a
1 single key setup function that can be used for both encryption and
1 decryption.
1
1 6.2.1 AES
1 ---------
1
1 AES is a block cipher, specified by NIST as a replacement for the older
1 DES standard. The standard is the result of a competition between
1 cipher designers. The winning design, also known as RIJNDAEL, was
1 constructed by Joan Daemen and Vincent Rijnmen.
1
1 Like all the AES candidates, the winning design uses a block size of
1 128 bits, or 16 octets, and three possible key-size, 128, 192 and 256
1 bits (16, 24 and 32 octets) being the allowed key sizes. It does not
1 have any weak keys. Nettle defines AES in ‘<nettle/aes.h>’, and there
1 is one context struct for each key size. (Earlier versions of Nettle
1 used a single context struct, ‘struct aes_ctx’, for all key sizes. This
1 interface kept for backwards compatibility).
1
1 -- Context struct: struct aes128_ctx
1 -- Context struct: struct aes192_ctx
1 -- Context struct: struct aes256_ctx
1
1 -- Context struct: struct aes_ctx
1 Alternative struct, for the old AES interface.
1
1 -- Constant: AES_BLOCK_SIZE
1 The AES block-size, 16.
1
1 -- Constant: AES128_KEY_SIZE
1 -- Constant: AES192_KEY_SIZE
1 -- Constant: AES256_KEY_SIZE
1 -- Constant: AES_MIN_KEY_SIZE
1 -- Constant: AES_MAX_KEY_SIZE
1
1 -- Constant: AES_KEY_SIZE
1 Default AES key size, 32.
1
1 -- Function: void aes128_set_encrypt_key (struct aes128_ctx *CTX, const
1 uint8_t *KEY)
1 -- Function: void aes128_set_decrypt_key (struct aes128_ctx *CTX, const
1 uint8_t *KEY)
1 -- Function: void aes192_set_encrypt_key (struct aes192_ctx *CTX, const
1 uint8_t *KEY)
1 -- Function: void aes192_set_decrypt_key (struct aes192_ctx *CTX, const
1 uint8_t *KEY)
1 -- Function: void aes256_set_encrypt_key (struct aes256_ctx *CTX, const
1 uint8_t *KEY)
1 -- Function: void aes256_set_decrypt_key (struct aes256_ctx *CTX, const
1 uint8_t *KEY)
1 -- Function: void aes_set_encrypt_key (struct aes_ctx *CTX, size_t
1 LENGTH, const uint8_t *KEY)
1 -- Function: void aes_set_decrypt_key (struct aes_ctx *CTX, size_t
1 LENGTH, const uint8_t *KEY)
1 Initialize the cipher, for encryption or decryption, respectively.
1
1 -- Function: void aes128_invert_key (struct aes128_ctx *DST, const
1 struct aes128_ctx *SRC)
1 -- Function: void aes192_invert_key (struct aes192_ctx *DST, const
1 struct aes192_ctx *SRC)
1 -- Function: void aes256_invert_key (struct aes256_ctx *DST, const
1 struct aes256_ctx *SRC)
1 -- Function: void aes_invert_key (struct aes_ctx *DST, const struct
1 aes_ctx *SRC)
1 Given a context SRC initialized for encryption, initializes the
1 context struct DST for decryption, using the same key. If the same
1 context struct is passed for both ‘src’ and ‘dst’, it is converted
1 in place. These functions are mainly useful for applications which
1 needs to both encrypt and decrypt using the _same_ key, because
1 calling, e.g., ‘aes128_set_encrypt_key’ and ‘aes128_invert_key’, is
1 more efficient than calling ‘aes128_set_encrypt_key’ and
1 ‘aes128_set_decrypt_key’.
1
1 -- Function: void aes128_encrypt (struct aes128_ctx *CTX, size_t
1 LENGTH, uint8_t *DST, const uint8_t *SRC)
1 -- Function: void aes192_encrypt (struct aes192_ctx *CTX, size_t
1 LENGTH, uint8_t *DST, const uint8_t *SRC)
1 -- Function: void aes256_encrypt (struct aes256_ctx *CTX, size_t
1 LENGTH, uint8_t *DST, const uint8_t *SRC)
1 -- Function: void aes_encrypt (struct aes_ctx *CTX, size_t LENGTH,
1 uint8_t *DST, const uint8_t *SRC)
1 Encryption function. LENGTH must be an integral multiple of the
1 block size. If it is more than one block, the data is processed in
1 ECB mode. ‘src’ and ‘dst’ may be equal, but they must not overlap
1 in any other way.
1
1 -- Function: void aes128_decrypt (struct aes128_ctx *CTX, size_t
1 LENGTH, uint8_t *DST, const uint8_t *SRC)
1 -- Function: void aes192_decrypt (struct aes192_ctx *CTX, size_t
1 LENGTH, uint8_t *DST, const uint8_t *SRC)
1 -- Function: void aes256_decrypt (struct aes256_ctx *CTX, size_t
1 LENGTH, uint8_t *DST, const uint8_t *SRC)
1 -- Function: void aes_decrypt (struct aes_ctx *CTX, size_t LENGTH,
1 uint8_t *DST, const uint8_t *SRC)
1 Analogous to the encryption functions above.
1
1 6.2.2 ARCFOUR
1 -------------
1
1 ARCFOUR is a stream cipher, also known under the trade marked name RC4,
1 and it is one of the fastest ciphers around. A problem is that the key
1 setup of ARCFOUR is quite weak, you should never use keys with
1 structure, keys that are ordinary passwords, or sequences of keys like
1 “secret:1”, “secret:2”, .... If you have keys that don’t look like
1 random bit strings, and you want to use ARCFOUR, always hash the key
1 before feeding it to ARCFOUR. Furthermore, the initial bytes of the
1 generated key stream leak information about the key; for this reason, it
1 is recommended to discard the first 512 bytes of the key stream.
1
1 /* A more robust key setup function for ARCFOUR */
1 void
1 arcfour_set_key_hashed(struct arcfour_ctx *ctx,
1 size_t length, const uint8_t *key)
1 {
1 struct sha256_ctx hash;
1 uint8_t digest[SHA256_DIGEST_SIZE];
1 uint8_t buffer[0x200];
1
1 sha256_init(&hash);
1 sha256_update(&hash, length, key);
1 sha256_digest(&hash, SHA256_DIGEST_SIZE, digest);
1
1 arcfour_set_key(ctx, SHA256_DIGEST_SIZE, digest);
1 arcfour_crypt(ctx, sizeof(buffer), buffer, buffer);
1 }
1
1 Nettle defines ARCFOUR in ‘<nettle/arcfour.h>’.
1
1 -- Context struct: struct arcfour_ctx
1
1 -- Constant: ARCFOUR_MIN_KEY_SIZE
1 Minimum key size, 1.
1
1 -- Constant: ARCFOUR_MAX_KEY_SIZE
1 Maximum key size, 256.
1
1 -- Constant: ARCFOUR_KEY_SIZE
1 Default ARCFOUR key size, 16.
1
1 -- Function: void arcfour_set_key (struct arcfour_ctx *CTX, size_t
1 LENGTH, const uint8_t *KEY)
1 Initialize the cipher. The same function is used for both
1 encryption and decryption.
1
1 -- Function: void arcfour_crypt (struct arcfour_ctx *CTX, size_t
1 LENGTH, uint8_t *DST, const uint8_t *SRC)
1 Encrypt some data. The same function is used for both encryption
1 and decryption. Unlike the block ciphers, this function modifies
1 the context, so you can split the data into arbitrary chunks and
1 encrypt them one after another. The result is the same as if you
1 had called ‘arcfour_crypt’ only once with all the data.
1
1 6.2.3 ARCTWO
1 ------------
1
1 ARCTWO (also known as the trade marked name RC2) is a block cipher
1 specified in RFC 2268. Nettle also include a variation of the ARCTWO
1 set key operation that lack one step, to be compatible with the reverse
1 engineered RC2 cipher description, as described in a Usenet post to
1 ‘sci.crypt’ by Peter Gutmann.
1
1 ARCTWO uses a block size of 64 bits, and variable key-size ranging
1 from 1 to 128 octets. Besides the key, ARCTWO also has a second
1 parameter to key setup, the number of effective key bits, ‘ekb’. This
1 parameter can be used to artificially reduce the key size. In practice,
1 ‘ekb’ is usually set equal to the input key size. Nettle defines ARCTWO
1 in ‘<nettle/arctwo.h>’.
1
1 We do not recommend the use of ARCTWO; the Nettle implementation is
1 provided primarily for interoperability with existing applications and
1 standards.
1
1 -- Context struct: struct arctwo_ctx
1
1 -- Constant: ARCTWO_BLOCK_SIZE
1 The ARCTWO block-size, 8.
1
1 -- Constant: ARCTWO_MIN_KEY_SIZE
1
1 -- Constant: ARCTWO_MAX_KEY_SIZE
1
1 -- Constant: ARCTWO_KEY_SIZE
1 Default ARCTWO key size, 8.
1
1 -- Function: void arctwo_set_key_ekb (struct arctwo_ctx *CTX, size_t
1 LENGTH, const uint8_t *KEY, unsigned EKB)
1 -- Function: void arctwo_set_key (struct arctwo_ctx *CTX, size_t
1 LENGTH, const uint8_t *KEY)
1 -- Function: void arctwo_set_key_gutmann (struct arctwo_ctx *CTX,
1 size_t LENGTH, const uint8_t *KEY)
1 Initialize the cipher. The same function is used for both
1 encryption and decryption. The first function is the most general
1 one, which lets you provide both the variable size key, and the
1 desired effective key size (in bits). The maximum value for EKB is
1 1024, and for convenience, ‘ekb = 0’ has the same effect as ‘ekb =
1 1024’.
1
1 ‘arctwo_set_key(ctx, length, key)’ is equivalent to
1 ‘arctwo_set_key_ekb(ctx, length, key, 8*length)’, and
1 ‘arctwo_set_key_gutmann(ctx, length, key)’ is equivalent to
1 ‘arctwo_set_key_ekb(ctx, length, key, 1024)’
1
1 -- Function: void arctwo_encrypt (struct arctwo_ctx *CTX, size_t
1 LENGTH, uint8_t *DST, const uint8_t *SRC)
1 Encryption function. LENGTH must be an integral multiple of the
1 block size. If it is more than one block, the data is processed in
1 ECB mode. ‘src’ and ‘dst’ may be equal, but they must not overlap
1 in any other way.
1
1 -- Function: void arctwo_decrypt (struct arctwo_ctx *CTX, size_t
1 LENGTH, uint8_t *DST, const uint8_t *SRC)
1 Analogous to ‘arctwo_encrypt’
1
1 6.2.4 BLOWFISH
1 --------------
1
1 BLOWFISH is a block cipher designed by Bruce Schneier. It uses a block
1 size of 64 bits (8 octets), and a variable key size, up to 448 bits. It
1 has some weak keys. Nettle defines BLOWFISH in ‘<nettle/blowfish.h>’.
1
1 -- Context struct: struct blowfish_ctx
1
1 -- Constant: BLOWFISH_BLOCK_SIZE
1 The BLOWFISH block-size, 8.
1
1 -- Constant: BLOWFISH_MIN_KEY_SIZE
1 Minimum BLOWFISH key size, 8.
1
1 -- Constant: BLOWFISH_MAX_KEY_SIZE
1 Maximum BLOWFISH key size, 56.
1
1 -- Constant: BLOWFISH_KEY_SIZE
1 Default BLOWFISH key size, 16.
1
1 -- Function: int blowfish_set_key (struct blowfish_ctx *CTX, size_t
1 LENGTH, const uint8_t *KEY)
1 Initialize the cipher. The same function is used for both
1 encryption and decryption. Checks for weak keys, returning 1 for
1 good keys and 0 for weak keys. Applications that don’t care about
1 weak keys can ignore the return value.
1
1 ‘blowfish_encrypt’ or ‘blowfish_decrypt’ with a weak key will crash
1 with an assert violation.
1
1 -- Function: void blowfish_encrypt (struct blowfish_ctx *CTX, size_t
1 LENGTH, uint8_t *DST, const uint8_t *SRC)
1 Encryption function. LENGTH must be an integral multiple of the
1 block size. If it is more than one block, the data is processed in
1 ECB mode. ‘src’ and ‘dst’ may be equal, but they must not overlap
1 in any other way.
1
1 -- Function: void blowfish_decrypt (struct blowfish_ctx *CTX, size_t
1 LENGTH, uint8_t *DST, const uint8_t *SRC)
1 Analogous to ‘blowfish_encrypt’
1
1 6.2.5 Camellia
1 --------------
1
1 Camellia is a block cipher developed by Mitsubishi and Nippon Telegraph
1 and Telephone Corporation, described in ‘RFC3713’. It is recommended by
1 some Japanese and European authorities as an alternative to AES, and it
1 is one of the selected algorithms in the New European Schemes for
1 Signatures, Integrity and Encryption (NESSIE) project. The algorithm is
1 patented. The implementation in Nettle is derived from the
1 implementation released by NTT under the GNU LGPL (v2.1 or later), and
1 relies on the implicit patent license of the LGPL. There is also a
1 statement of royalty-free licensing for Camellia at
1 <http://www.ntt.co.jp/news/news01e/0104/010417.html>, but this statement
1 has some limitations which seem problematic for free software.
1
1 Camellia uses a the same block size and key sizes as AES: The block
1 size is 128 bits (16 octets), and the supported key sizes are 128, 192,
1 and 256 bits. The variants with 192 and 256 bit keys are identical,
1 except for the key setup. Nettle defines Camellia in
1 ‘<nettle/camellia.h>’, and there is one context struct for each key
1 size. (Earlier versions of Nettle used a single context struct, ‘struct
1 camellia_ctx’, for all key sizes. This interface kept for backwards
1 compatibility).
1
1 -- Context struct: struct camellia128_ctx
1 -- Context struct: struct camellia192_ctx
1 -- Context struct: struct camellia256_ctx
1 Contexts structs. Actually, ‘camellia192_ctx’ is an alias for
1 ‘camellia256_ctx’.
1
1 -- Context struct: struct camellia_ctx
1 Alternative struct, for the old Camellia interface.
1
1 -- Constant: CAMELLIA_BLOCK_SIZE
1 The CAMELLIA block-size, 16.
1
1 -- Constant: CAMELLIA128_KEY_SIZE
1 -- Constant: CAMELLIA192_KEY_SIZE
1 -- Constant: CAMELLIA256_KEY_SIZE
1 -- Constant: CAMELLIA_MIN_KEY_SIZE
1 -- Constant: CAMELLIA_MAX_KEY_SIZE
1
1 -- Constant: CAMELLIA_KEY_SIZE
1 Default CAMELLIA key size, 32.
1
1 -- Function: void camellia128_set_encrypt_key (struct camellia128_ctx
1 *CTX, const uint8_t *KEY)
1 -- Function: void camellia128_set_decrypt_key (struct camellia128_ctx
1 *CTX, const uint8_t *KEY)
1 -- Function: void camellia192_set_encrypt_key (struct camellia192_ctx
1 *CTX, const uint8_t *KEY)
1 -- Function: void camellia192_set_decrypt_key (struct camellia192_ctx
1 *CTX, const uint8_t *KEY)
1 -- Function: void camellia256_set_encrypt_key (struct camellia256_ctx
1 *CTX, const uint8_t *KEY)
1 -- Function: void camellia256_set_decrypt_key (struct camellia256_ctx
1 *CTX, const uint8_t *KEY)
1 -- Function: void camellia_set_encrypt_key (struct camellia_ctx *CTX,
1 size_t LENGTH, const uint8_t *KEY)
1 -- Function: void camellia_set_decrypt_key (struct camellia_ctx *CTX,
1 size_t LENGTH, const uint8_t *KEY)
1 Initialize the cipher, for encryption or decryption, respectively.
1
1 -- Function: void camellia128_invert_key (struct camellia128_ctx *DST,
1 const struct camellia128_ctx *SRC)
1 -- Function: void camellia192_invert_key (struct camellia192_ctx *DST,
1 const struct camellia192_ctx *SRC)
1 -- Function: void camellia256_invert_key (struct camellia256_ctx *DST,
1 const struct camellia256_ctx *SRC)
1 -- Function: void camellia_invert_key (struct camellia_ctx *DST, const
1 struct camellia_ctx *SRC)
1 Given a context SRC initialized for encryption, initializes the
1 context struct DST for decryption, using the same key. If the same
1 context struct is passed for both ‘src’ and ‘dst’, it is converted
1 in place. These functions are mainly useful for applications which
1 needs to both encrypt and decrypt using the _same_ key.
1
1 -- Function: void camellia128_crypt (struct camellia128_ctx *CTX,
1 size_t LENGTH, uint8_t *DST, const uint8_t *SRC)
1 -- Function: void camellia192_crypt (struct camellia192_ctx *CTX,
1 size_t LENGTH, uint8_t *DST, const uint8_t *SRC)
1 -- Function: void camellia256_crypt (struct camellia256_ctx *CTX,
1 size_t LENGTH, uint8_t *DST, const uint8_t *SRC)
1 -- Function: void camellia_crypt (struct camellia_ctx *CTX, size_t
1 LENGTH, uint8_t *DST, const uint8_t *SRC)
1 The same function is used for both encryption and decryption.
1 LENGTH must be an integral multiple of the block size. If it is
1 more than one block, the data is processed in ECB mode. ‘src’ and
1 ‘dst’ may be equal, but they must not overlap in any other way.
1
1 6.2.6 CAST128
1 -------------
1
1 CAST-128 is a block cipher, specified in ‘RFC 2144’. It uses a 64 bit
1 (8 octets) block size, and a variable key size of up to 128 bits.
1 Nettle defines cast128 in ‘<nettle/cast128.h>’.
1
1 -- Context struct: struct cast128_ctx
1
1 -- Constant: CAST128_BLOCK_SIZE
1 The CAST128 block-size, 8.
1
1 -- Constant: CAST128_MIN_KEY_SIZE
1 Minimum CAST128 key size, 5.
1
1 -- Constant: CAST128_MAX_KEY_SIZE
1 Maximum CAST128 key size, 16.
1
1 -- Constant: CAST128_KEY_SIZE
1 Default CAST128 key size, 16.
1
1 -- Function: void cast128_set_key (struct cast128_ctx *CTX, size_t
1 LENGTH, const uint8_t *KEY)
1 Initialize the cipher. The same function is used for both
1 encryption and decryption.
1
1 -- Function: void cast128_encrypt (struct cast128_ctx *CTX, size_t
1 LENGTH, uint8_t *DST, const uint8_t *SRC)
1 Encryption function. LENGTH must be an integral multiple of the
1 block size. If it is more than one block, the data is processed in
1 ECB mode. ‘src’ and ‘dst’ may be equal, but they must not overlap
1 in any other way.
1
1 -- Function: void cast128_decrypt (struct cast128_ctx *CTX, size_t
1 LENGTH, uint8_t *DST, const uint8_t *SRC)
1 Analogous to ‘cast128_encrypt’
1
1 6.2.7 ChaCha
1 ------------
1
1 ChaCha is a variant of the stream cipher Salsa20, also designed by D. J.
1 Bernstein. For more information on Salsa20, see below. Nettle defines
1 ChaCha in ‘<nettle/chacha.h>’.
1
1 -- Context struct: struct chacha_ctx
1
1 -- Constant: CHACHA_KEY_SIZE
1 ChaCha key size, 32.
1
1 -- Constant: CHACHA_BLOCK_SIZE
1 ChaCha block size, 64.
1
1 -- Constant: CHACHA_NONCE_SIZE
1 Size of the nonce, 8.
1
1 -- Function: void chacha_set_key (struct chacha_ctx *CTX, const uint8_t
1 *KEY)
1 Initialize the cipher. The same function is used for both
1 encryption and decryption. Before using the cipher, you _must_
1 also call ‘chacha_set_nonce’, see below.
1
1 -- Function: void chacha_set_nonce (struct chacha_ctx *CTX, const
1 uint8_t *NONCE)
1 Sets the nonce. It is always of size ‘CHACHA_NONCE_SIZE’, 8
1 octets. This function also initializes the block counter, setting
1 it to zero.
1
1 -- Function: void chacha_crypt (struct chacha_ctx *CTX, size_t LENGTH,
1 uint8_t *DST, const uint8_t *SRC)
1 Encrypts or decrypts the data of a message, using ChaCha. When a
1 message is encrypted using a sequence of calls to ‘chacha_crypt’,
1 all but the last call _must_ use a length that is a multiple of
1 ‘CHACHA_BLOCK_SIZE’.
1
1 6.2.8 DES
1 ---------
1
1 DES is the old Data Encryption Standard, specified by NIST. It uses a
1 block size of 64 bits (8 octets), and a key size of 56 bits. However,
1 the key bits are distributed over 8 octets, where the least significant
1 bit of each octet may be used for parity. A common way to use DES is to
1 generate 8 random octets in some way, then set the least significant bit
1 of each octet to get odd parity, and initialize DES with the resulting
1 key.
1
1 The key size of DES is so small that keys can be found by brute
1 force, using specialized hardware or lots of ordinary work stations in
1 parallel. One shouldn’t be using plain DES at all today, if one uses
1 DES at all one should be using “triple DES”, see DES3 below.
1
1 DES also has some weak keys. Nettle defines DES in ‘<nettle/des.h>’.
1
1 -- Context struct: struct des_ctx
1
1 -- Constant: DES_BLOCK_SIZE
1 The DES block-size, 8.
1
1 -- Constant: DES_KEY_SIZE
1 DES key size, 8.
1
1 -- Function: int des_set_key (struct des_ctx *CTX, const uint8_t *KEY)
1 Initialize the cipher. The same function is used for both
1 encryption and decryption. Parity bits are ignored. Checks for
1 weak keys, returning 1 for good keys and 0 for weak keys.
1 Applications that don’t care about weak keys can ignore the return
1 value.
1
1 -- Function: void des_encrypt (struct des_ctx *CTX, size_t LENGTH,
1 uint8_t *DST, const uint8_t *SRC)
1 Encryption function. LENGTH must be an integral multiple of the
1 block size. If it is more than one block, the data is processed in
1 ECB mode. ‘src’ and ‘dst’ may be equal, but they must not overlap
1 in any other way.
1
1 -- Function: void des_decrypt (struct des_ctx *CTX, size_t LENGTH,
1 uint8_t *DST, const uint8_t *SRC)
1 Analogous to ‘des_encrypt’
1
1 -- Function: int des_check_parity (size_t LENGTH, const uint8_t *KEY);
1 Checks that the given key has correct, odd, parity. Returns 1 for
1 correct parity, and 0 for bad parity.
1
1 -- Function: void des_fix_parity (size_t LENGTH, uint8_t *DST, const
1 uint8_t *SRC)
1 Adjusts the parity bits to match DES’s requirements. You need this
1 function if you have created a random-looking string by a key
1 agreement protocol, and want to use it as a DES key. DST and SRC
1 may be equal.
1
1 6.2.9 DES3
1 ----------
1
1 The inadequate key size of DES has already been mentioned. One way to
1 increase the key size is to pipe together several DES boxes with
1 independent keys. It turns out that using two DES ciphers is not as
1 secure as one might think, even if the key size of the combination is a
1 respectable 112 bits.
1
1 The standard way to increase DES’s key size is to use three DES
1 boxes. The mode of operation is a little peculiar: the middle DES box
1 is wired in the reverse direction. To encrypt a block with DES3, you
1 encrypt it using the first 56 bits of the key, then _decrypt_ it using
1 the middle 56 bits of the key, and finally encrypt it again using the
1 last 56 bits of the key. This is known as “ede” triple-DES, for
1 “encrypt-decrypt-encrypt”.
1
1 The “ede” construction provides some backward compatibility, as you
1 get plain single DES simply by feeding the same key to all three boxes.
1 That should help keeping down the gate count, and the price, of hardware
1 circuits implementing both plain DES and DES3.
1
1 DES3 has a key size of 168 bits, but just like plain DES, useless
1 parity bits are inserted, so that keys are represented as 24 octets (192
1 bits). As a 112 bit key is large enough to make brute force attacks
1 impractical, some applications uses a “two-key” variant of triple-DES.
1 In this mode, the same key bits are used for the first and the last DES
1 box in the pipe, while the middle box is keyed independently. The
1 two-key variant is believed to be secure, i.e. there are no known
1 attacks significantly better than brute force.
1
1 Naturally, it’s simple to implement triple-DES on top of Nettle’s DES
1 functions. Nettle includes an implementation of three-key “ede”
1 triple-DES, it is defined in the same place as plain DES,
1 ‘<nettle/des.h>’.
1
1 -- Context struct: struct des3_ctx
1
1 -- Constant: DES3_BLOCK_SIZE
1 The DES3 block-size is the same as DES_BLOCK_SIZE, 8.
1
1 -- Constant: DES3_KEY_SIZE
1 DES key size, 24.
1
1 -- Function: int des3_set_key (struct des3_ctx *CTX, const uint8_t
1 *KEY)
1 Initialize the cipher. The same function is used for both
1 encryption and decryption. Parity bits are ignored. Checks for
1 weak keys, returning 1 if all three keys are good keys, and 0 if
1 one or more key is weak. Applications that don’t care about weak
1 keys can ignore the return value.
1
1 For random-looking strings, you can use ‘des_fix_parity’ to adjust
1 the parity bits before calling ‘des3_set_key’.
1
1 -- Function: void des3_encrypt (struct des3_ctx *CTX, size_t LENGTH,
1 uint8_t *DST, const uint8_t *SRC)
1 Encryption function. LENGTH must be an integral multiple of the
1 block size. If it is more than one block, the data is processed in
1 ECB mode. ‘src’ and ‘dst’ may be equal, but they must not overlap
1 in any other way.
1
1 -- Function: void des3_decrypt (struct des3_ctx *CTX, size_t LENGTH,
1 uint8_t *DST, const uint8_t *SRC)
1 Analogous to ‘des_encrypt’
1
1 6.2.10 Salsa20
1 --------------
1
1 Salsa20 is a fairly recent stream cipher designed by D. J. Bernstein.
1 It is built on the observation that a cryptographic hash function can be
1 used for encryption: Form the hash input from the secret key and a
1 counter, xor the hash output and the first block of the plaintext, then
1 increment the counter to process the next block (similar to CTR mode,
1 see ⇒CTR). Bernstein defined an encryption algorithm, Snuffle,
1 in this way to ridicule United States export restrictions which treated
1 hash functions as nice and harmless, but ciphers as dangerous munitions.
1
1 Salsa20 uses the same idea, but with a new specialized hash function
1 to mix key, block counter, and a couple of constants. It’s also
1 designed for speed; on x86_64, it is currently the fastest cipher
1 offered by nettle. It uses a block size of 512 bits (64 octets) and
1 there are two specified key sizes, 128 and 256 bits (16 and 32 octets).
1
1 *Caution:* The hash function used in Salsa20 is _not_ directly
1 applicable for use as a general hash function. It’s _not_ collision
1 resistant if arbitrary inputs are allowed, and furthermore, the input
1 and output is of fixed size.
1
1 When using Salsa20 to process a message, one specifies both a key and
1 a “nonce”, the latter playing a similar rôle to the initialization
1 vector (IV) used with CBC or CTR mode. One can use the same key for
1 several messages, provided one uses a unique random iv for each message.
1 The iv is 64 bits (8 octets). The block counter is initialized to zero
1 for each message, and is also 64 bits (8 octets). Nettle defines
1 Salsa20 in ‘<nettle/salsa20.h>’.
1
1 -- Context struct: struct salsa20_ctx
1
1 -- Constant: SALSA20_128_KEY_SIZE
1 -- Constant: SALSA20_256_KEY_SIZE
1 The two supported key sizes, 16 and 32 octets.
1
1 -- Constant: SALSA20_KEY_SIZE
1 Recommended key size, 32.
1
1 -- Constant: SALSA20_BLOCK_SIZE
1 Salsa20 block size, 64.
1
1 -- Constant: SALSA20_NONCE_SIZE
1 Size of the nonce, 8.
1
1 -- Function: void salsa20_128_set_key (struct salsa20_ctx *CTX, const
1 uint8_t *KEY)
1 -- Function: void salsa20_256_set_key (struct salsa20_ctx *CTX, const
1 uint8_t *KEY)
1 -- Function: void salsa20_set_key (struct salsa20_ctx *CTX, size_t
1 LENGTH, const uint8_t *KEY)
1 Initialize the cipher. The same function is used for both
1 encryption and decryption. ‘salsa20_128_set_key’ and
1 ‘salsa20_128_set_key’ use a fix key size each, 16 and 32 octets,
1 respectively. The function ‘salsa20_set_key’ is provided for
1 backwards compatibility, and the LENGTH argument must be either 16
1 or 32. Before using the cipher, you _must_ also call
1 ‘salsa20_set_nonce’, see below.
1
1 -- Function: void salsa20_set_nonce (struct salsa20_ctx *CTX, const
1 uint8_t *NONCE)
1 Sets the nonce. It is always of size ‘SALSA20_NONCE_SIZE’, 8
1 octets. This function also initializes the block counter, setting
1 it to zero.
1
1 -- Function: void salsa20_crypt (struct salsa20_ctx *CTX, size_t
1 LENGTH, uint8_t *DST, const uint8_t *SRC)
1 Encrypts or decrypts the data of a message, using salsa20. When a
1 message is encrypted using a sequence of calls to ‘salsa20_crypt’,
1 all but the last call _must_ use a length that is a multiple of
1 ‘SALSA20_BLOCK_SIZE’.
1
1 The full salsa20 cipher uses 20 rounds of mixing. Variants of
1 Salsa20 with fewer rounds are possible, and the 12-round variant is
1 specified by eSTREAM, see
1 <http://www.ecrypt.eu.org/stream/finallist.html>. Nettle calls this
1 variant ‘salsa20r12’. It uses the same context struct and key setup as
1 the full salsa20 cipher, but a separate function for encryption and
1 decryption.
1
1 -- Function: void salsa20r12_crypt (struct salsa20_ctx *CTX, size_t
1 LENGTH, uint8_t *DST, const uint8_t *SRC)
1 Encrypts or decrypts the data of a message, using salsa20 reduced
1 to 12 rounds.
1
1 6.2.11 SERPENT
1 --------------
1
1 SERPENT is one of the AES finalists, designed by Ross Anderson, Eli
1 Biham and Lars Knudsen. Thus, the interface and properties are similar
1 to AES’. One peculiarity is that it is quite pointless to use it with
1 anything but the maximum key size, smaller keys are just padded to
1 larger ones. Nettle defines SERPENT in ‘<nettle/serpent.h>’.
1
1 -- Context struct: struct serpent_ctx
1
1 -- Constant: SERPENT_BLOCK_SIZE
1 The SERPENT block-size, 16.
1
1 -- Constant: SERPENT_MIN_KEY_SIZE
1 Minimum SERPENT key size, 16.
1
1 -- Constant: SERPENT_MAX_KEY_SIZE
1 Maximum SERPENT key size, 32.
1
1 -- Constant: SERPENT_KEY_SIZE
1 Default SERPENT key size, 32.
1
1 -- Function: void serpent_set_key (struct serpent_ctx *CTX, size_t
1 LENGTH, const uint8_t *KEY)
1 Initialize the cipher. The same function is used for both
1 encryption and decryption.
1
1 -- Function: void serpent_encrypt (struct serpent_ctx *CTX, size_t
1 LENGTH, uint8_t *DST, const uint8_t *SRC)
1 Encryption function. LENGTH must be an integral multiple of the
1 block size. If it is more than one block, the data is processed in
1 ECB mode. ‘src’ and ‘dst’ may be equal, but they must not overlap
1 in any other way.
1
1 -- Function: void serpent_decrypt (struct serpent_ctx *CTX, size_t
1 LENGTH, uint8_t *DST, const uint8_t *SRC)
1 Analogous to ‘serpent_encrypt’
1
1 6.2.12 TWOFISH
1 --------------
1
1 Another AES finalist, this one designed by Bruce Schneier and others.
1 Nettle defines it in ‘<nettle/twofish.h>’.
1
1 -- Context struct: struct twofish_ctx
1
1 -- Constant: TWOFISH_BLOCK_SIZE
1 The TWOFISH block-size, 16.
1
1 -- Constant: TWOFISH_MIN_KEY_SIZE
1 Minimum TWOFISH key size, 16.
1
1 -- Constant: TWOFISH_MAX_KEY_SIZE
1 Maximum TWOFISH key size, 32.
1
1 -- Constant: TWOFISH_KEY_SIZE
1 Default TWOFISH key size, 32.
1
1 -- Function: void twofish_set_key (struct twofish_ctx *CTX, size_t
1 LENGTH, const uint8_t *KEY)
1 Initialize the cipher. The same function is used for both
1 encryption and decryption.
1
1 -- Function: void twofish_encrypt (struct twofish_ctx *CTX, size_t
1 LENGTH, uint8_t *DST, const uint8_t *SRC)
1 Encryption function. LENGTH must be an integral multiple of the
1 block size. If it is more than one block, the data is processed in
1 ECB mode. ‘src’ and ‘dst’ may be equal, but they must not overlap
1 in any other way.
1
1 -- Function: void twofish_decrypt (struct twofish_ctx *CTX, size_t
1 LENGTH, uint8_t *DST, const uint8_t *SRC)
1 Analogous to ‘twofish_encrypt’
1
1 6.2.13 The ‘struct nettle_cipher’ abstraction
1 ---------------------------------------------
1
1 Nettle includes a struct including information about some of the more
1 regular cipher functions. It can be useful for applications that need a
1 simple way to handle various algorithms. Nettle defines these structs
1 in ‘<nettle/nettle-meta.h>’.
1
1 -- Meta struct: ‘struct nettle_cipher’ name context_size block_size
1 key_size set_encrypt_key set_decrypt_key encrypt decrypt
1 The last four attributes are function pointers, of types
1 ‘nettle_set_key_func *’ and ‘nettle_cipher_func *’. The first
1 argument to these functions is a ‘const void *’ pointer to a
1 context struct, which is of size ‘context_size’.
1
1 -- Constant Struct: struct nettle_cipher nettle_aes128
1 -- Constant Struct: struct nettle_cipher nettle_aes192
1 -- Constant Struct: struct nettle_cipher nettle_aes256
1
1 -- Constant Struct: struct nettle_cipher nettle_arctwo40
1 -- Constant Struct: struct nettle_cipher nettle_arctwo64
1 -- Constant Struct: struct nettle_cipher nettle_arctwo128
1 -- Constant Struct: struct nettle_cipher nettle_arctwo_gutmann128
1
1 -- Constant Struct: struct nettle_cipher nettle_arcfour128
1
1 -- Constant Struct: struct nettle_cipher nettle_camellia128
1 -- Constant Struct: struct nettle_cipher nettle_camellia192
1 -- Constant Struct: struct nettle_cipher nettle_camellia256
1
1 -- Constant Struct: struct nettle_cipher nettle_cast128
1
1 -- Constant Struct: struct nettle_cipher nettle_serpent128
1 -- Constant Struct: struct nettle_cipher nettle_serpent192
1 -- Constant Struct: struct nettle_cipher nettle_serpent256
1
1 -- Constant Struct: struct nettle_cipher nettle_twofish128
1 -- Constant Struct: struct nettle_cipher nettle_twofish192
1 -- Constant Struct: struct nettle_cipher nettle_twofish256
1 Nettle includes such structs for all the _regular_ ciphers, i.e.
1 ones without weak keys or other oddities.
1
1 Nettle also exports a list of all these ciphers without weak keys or
1 other oddities.
1
1 -- Function: const struct nettle_cipher **nettle_get_ciphers(void)
1 Returns a NULL-terminated list of pointers to supported block
1 ciphers. This list can be used to dynamically enumerate or search
1 the supported algorithms.
1
1 -- Macro: nettle_ciphers
1 A macro expanding to a call to nettle_get_ciphers. In earlier
1 versions, this was not a macro but the actual array of pointers.
1