Commit 2fdc023b authored by Niels Möller's avatar Niels Möller
Browse files

Update documentation for nettle_cipher_func.

parent 7153ad93
2014-04-26 Niels Möller <nisse@lysator.liu.se> 2014-04-26 Niels Möller <nisse@lysator.liu.se>
* nettle.texinfo (GCM): Document GCM_DIGEST_SIZE. * nettle.texinfo: Update for introduction of nettle_cipher_func.
(GCM): Document GCM_DIGEST_SIZE.
(UMAC): Document new UMAC constants. (UMAC): Document new UMAC constants.
(Keyed hash functions): Make HMAC and UMAC their own info nodes. (Keyed hash functions): Make HMAC and UMAC their own info nodes.
(EAX): Document EAX. (EAX): Document EAX.
......
...@@ -7,14 +7,14 @@ ...@@ -7,14 +7,14 @@
@syncodeindex fn cp @syncodeindex fn cp
@c %**end of header @c %**end of header
@set UPDATED-FOR 2.7 @set UPDATED-FOR 3.0
@set AUTHOR Niels Möller @set AUTHOR Niels Möller
@copying @copying
This manual is for the Nettle library (version @value{UPDATED-FOR}), a This manual is for the Nettle library (version @value{UPDATED-FOR}), a
low-level cryptographic library. low-level cryptographic library.
Originally written 2001 by @value{AUTHOR}, updated 2013. Originally written 2001 by @value{AUTHOR}, updated 2014.
@quotation @quotation
This manual is placed in the public domain. You may freely copy it, in This manual is placed in the public domain. You may freely copy it, in
...@@ -993,10 +993,10 @@ functions}). ...@@ -993,10 +993,10 @@ functions}).
@deftp {Meta struct} @code{struct nettle_hash} name context_size digest_size block_size init update digest @deftp {Meta struct} @code{struct nettle_hash} name context_size digest_size block_size init update digest
The last three attributes are function pointers, of types The last three attributes are function pointers, of types
@code{nettle_hash_init_func}, @code{nettle_hash_update_func}, and @code{nettle_hash_init_func *}, @code{nettle_hash_update_func *}, and
@code{nettle_hash_digest_func}. The first argument to these functions is @code{nettle_hash_digest_func *}. The first argument to these functions is
@code{void *} pointer to a context struct, which is of size @code{void *} pointer to a context struct, which is of size
@code{context_size}. @code{context_size}.
@end deftp @end deftp
@deftypevr {Constant Struct} {struct nettle_hash} nettle_md2 @deftypevr {Constant Struct} {struct nettle_hash} nettle_md2
...@@ -1756,15 +1756,14 @@ Analogous to @code{twofish_encrypt} ...@@ -1756,15 +1756,14 @@ Analogous to @code{twofish_encrypt}
@subsection @code{struct nettle_cipher} @subsection @code{struct nettle_cipher}
Nettle includes a struct including information about some of the more Nettle includes a struct including information about some of the more
regular cipher functions. It should be considered a little experimental, regular cipher functions. It can be useful for applications that need a
but can be useful for applications that need a simple way to handle simple way to handle various algorithms. Nettle defines these structs in
various algorithms. Nettle defines these structs in @file{<nettle/nettle-meta.h>}.
@file{<nettle/nettle-meta.h>}.
@deftp {Meta struct} @code{struct nettle_cipher} name context_size block_size key_size set_encrypt_key set_decrypt_key encrypt decrypt @deftp {Meta struct} @code{struct nettle_cipher} name context_size block_size key_size set_encrypt_key set_decrypt_key encrypt decrypt
The last four attributes are function pointers, of types The last four attributes are function pointers, of types
@code{nettle_set_key_func} and @code{nettle_crypt_func}. The first @code{nettle_set_key_func *} and @code{nettle_cipher_func *}. The first
argument to these functions is a @code{void *} pointer to a context argument to these functions is a @code{const void *} pointer to a context
struct, which is of size @code{context_size}. struct, which is of size @code{context_size}.
@end deftp @end deftp
...@@ -1868,8 +1867,8 @@ Block Chaining (@acronym{CBC}) mode, one for encryption and one for ...@@ -1868,8 +1867,8 @@ Block Chaining (@acronym{CBC}) mode, one for encryption and one for
decryption. These functions uses @code{void *} to pass cipher contexts decryption. These functions uses @code{void *} to pass cipher contexts
around. around.
@deftypefun {void} cbc_encrypt (void *@var{ctx}, nettle_crypt_func @var{f}, size_t @var{block_size}, uint8_t *@var{iv}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) @deftypefun {void} cbc_encrypt (const void *@var{ctx}, nettle_cipher_func *@var{f}, size_t @var{block_size}, uint8_t *@var{iv}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src})
@deftypefunx {void} cbc_decrypt (void *@var{ctx}, void (*@var{f})(), size_t @var{block_size}, uint8_t *@var{iv}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) @deftypefunx {void} cbc_decrypt (const void *@var{ctx}, nettle_cipher_func *@var{f}, size_t @var{block_size}, uint8_t *@var{iv}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src})
Applies the encryption or decryption function @var{f} in @acronym{CBC} Applies the encryption or decryption function @var{f} in @acronym{CBC}
mode. The final ciphertext block processed is copied into @var{iv} mode. The final ciphertext block processed is copied into @var{iv}
...@@ -1964,7 +1963,7 @@ similar rôle as the @acronym{IV} for @acronym{CBC}. When adding, ...@@ -1964,7 +1963,7 @@ similar rôle as the @acronym{IV} for @acronym{CBC}. When adding,
byte order. For the last block, @code{E_k(IC + n - 1) [1..m]} means that byte order. For the last block, @code{E_k(IC + n - 1) [1..m]} means that
the cipher output is truncated to @code{m} bytes. the cipher output is truncated to @code{m} bytes.
@deftypefun {void} ctr_crypt (void *@var{ctx}, nettle_crypt_func @var{f}, size_t @var{block_size}, uint8_t *@var{ctr}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) @deftypefun {void} ctr_crypt (const void *@var{ctx}, nettle_cipher_func *@var{f}, size_t @var{block_size}, uint8_t *@var{ctr}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src})
Applies the encryption function @var{f} in @acronym{CTR} mode. Note that Applies the encryption function @var{f} in @acronym{CTR} mode. Note that
for @acronym{CTR} mode, encryption and decryption is the same operation, for @acronym{CTR} mode, encryption and decryption is the same operation,
...@@ -2247,7 +2246,7 @@ Size of the @acronym{GCM} digest, also 16. ...@@ -2247,7 +2246,7 @@ Size of the @acronym{GCM} digest, also 16.
Recommended size of the @acronym{IV}, 12. Other sizes are allowed. Recommended size of the @acronym{IV}, 12. Other sizes are allowed.
@end defvr @end defvr
@deftypefun void gcm_set_key (struct gcm_key *@var{key}, void *@var{cipher}, nettle_crypt_func *@var{f}) @deftypefun void gcm_set_key (struct gcm_key *@var{key}, const void *@var{cipher}, nettle_cipher_func *@var{f})
Initializes @var{key}. @var{cipher} gives a context struct for the Initializes @var{key}. @var{cipher} gives a context struct for the
underlying cipher, which must have been previously initialized for underlying cipher, which must have been previously initialized for
encryption, and @var{f} is the encryption function. encryption, and @var{f} is the encryption function.
...@@ -2266,15 +2265,15 @@ for each message @emph{must} use a length that is a multiple of the ...@@ -2266,15 +2265,15 @@ for each message @emph{must} use a length that is a multiple of the
block size. block size.
@end deftypefun @end deftypefun
@deftypefun void gcm_encrypt (struct gcm_ctx *@var{ctx}, const struct gcm_key *@var{key} void *@var{cipher}, nettle_crypt_func *@var{f}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) @deftypefun void gcm_encrypt (struct gcm_ctx *@var{ctx}, const struct gcm_key *@var{key}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src})
@deftypefunx void gcm_decrypt (struct gcm_ctx *@var{ctx}, const struct gcm_key *@var{key}, void *@var{cipher}, nettle_crypt_func *@var{f}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) @deftypefunx void gcm_decrypt (struct gcm_ctx *@var{ctx}, const struct gcm_key *@var{key}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src})
Encrypts or decrypts the data of a message. @var{cipher} is the context Encrypts or decrypts the data of a message. @var{cipher} is the context
struct for the underlying cipher and @var{f} is the encryption function. struct for the underlying cipher and @var{f} is the encryption function.
All but the last call for each message @emph{must} use a length that is All but the last call for each message @emph{must} use a length that is
a multiple of the block size. a multiple of the block size.
@end deftypefun @end deftypefun
@deftypefun void gcm_digest (struct gcm_ctx *@var{ctx}, const struct gcm_key *@var{key}, void *@var{cipher}, nettle_crypt_func *@var{f}, size_t @var{length}, uint8_t *@var{digest}) @deftypefun void gcm_digest (struct gcm_ctx *@var{ctx}, const struct gcm_key *@var{key}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{length}, uint8_t *@var{digest})
Extracts the message digest (also known ``authentication tag''). This is Extracts the message digest (also known ``authentication tag''). This is
the final operation when processing a message. @var{length} is usually the final operation when processing a message. @var{length} is usually
equal to @code{GCM_DIGEST_SIZE}, but if you provide a smaller value, equal to @code{GCM_DIGEST_SIZE}, but if you provide a smaller value,
...@@ -2483,26 +2482,26 @@ Holds state corresponding to a particular message. ...@@ -2483,26 +2482,26 @@ Holds state corresponding to a particular message.
@acronym{CCM}'s block size, 16. @acronym{CCM}'s block size, 16.
@end defvr @end defvr
@deftypefun void ccm_set_nonce (struct ccm_ctx *@var{ctx}, const void *@var{cipher}, nettle_crypt_func *@var{f}, size_t @var{noncelen}, const uint8_t *@var{nonce}, size_t @var{authlen}, size_t @var{msglen}, size_t @var{taglen}) @deftypefun void ccm_set_nonce (struct ccm_ctx *@var{ctx}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{noncelen}, const uint8_t *@var{nonce}, size_t @var{authlen}, size_t @var{msglen}, size_t @var{taglen})
Initializes @var{ctx} using the given nonce and the sizes of the Initializes @var{ctx} using the given nonce and the sizes of the
authenticated data, message, and @acronym{MAC} to be processed. authenticated data, message, and @acronym{MAC} to be processed.
@end deftypefun @end deftypefun
@deftypefun void ccm_update (struct ccm_ctx *@var{ctx}, const void *@var{cipher}, nettle_crypt_func *@var{f}, size_t @var{length}, const uint8_t *@var{data}) @deftypefun void ccm_update (struct ccm_ctx *@var{ctx}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{length}, const uint8_t *@var{data})
Provides associated data to be authenticated. Must be called after Provides associated data to be authenticated. Must be called after
@code{ccm_set_nonce}, and before @code{ccm_encrypt}, @code{ccm_decrypt}, or @code{ccm_set_nonce}, and before @code{ccm_encrypt}, @code{ccm_decrypt}, or
@code{ccm_digest}. @code{ccm_digest}.
@end deftypefun @end deftypefun
@deftypefun void ccm_encrypt (struct ccm_ctx *@var{ctx}, const void *@var{cipher}, nettle_crypt_func *@var{f}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) @deftypefun void ccm_encrypt (struct ccm_ctx *@var{ctx}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src})
@deftypefunx void ccm_decrypt (struct ccm_ctx *@var{ctx}, const void *@var{cipher}, nettle_crypt_func *@var{f}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) @deftypefunx void ccm_decrypt (struct ccm_ctx *@var{ctx}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src})
Encrypts or decrypts the message data. Must be called after Encrypts or decrypts the message data. Must be called after
@code{ccm_set_nonce} and before @code{ccm_digest}. All but the last call @code{ccm_set_nonce} and before @code{ccm_digest}. All but the last call
for each message @emph{must} use a length that is a multiple of the for each message @emph{must} use a length that is a multiple of the
block size. block size.
@end deftypefun @end deftypefun
@deftypefun void ccm_digest (struct ccm_ctx *@var{ctx}, const void *@var{cipher}, nettle_crypt_func *@var{f}, size_t @var{length}, uint8_t *@var{digest}) @deftypefun void ccm_digest (struct ccm_ctx *@var{ctx}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{length}, uint8_t *@var{digest})
Extracts the message digest (also known ``authentication tag''). This is Extracts the message digest (also known ``authentication tag''). This is
the final operation when processing a message. @var{length} is usually the final operation when processing a message. @var{length} is usually
equal to the @var{taglen} parameter supplied to @code{ccm_set_nonce}, equal to the @var{taglen} parameter supplied to @code{ccm_set_nonce},
...@@ -2534,13 +2533,13 @@ passed to a function is always the size for the result, @var{clength} ...@@ -2534,13 +2533,13 @@ passed to a function is always the size for the result, @var{clength}
for the encryption functions, and @var{mlength} for the decryption for the encryption functions, and @var{mlength} for the decryption
functions. functions.
@deftypefun void ccm_encrypt_message (void *@var{cipher}, nettle_crypt_func *@var{f}, size_t @var{nlength}, const uint8_t *@var{nonce}, size_t @var{alength}, const uint8_t *@var{adata}, size_t @var{tlength}, size_t @var{clength}, uint8_t *@var{dst}, const uint8_t *@var{src}) @deftypefun void ccm_encrypt_message (void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{nlength}, const uint8_t *@var{nonce}, size_t @var{alength}, const uint8_t *@var{adata}, size_t @var{tlength}, size_t @var{clength}, uint8_t *@var{dst}, const uint8_t *@var{src})
Computes the message digest from the @var{adata} and @var{src} Computes the message digest from the @var{adata} and @var{src}
parameters, encrypts the plaintext from @var{src}, appends the encrypted parameters, encrypts the plaintext from @var{src}, appends the encrypted
@acronym{MAC} to ciphertext and outputs it to @var{dst}. @acronym{MAC} to ciphertext and outputs it to @var{dst}.
@end deftypefun @end deftypefun
@deftypefun int ccm_decrypt_message (void *@var{cipher}, nettle_crypt_func *@var{f}, size_t @var{nlength}, const uint8_t *@var{nonce}, size_t @var{alength}, const uint8_t *@var{adata}, size_t @var{tlength}, size_t @var{mlength}, uint8_t *@var{dst}, const uint8_t *@var{src}) @deftypefun int ccm_decrypt_message (void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{nlength}, const uint8_t *@var{nonce}, size_t @var{alength}, const uint8_t *@var{adata}, size_t @var{tlength}, size_t @var{mlength}, uint8_t *@var{dst}, const uint8_t *@var{src})
Decrypts the ciphertext from @var{src}, outputs the plaintext to Decrypts the ciphertext from @var{src}, outputs the plaintext to
@var{dst}, recalculates the @acronym{MAC} from @var{adata} and the @var{dst}, recalculates the @acronym{MAC} from @var{adata} and the
plaintext, and compares it to the final @var{tlength} bytes of plaintext, and compares it to the final @var{tlength} bytes of
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment