From b77fb37ceaa3d1ffad4409209e775cb6ec43ea22 Mon Sep 17 00:00:00 2001 From: Werner Koch Date: Mon, 15 Sep 2008 10:19:15 +0000 Subject: doc cleanups. --- NEWS | 4 +++ doc/ChangeLog | 4 +++ doc/gcrypt.texi | 94 +++++++++++++++++++++++++++++++++------------------------ doc/lgpl.texi | 4 +-- 4 files changed, 65 insertions(+), 41 deletions(-) diff --git a/NEWS b/NEWS index 1511c10e..c3037d07 100644 --- a/NEWS +++ b/NEWS @@ -1,6 +1,10 @@ Noteworthy changes in version 1.4.3 ------------------------------------------------ + * More self-tests. + + * Documentation cleanups. + Noteworthy changes in version 1.4.2 (2008-09-08) ------------------------------------------------ diff --git a/doc/ChangeLog b/doc/ChangeLog index 6355766c..a417842e 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,7 @@ +2008-09-15 Werner Koch + + * gcrypt.texi: Fold the two FIPS appendices into one. + 2008-09-11 Werner Koch * gcrypt.texi (Public-Key Subsystem Architecture): Explain RSA diff --git a/doc/gcrypt.texi b/doc/gcrypt.texi index 7c35011e..4e8eb996 100644 --- a/doc/gcrypt.texi +++ b/doc/gcrypt.texi @@ -77,9 +77,8 @@ section entitled ``GNU General Public License''. Appendices -* Self-Tests:: Description of self-tests. -* FIPS Restrictions:: Restrictions in FIPS mode. -* FIPS Finite State Machine:: Description of the FIPS FSM. +* Self-Tests:: Description of the self-tests. +* FIPS Mode:: Description of the FIPS mode. * Library Copying:: The GNU Lesser General Public License says how you can copy and share Libgcrypt. * Copying:: The GNU General Public License says how you @@ -188,7 +187,7 @@ of the library are verified. * Building sources using Automake:: How to build sources with the help of Automake. * Initializing the library:: How to initialize the library. * Multi-Threading:: How Libgcrypt can be used in a MT environment. -* FIPS mode:: How to enable the FIPS mode. +* Enabling FIPS mode:: How to enable the FIPS mode. @end menu @@ -392,8 +391,8 @@ and freed memory, you need to initialize Libgcrypt this way: gcry_control (GCRYCTL_INIT_SECMEM, 16384, 0); @anchor{sample-use-resume-secmem} - /* It is now okay to let Libgcrypt complain when there was/is a problem - with the secure memory. */ + /* It is now okay to let Libgcrypt complain when there was/is + a problem with the secure memory. */ gcry_control (GCRYCTL_RESUME_SECMEM_WARN); /* ... If required, other initialization goes here. */ @@ -489,25 +488,28 @@ necessary thread callbacks for PThread and for GNU Pth: @table @code @item GCRY_THREAD_OPTION_PTH_IMPL -This macro defines the following (static) symbols: gcry_pth_init, -gcry_pth_mutex_init, gcry_pth_mutex_destroy, gcry_pth_mutex_lock, -gcry_pth_mutex_unlock, gcry_pth_read, gcry_pth_write, gcry_pth_select, -gcry_pth_waitpid, gcry_pth_accept, gcry_pth_connect, gcry_threads_pth. +This macro defines the following (static) symbols: +@code{gcry_pth_init}, @code{gcry_pth_mutex_init}, +@code{gcry_pth_mutex_destroy}, @code{gcry_pth_mutex_lock}, +@code{gcry_pth_mutex_unlock}, @code{gcry_pth_read}, +@code{gcry_pth_write}, @code{gcry_pth_select}, +@code{gcry_pth_waitpid}, @code{gcry_pth_accept}, +@code{gcry_pth_connect}, @code{gcry_threads_pth}. -After including this macro, gcry_control() shall be used with a -command of GCRYCTL_SET_THREAD_CBS in order to register the thread -callback structure named ``gcry_threads_pth''. +After including this macro, @code{gcry_control()} shall be used with a +command of @code{GCRYCTL_SET_THREAD_CBS} in order to register the +thread callback structure named ``gcry_threads_pth''. @item GCRY_THREAD_OPTION_PTHREAD_IMPL This macro defines the following (static) symbols: -gcry_pthread_mutex_init, gcry_pthread_mutex_destroy, -gcry_pthread_mutex_lock, gcry_pthread_mutex_unlock, -gcry_threads_pthread. +@code{gcry_pthread_mutex_init}, @code{gcry_pthread_mutex_destroy}, +@code{gcry_pthread_mutex_lock}, @code{gcry_pthread_mutex_unlock}, +@code{gcry_threads_pthread}. -After including this macro, gcry_control() shall be used with a -command of GCRYCTL_SET_THREAD_CBS in order to register the thread -callback structure named ``gcry_threads_pthread''. +After including this macro, @code{gcry_control()} shall be used with a +command of @code{GCRYCTL_SET_THREAD_CBS} in order to register the +thread callback structure named ``gcry_threads_pthread''. @end table Note that these macros need to be terminated with a semicolon. Keep @@ -515,9 +517,8 @@ in mind that these are convenient macros for C programmers; C++ programmers might have to wrap these macros in an ``extern C'' body. - -@node FIPS mode -@section FIPS Mode +@node Enabling FIPS mode +@section How to enable the FIPS mode Libgcrypt may be used in a FIPS 140-2 mode. Note, that this does not necessary mean that Libcgrypt is an appoved FIPS 140-2 module. Check the @@ -1168,7 +1169,8 @@ above: gcry_cipher_hd_t handle; gcry_error_t err = 0; - err = gcry_cipher_open (&handle, GCRY_CIPHER_AES, GCRY_CIPHER_MODE_CBC, 0); + err = gcry_cipher_open (&handle, GCRY_CIPHER_AES, + GCRY_CIPHER_MODE_CBC, 0); if (err) @{ fprintf (stderr, "Failure: %s/%s\n", @@ -1510,13 +1512,13 @@ unsigned char *inbuf) @deftp {Data type} gcry_cipher_stencrypt_t Type for the `stencrypt' function, defined as: gcry_err_code_t -(*gcry_cipher_stencrypt_t) (void *c, const unsigned char *outbuf, const +(*gcry_@/cipher_@/stencrypt_@/t) (void *c, const unsigned char *outbuf, const unsigned char *, unsigned int n) @end deftp @deftp {Data type} gcry_cipher_stdecrypt_t Type for the `stdecrypt' function, defined as: gcry_err_code_t -(*gcry_cipher_stdecrypt_t) (void *c, const unsigned char *outbuf, const +(*gcry_@/cipher_@/stdecrypt_@/t) (void *c, const unsigned char *outbuf, const unsigned char *, unsigned int n) @end deftp @@ -3011,7 +3013,8 @@ Example code: err = gcry_ac_open (&handle, GCRY_AC_RSA, 0); assert (! err); - err = gcry_ac_key_pair_generate (handle, 1024, &rsa_spec, &key_pair, NULL); + err = gcry_ac_key_pair_generate (handle, 1024, &rsa_spec, + &key_pair, NULL); assert (! err); @} @end example @@ -4995,7 +4998,7 @@ incremented on each use. @c ******************************************** @node Self-Tests -@appendix Description of Self-Tests +@appendix Description of the Self-Tests In addition to the build time regression test suite, Libgcrypt implements self-tests to be performed at runtime. Which self-tests @@ -5191,16 +5194,22 @@ mode, the library is put into the ``Error'' state. @table @asis @item RSA -The test uses a random number 64 bits less the size of the modulus to -test the encryption and decryption operation. A new random number of -the same size is then generated to test the signing operation. The -signature is then modified and then checked to test that a modified -signature is correcty detected. (@code{cipher/@/dsa.c:@/test_keys}) +The test uses a random number 64 bits less the size of the modulus as +plaintext and runs an encryption and decryption operation in turn. The +encrypted value is checked to not match the plaintext and the result +of the decryption is checked to match the plaintext. + +A new random number of the same size is generated, signed and verified +to test the correctness of the signing operation. As a second signing +test, the signature is modified by incrementing its value and then +verified with the expected result that the verification fails. +(@code{cipher/@/dsa.c:@/test_keys}) @item DSA The test uses a random number of the size of the Q parameter to create -a signature and then checked that the signature verifies. The data is -then modified and then checked that the signature does not verify. -(@code{cipher/@/dsa.c:@/test_keys}) +a signature and then checks that the signature verifies. As a second +signing test, the data is modified by incrementing its value and then +verified against the signature with the expected result that the +verification fails. (@code{cipher/@/dsa.c:@/test_keys}) @end table @@ -5327,8 +5336,16 @@ A known answer test using 152 byte of data and a 131 byte key is run. @c ******************************************** -@node FIPS Restrictions -@appendix Restrictions in FIPS mode +@node FIPS Mode +@appendix Description of the FIPS Mode + +This appendix gives detailed information pertaining to the FIPS mode. +In particular, the changes to the standard mode and the finite state +machine are described. The self-tests required in this mode are +described in the appendix on self-tests. + +@c ------------------------------- +@section Restrictions in FIPS Mode @noindent If Libgcrypt is used in FIPS mode these restrictions are effective: @@ -5426,8 +5443,7 @@ A handler set by @code{gcry_set_fatalerror_handler} is ignored. @c ******************************************** -@node FIPS Finite State Machine -@appendix FIPS Finite State Machine +@section FIPS Finite State Machine The FIPS mode of libgcrypt implements a finite state machine (FSM) using 8 states (@pxref{tbl:fips-states}) and checks at runtime that only valid diff --git a/doc/lgpl.texi b/doc/lgpl.texi index 99e0f725..a3f83cb3 100644 --- a/doc/lgpl.texi +++ b/doc/lgpl.texi @@ -1,7 +1,7 @@ @node Library Copying -@unnumbered Lesser General Public License +@unnumbered GNU Lesser General Public License -@cindex LGPL, Lesser General Public License +@cindex LGPL, GNU Lesser General Public License @center Version 2.1, February 1999 @display -- cgit v1.2.1