diff options
author | Moritz Schulte <mo@g10code.com> | 2003-06-14 16:26:18 +0000 |
---|---|---|
committer | Moritz Schulte <mo@g10code.com> | 2003-06-14 16:26:18 +0000 |
commit | 41a949abaa5a285331fc123ad575ef539b807240 (patch) | |
tree | a4febb6f23663f805208d00052810dcd88178d70 | |
parent | 733ebafe52df44c37f28baff775972a34092b06f (diff) | |
download | libgcrypt-41a949abaa5a285331fc123ad575ef539b807240.tar.gz |
2003-06-14 Moritz Schulte <moritz@g10code.com>
* gcrypt.texi (Hash Functions): Adjusteded description of
gcry_md_copy.
2003-06-12 Moritz Schulte <moritz@g10code.com>
* gcrypt.texi (Public Key Functions): Fix example S-Exp, i.e.:
added the number of following digits as prefix to the number of
bits.
(Public Key Functions): Document the general usage of `flags',
including the no-blinding flag.
-rw-r--r-- | doc/ChangeLog | 13 | ||||
-rw-r--r-- | doc/gcrypt.texi | 78 |
2 files changed, 73 insertions, 18 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 82b579ce..3425c6d9 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,16 @@ +2003-06-14 Moritz Schulte <moritz@g10code.com> + + * gcrypt.texi (Hash Functions): Adjusteded description of + gcry_md_copy. + +2003-06-12 Moritz Schulte <moritz@g10code.com> + + * gcrypt.texi (Public Key Functions): Fix example S-Exp, i.e.: + added the number of following digits as prefix to the number of + bits. + (Public Key Functions): Document the general usage of `flags', + including the no-blinding flag. + 2003-06-11 Werner Koch <wk@gnupg.org> * gcrypt.texi (Hash Functions): Document possible values of HD. diff --git a/doc/gcrypt.texi b/doc/gcrypt.texi index bd316b4d..29b3c983 100644 --- a/doc/gcrypt.texi +++ b/doc/gcrypt.texi @@ -78,6 +78,8 @@ This is Edition @value{EDITION}, last updated @value{UPDATED}, of @menu * Introduction:: How to use this manual. * Preparation:: What you should do before using the library. +* General Functions:: General library functions. +* Handler Functions:: Working with handler functions. * Cipher Functions:: All about ciphers. * Hash Functions:: How to use cryptographic hash functions. * Public Key Functions:: How to use asymmetric encryption. @@ -155,8 +157,8 @@ subject to the terms of the GNU General Public License list of these parts. @item It encapsulates the low level cryptography -`Libgcrypt' a high level interface to cryptographic building blocks -using an extendable and flexible API. +`Libgcrypt' provides a high level interface to cryptographic building +blocks using an extendable and flexible API. @end table @@ -278,6 +280,29 @@ specifying both options to @command{libgcrypt-config}: gcc -o foo foo.c `libgcrypt-config --cflags --libs` @end example +@c ********************************************************** +@c ******************* General **************************** +@c ********************************************************** +@node General Functions +@chapter General Functions + +@deftypefun gpg_error_t gcry_control (enum gcry_ctl_cmds @var{cmd}, ...) + +This function can be used to influence the general behaviour of +Libgcrypt in several ways. Depending on @var{cmd}, more arguments can +or have to be provided. + +FIXME. +@end deftypefun + +@c ********************************************************** +@c ******************* General **************************** +@c ********************************************************** +@node Handler Functions +@chapter Handler Functions + +Libgcrypt makes it possible to install so called `handler functions', +which get called by Libgcrypt in case of certain events. @c ********************************************************** @c ******************* Ciphers **************************** @@ -776,12 +801,12 @@ might not even be possible if the data is received from a pipe), a snapshot of the current hash context can be taken and turned into a new context: -@deftypefun gpg_error_t gcry_md_copy (gcry_md_hd_t *@var{h2}, gcry_md_hd_t @var{h}) +@deftypefun gpg_error_t gcry_md_copy (gcry_md_hd_t *@var{handle_dst}, gcry_md_hd_t @var{handle_src}) Create a new digest object as an exact copy of the object described by -handle @var{h} and store it in @var{h2}. The context is not reset and -you can continue to hash data using this context and independently -using the original context. +handle @var{handle_src} and store it in @var{handle_dst}. The context +is not reset and you can continue to hash data using this context and +independently using the original context. @end deftypefun @@ -970,11 +995,11 @@ does implicitly stop debugging. @node Public Key Functions @chapter Public Key Functions -Public key encryption, also known as asymmetric encryption, is am easy -way for key management and to provide digital signatures. Libgcrypt -supports the RSA (Rivest-Shamir-Adleman) algorithms as well as DSA -(Digital Signature Algorithm) and ElGamal. The versatile interface -allows to add more algorithms in the future. +Public key cryptography, also known as asymmetric cryptography, is an +easy way for key management and to provide digital signatures. +Libgcrypt supports the RSA (Rivest-Shamir-Adleman) algorithms as well +as DSA (Digital Signature Algorithm) and ElGamal. The versatile +interface allows to add more algorithms in the future. The API is based on data structures called S-expressions (see XXXX) and does not work with contexts as most of the other building blocks @@ -1002,7 +1027,7 @@ indicate parameters whereas lowercase words are literals. @end example @noindent -This specifies an DSA private key with the following parameters: +This specifies a DSA private key with the following parameters: @table @var @item p-mpi @@ -1063,6 +1088,22 @@ specified and may also support other parameters for performance reasons. @noindent + +Some functions operating on S-expressions support `flags', that +influence the operation. These flags have to be listed in a +sub-S-expression named `flags'; the following flags are known: + +@table @var +@item pkcs1 +Use PKCS#1 block type 2 padding. +@item no-blinding +Do not use a technique called `blinding', which is used by default in +order to prevent leaking of secret information. Blinding is only +implemented by RSA, but it might be implemented by other algorithms in +the future as well, when necessary. +@end table + +@noindent Now that we know the key basics, we can carry on and explain how to encrypt and decrypt data. In almost all cases the data is a random session key which is in turn used for the actual encryption of the real @@ -1070,11 +1111,12 @@ data. There are 2 functions to do this: @deftypefun gpg_error_t gcry_pk_encrypt (@w{gcry_sexp_t *@var{r_ciph},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{pkey}}) -Obviously a public key must be provided for encryption. It is expected -as an appropriate S-expression (see above) in @var{pkey}. The data to -be encrypted can either be in the simple old format, which is a very -simple S-expression consisting only of one MPI, or it may be a more -complex S-expression which also allows to specify padding rules. +Obviously a public key must be provided for encryption. It is +expected as an appropriate S-expression (see above) in @var{pkey}. +The data to be encrypted can either be in the simple old format, which +is a very simple S-expression consisting only of one MPI, or it may be +a more complex S-expression which also allows to specify flags for +operation, like e.g. padding rules. @noindent If you don't want to let Libgcrypt handle the padding, you must pass an @@ -1404,7 +1446,7 @@ Here is an example for @var{parms} for creating a 1024 bit RSA key: @example (genkey (rsa - (nbits 1024))) + (nbits 4:1024))) @end example @noindent |