nettle: Conventions

1 
1 3 Conventions
1 *************
1 
1 For each supported algorithm, there is an include file that defines a
1 _context struct_, a few constants, and declares functions for operating
1 on the context.  The context struct encapsulates all information needed
1 by the algorithm, and it can be copied or moved in memory with no
1 unexpected effects.
1 
1    For consistency, functions for different algorithms are very similar,
1 but there are some differences, for instance reflecting if the key setup
1 or encryption function differ for encryption and decryption, and whether
1 or not key setup can fail.  There are also differences between
1 algorithms that don’t show in function prototypes, but which the
1 application must nevertheless be aware of.  There is no big difference
1 between the functions for stream ciphers and for block ciphers, although
1 they should be used quite differently by the application.
1 
1    If your application uses more than one algorithm of the same type,
1 you should probably create an interface that is tailor-made for your
1 needs, and then write a few lines of glue code on top of Nettle.
1 
1    By convention, for an algorithm named ‘foo’, the struct tag for the
1 context struct is ‘foo_ctx’, constants and functions uses prefixes like
1 ‘FOO_BLOCK_SIZE’ (a constant) and ‘foo_set_key’ (a function).
1 
1    In all functions, strings are represented with an explicit length, of
1 type ‘size_t’, and a pointer of type ‘uint8_t *’ or ‘const uint8_t *’.
1 For functions that transform one string to another, the argument order
1 is length, destination pointer and source pointer.  Source and
1 destination areas are usually of the same length.  When they differ,
1 e.g., for ‘ccm_encrypt_message’, the length argument specifies the size
1 of the destination area.  Source and destination pointers may be equal,
1 so that you can process strings in place, but source and destination
1 areas _must not_ overlap in any other way.
1 
1    Many of the functions lack return value and can never fail.  Those
1 functions which can fail, return one on success and zero on failure.
1