libgcrypt/doc (ChangeLog gcrypt.texi)
cvs user mo
cvs at cvs.gnupg.org
Mon Apr 11 13:48:51 CEST 2005
Date: Monday, April 11, 2005 @ 14:04:51
Author: mo
Path: /cvs/libgcrypt/libgcrypt/doc
Modified: ChangeLog gcrypt.texi
2005-04-11 Moritz Schulte <moritz at g10code.com>
* gcrypt.texi (Available hash algorithms): Add entry for Whirlpool.
2005-03-30 Moritz Schulte <moritz at g10code.com>
* gcrypt.texi (Working with IO objects): Document ac io objects;
adjust ac scheme functions, which do now use io objects.
-------------+
ChangeLog | 9 ++
gcrypt.texi | 184 ++++++++++++++++++++++++++++++++++++++++++++++------------
2 files changed, 158 insertions(+), 35 deletions(-)
Index: libgcrypt/doc/ChangeLog
diff -u libgcrypt/doc/ChangeLog:1.46 libgcrypt/doc/ChangeLog:1.47
--- libgcrypt/doc/ChangeLog:1.46 Sat Mar 19 19:56:32 2005
+++ libgcrypt/doc/ChangeLog Mon Apr 11 14:04:51 2005
@@ -1,3 +1,12 @@
+2005-04-11 Moritz Schulte <moritz at g10code.com>
+
+ * gcrypt.texi (Available hash algorithms): Add entry for Whirlpool.
+
+2005-03-30 Moritz Schulte <moritz at g10code.com>
+
+ * gcrypt.texi (Working with IO objects): Document ac io objects;
+ adjust ac scheme functions, which do now use io objects.
+
2005-03-19 Moritz Schulte <moritz at g10code.com>
* gcrypt.texi (Working with cipher handles): Clarify CTS mode.
Index: libgcrypt/doc/gcrypt.texi
diff -u libgcrypt/doc/gcrypt.texi:1.48 libgcrypt/doc/gcrypt.texi:1.49
--- libgcrypt/doc/gcrypt.texi:1.48 Sat Mar 19 19:56:32 2005
+++ libgcrypt/doc/gcrypt.texi Mon Apr 11 14:04:51 2005
@@ -1572,6 +1572,10 @@
This is the OpenPGP cyclic redundancy check function. It yields an
output of 3 bytes.
+ at item GCRY_MD_WHIRLPOOL
+This is the Whirlpool algorithm which yields a message digest of 64
+bytes.
+
@end table
@c end table of hash algorithms
@@ -2662,6 +2666,7 @@
@menu
* Available asymmetric algorithms:: List of algorithms supported by the library.
* Working with sets of data:: How to work with sets of data.
+* Working with IO objects:: How to work with IO objects.
* Working with handles:: How to use handles.
* Working with keys:: How to work with keys.
* Using cryptographic functions:: How to perform cryptographic operations.
@@ -2696,7 +2701,8 @@
In the context of this interface the term `data set' refers to a list
of `named MPI values' that is used by functions performing
-cryptographic operations.
+cryptographic operations; a named MPI value is a an MPI value,
+associated with a label.
Such data sets are used for representing keys, since keys simply
consist of a variable amount of numbers. Furthermore some functions
@@ -2704,10 +2710,10 @@
functions.
This section documents the data types, symbols and functions that are
-relevant for working with such data sets.
+relevant for working with data sets.
@deftp {Data type} gcry_ac_data_t
-A data set, that is simply a list of named MPI values.
+A single data set.
@end deftp
The following flags are supported:
@@ -2715,7 +2721,10 @@
@table @code
@item GCRY_AC_FLAG_DEALLOC
Used for storing data in a data set. If given, the data will be
-released by the library.
+released by the library. Note that whenever one of the ac functions
+is about to release objects because of this flag, the objects are
+expected to be stored in memory allocated through the Libgcrypt memory
+management. In other words: gcry_free() is used instead of free().
@item GCRY_AC_FLAG_COPY
Used for storing/retrieving data in/from a data set. If given, the
@@ -2741,7 +2750,8 @@
@end deftypefun
@deftypefun gcry_error_t gcry_ac_data_copy (gcry_ac_data_t *@var{data_cp}, gcry_ac_data_t @var{data})
-Create a copy of the data set @var{data} and store it in @var{data_cp}.
+Create a copy of the data set @var{data} and store it in
+ at var{data_cp}. FIXME: exact semantics undefined.
@end deftypefun
@deftypefun unsigned int gcry_ac_data_length (gcry_ac_data_t @var{data})
@@ -2752,7 +2762,9 @@
@deftypefun gcry_error_t gcry_ac_data_get_name (gcry_ac_data_t @var{data}, unsigned int @var{flags}, char *@var{name}, gcry_mpi_t *@var{mpi})
Store the value labelled with @var{name} found in @var{data} in
@var{mpi}. If @var{flags} contains GCRY_AC_FLAG_COPY, store a copy of
-the @var{mpi} value contained in the data set. @var{mpi} may be NULL.
+the @var{mpi} value contained in the data set. @var{mpi} may be NULL
+(this might be useful for checking the existence of an MPI with
+extracting it).
@end deftypefun
@deftypefun gcry_error_t gcry_ac_data_get_index (gcry_ac_data_t @var{data}, unsigned int flags, unsigned int @var{index}, const char **@var{name}, gcry_mpi_t *@var{mpi})
@@ -2766,6 +2778,104 @@
Destroys any values contained in the data set @var{data}.
@end deftypefun
+ at deftypefun gcry_error_t gcry_ac_data_to_sexp (gcry_ac_data_t @var{data}, gcry_sexp_t *@var{sexp}, const char **@var{identifiers})
+This function converts the data set @var{data} into a newly created
+S-Expression, which is to be stored in @var{sexp}; @var{identifiers}
+is a NULL terminated list of C strings, which specifies the structure
+of the S-Expression.
+
+Example:
+
+If @var{identifiers} is a list of pointers to the strings ``foo'' and
+``bar'' and if @var{data} is a data set containing the values ``val1 =
+0x01'' and ``val2 = 0x02'', then the resulting S-Expression will look
+like this: (foo (bar ((val1 0x01) (val2 0x02))).
+ at end deftypefun
+
+ at deftypefun gcry_error gcry_ac_data_from_sexp (gcry_ac_data_t *@var{data}, gcry_sexp_t @var{sexp}, const char **@var{identifiers})
+This function converts the S-Expression @var{sexp} into a newly
+created data set, which is to be stored in @var{data};
+ at var{identifiers} is a NULL terminated list of C strings, which
+specifies the structure of the S-Expression. If the list of
+identifiers does not match the structure of the S-Expression, the
+function fails.
+ at end deftypefun
+
+ at node Working with IO objects
+ at section Working with IO objects
+
+Note: IO objects are currently only used in the context of message
+encoding/decoding and encryption/signature schemes.
+
+ at deftp {Data type} {gcry_ac_io_t}
+ at code{gcry_ac_io_t} is the type to be used for IO objects.
+ at end deftp
+
+IO objects provide an uniform IO layer on top of different underlying
+IO mechanisms; either they can be used for providing data to the
+library (mode is GCRY_AC_IO_READABLE) or they can be used for
+retrieving data from the library (mode is GCRY_AC_IO_WRITABLE).
+
+IO object need to be initialized by calling on of the following
+functions:
+
+ at deftypefun void gcry_ac_io_init (gcry_ac_io_t *@var{ac_io}, gcry_ac_io_mode_t @var{mode}, gcry_ac_io_type_t @var{type}, ...);
+Initialize @var{ac_io} according to @var{mode}, @var{type} and the
+variable list of arguments. The list of variable arguments to specify
+depends on the given @var{type}.
+ at end deftypefun
+
+ at deftypefun void gcry_ac_io_init_va (gcry_ac_io_t *@var{ac_io}, gcry_ac_io_mode_t @var{mode}, gcry_ac_io_type_t @var{type}, va_list @var{ap});
+Initialize @var{ac_io} according to @var{mode}, @var{type} and the
+variable list of arguments @var{ap}. The list of variable arguments
+to specify depends on the given @var{type}.
+ at end deftypefun
+
+The following types of IO objects exist:
+
+ at table @code
+ at item GCRY_AC_IO_STRING
+In case of GCRY_AC_IO_READABLE the IO object will provide data from a
+memory string. Arguments to specify at initialization time:
+ at table @code
+ at item unsigned char *
+Pointer to the beginning of the memory string
+ at item size_t
+Size of the memory string
+ at end table
+In case of GCRY_AC_IO_WRITABLE the object will store retrieved data in
+a newly allocated memory string. Arguments to specify at
+initialization time:
+ at table @code
+ at item unsigned char **
+Pointer to address, at which the pointer to the newly created memory
+string is to be stored
+ at item size_t *
+Pointer to address, at which the size of the newly created memory
+string is to be stored
+ at end table
+
+ at item GCRY_AC_IO_CALLBACK
+In case of GCRY_AC_IO_READABLE the object will forward read requests
+to a provided callback function. Arguments to specify at
+initialization time:
+ at table @code
+ at item gcry_ac_data_read_cb_t
+Callback function to use
+ at item void *
+Opaque argument to provide to the callback function
+ at end table
+In case of GCRY_AC_IO_WRITABLE the object will forward write requests
+to a provided callback function. Arguments to specify at
+initialization time:
+ at table @code
+ at item gcry_ac_data_write_cb_t
+Callback function to use
+ at item void *
+Opaque argument to provide to the callback function
+ at end table
+ at end table
+
@node Working with handles
@section Working with handles
@@ -2775,7 +2885,7 @@
@deftypefun gcry_error_t gcry_ac_open (gcry_ac_handle_t *@var{handle}, int @var{algorithm}, int @var{flags})
Creates a new handle for the algorithm @var{algorithm} and stores it
-in @var{handle}. @var{flags} is not used yet.
+in @var{handle}. @var{flags} is not used currently.
@var{algorithm} must be a valid algorithm ID, see @xref{Available
algorithms}, for a list of supported algorithms and the according
@@ -2839,7 +2949,7 @@
has the following meanings:
@table @code
@item = 0
-Let @acronym{Libgcrypt} device what exponent should be used.
+Let @acronym{Libgcrypt} decide what exponent should be used.
@item = 1
Request the use of a ``secure'' exponent; this is required by some
specification to be 65537.
@@ -3026,33 +3136,37 @@
The functions implementing schemes:
- at deftypefun gcry_error_t gcry_ac_data_encrypt_scheme (gcry_ac_handle_t @var{handle}, gcry_ac_scheme_t @var{scheme}, unsigned int @var{flags}, void *@var{opts}, gcry_ac_key_t @var{key_public}, unsigned char *@var{m}, size_t @var{m_n}, unsigned char **@var{c}, size_t *@var{c_n})
-Encrypts the plain text contained in @var{m} of size @var{m_n} through
- at var{handle} and @var{key_public} according to @var{scheme},
- at var{flags} and @var{opts}. The encrypted message is stored in
- at var{c} and @var{c_n}.
- at end deftypefun
-
- at deftypefun gcry_error_t gcry_ac_data_decrypt_scheme (gcry_ac_handle_t @var{handle}, gcry_ac_scheme_t @var{scheme}, unsigned int @var{flags}, void *@var{opts}, gcry_ac_key_t @var{key_secret}, unsigned char *@var{c}, size_t @var{c_n}, unsigned char **@var{m}, size_t *@var{m_n})
-Decrypts the cipher text contained in @var{c} of size @var{c_n}
-through @var{handle} and @var{key_secret} according to @var{scheme},
- at var{flags} and @var{opts}. The decrypted message is stored in
- at var{m} and @var{m_n}.
- at end deftypefun
-
- at deftypefun gcry_error_t gcry_ac_data_sign_scheme (gcry_ac_handle_t @var{handle}, gcry_ac_scheme_t @var{scheme}, unsigned int @var{flags}, void *@var{opts}, gcry_ac_key_t @var{key_secret}, unsigned char *@var{m}, size_t @var{m_n}, unsigned char **@var{s}, size_t *@var{s_n})
-Signs the message contained in @var{m} of size @var{m_n} through
- at var{handle} and @var{key_secret} according to @var{scheme},
- at var{flags} and @var{opts}. The signature is stored in @var{s} and
- at var{s_n}.
- at end deftypefun
-
- at deftypefun gcry_error_t gcry_ac_data_verify_scheme (gcry_ac_handle_t @var{handle}, gcry_ac_scheme_t @var{scheme}, unsigned int @var{flags}, void *@var{opts}, gcry_ac_key_t @var{key_public}, unsigned char *@var{m}, size_t @var{m_n}, unsigned char *@var{s}, size_t @var{s_n})
-Verifies that the signature contained in @var{s} and @var{s_n} is
-indeed the result of signing the message contained in @var{m} of size
- at var{m_n} through @var{handle} and the secret key belonging to
- at var{key_public} according to @var{scheme}, @var{flags} and
- at var{opts}.
+ at deftypefun gcry_error_t gcry_ac_data_encrypt_scheme (gcry_ac_handle_t @var{handle}, gcry_ac_scheme_t @var{scheme}, unsigned int @var{flags}, void *@var{opts}, gcry_ac_key_t @var{key}, gcry_ac_io_t *@var{io_message}, gcry_ac_io_t *@var{io_cipher})
+Encrypts the plain text readable from @var{io_message} through
+ at var{handle} with the public key @var{key} according to @var{scheme},
+ at var{flags} and @var{opts}. If @var{opts} is not NULL, it has to be a
+pointer to a structure specific to the chosen scheme (gcry_ac_es_*_t).
+The encrypted message is written to @var{io_cipher}.
+ at end deftypefun
+
+ at deftypefun gcry_error_t gcry_ac_data_decrypt_scheme (gcry_ac_handle_t @var{handle}, gcry_ac_scheme_t @var{scheme}, unsigned int @var{flags}, void *@var{opts}, gcry_ac_key_t @var{key}, gcry_ac_io_t *@var{io_cipher}, gcry_ac_io_t *@var{io_message})
+Decrypts the cipher text readable from @var{io_cipher} through
+ at var{handle} with the secret key @var{key} according to @var{scheme},
+ at var{flags} and @var{opts}. If @var{opts} is not NULL, it has to be a
+pointer to a structure specific to the chosen scheme (gcry_ac_es_*_t).
+The decrypted message is written to @var{io_message}.
+ at end deftypefun
+
+ at deftypefun gcry_error_t gcry_ac_data_sign_scheme (gcry_ac_handle_t @var{handle}, gcry_ac_scheme_t @var{scheme}, unsigned int @var{flags}, void *@var{opts}, gcry_ac_key_t @var{key}, gcry_ac_io_t *@var{io_message}, gcry_ac_io_t *@var{io_signature})
+Signs the message readable from @var{io_message} through @var{handle}
+with the secret key @var{key} according to @var{scheme}, @var{flags}
+and @var{opts}. If @var{opts} is not NULL, it has to be a pointer to
+a structure specific to the chosen scheme (gcry_ac_ssa_*_t). The
+signature is written to @var{io_signature}.
+ at end deftypefun
+
+ at deftypefun gcry_error_t gcry_ac_data_verify_scheme (gcry_ac_handle_t @var{handle}, gcry_ac_scheme_t @var{scheme}, unsigned int @var{flags}, void *@var{opts}, gcry_ac_key_t @var{key}, gcry_ac_io_t *@var{io_message}, gcry_ac_io_t *@var{io_signature})
+Verifies through @var{handle} that the signature readable from
+ at var{io_signature} is indeed the result of signing the message
+readable from @var{io_message} with the secret key belonging to the
+public key @var{key} according to @var{scheme} and @var{opts}. If
+ at var{opts} is not NULL, it has to be an anonymous structure
+(gcry_ac_ssa_*_t) specific to the chosen scheme.
@end deftypefun
@node Handle-independent functions
More information about the Gnupg-commits
mailing list