[svn] gcry - r1227 - trunk/doc
svn author marcus
cvs at cvs.gnupg.org
Mon Apr 9 18:00:05 CEST 2007
Author: marcus
Date: 2007-04-09 18:00:03 +0200 (Mon, 09 Apr 2007)
New Revision: 1227
Modified:
trunk/doc/ChangeLog
trunk/doc/gcrypt.texi
Log:
2007-04-09 Marcus Brinkmann <marcus at g10code.de>
* gcrypt.texi: Fix some typos.
Modified: trunk/doc/ChangeLog
===================================================================
--- trunk/doc/ChangeLog 2007-03-28 10:47:25 UTC (rev 1226)
+++ trunk/doc/ChangeLog 2007-04-09 16:00:03 UTC (rev 1227)
@@ -1,3 +1,7 @@
+2007-04-09 Marcus Brinkmann <marcus at g10code.de>
+
+ * gcrypt.texi: Fix some typos.
+
2006-11-05 Moritz Schulte <moritz at g10code.com>
* gcrypt.texi (General public-key related Functions): Typo.
Modified: trunk/doc/gcrypt.texi
===================================================================
--- trunk/doc/gcrypt.texi 2007-03-28 10:47:25 UTC (rev 1226)
+++ trunk/doc/gcrypt.texi 2007-04-09 16:00:03 UTC (rev 1227)
@@ -61,7 +61,7 @@
@menu
-* Introduction:: What is @acronym{Libgcrypt}.
+* Introduction:: What is Libgcrypt.
* Preparation:: What you should do before using the library.
* Generalities:: General library functions and data types.
* Handler Functions:: Working with handler functions.
@@ -78,9 +78,9 @@
Appendices
* Library Copying:: The GNU Lesser General Public License
- says how you can copy and share `Libgcrypt'.
+ says how you can copy and share Libgcrypt.
* Copying:: The GNU General Public License says how you
- can copy and share some parts of `Libgcrypt'.
+ can copy and share some parts of Libgcrypt.
Indices
@@ -92,7 +92,7 @@
Introduction
* Getting Started:: How to use this manual.
-* Features:: A glance at @acronym{Libgcrypt}'s features.
+* Features:: A glance at Libgcrypt's features.
* Overview:: Overview about the library.
Preparation
@@ -100,10 +100,10 @@
* Building sources:: How to build sources using the library.
* Building sources using Automake:: How to build sources with the help of Automake.
* Initializing the library:: How to initialize the library.
-* Multi Threading:: How @acronym{Libgcrypt} can be used in a MT environment.
+* Multi-Threading:: How Libgcrypt can be used in a MT environment.
Generalities
-* Controlling the library:: Controlling @acronym{Libgcrypt}'s behavior.
+* Controlling the library:: Controlling Libgcrypt's behavior.
* Modules:: Description of extension modules.
* Error Handling:: Error codes and such.
@@ -141,7 +141,7 @@
* Handle-independent functions:: General functions independent of handles.
Random Numbers
-* Quality of random numbers:: @acronym{Libgcrypt} uses different quality levels.
+* Quality of random numbers:: Libgcrypt uses different quality levels.
* Retrieving random numbers:: How to retrieve random numbers.
S-expressions
@@ -181,18 +181,18 @@
@c **********************************************************
@node Introduction
@chapter Introduction
-`@acronym{Libgcrypt}' is a library providing cryptographic building blocks.
+Libgcrypt is a library providing cryptographic building blocks.
@menu
* Getting Started:: How to use this manual.
-* Features:: A glance at @acronym{Libgcrypt}'s features.
+* Features:: A glance at Libgcrypt's features.
* Overview:: Overview about the library.
@end menu
@node Getting Started
@section Getting Started
-This manual documents the `@acronym{Libgcrypt}' library application programming
+This manual documents the Libgcrypt library application programming
interface (API). All functions and data types provided by the library
are explained.
@@ -213,7 +213,7 @@
@node Features
@section Features
-`Libgcrypt' might have a couple of advantages over other libraries doing
+Libgcrypt might have a couple of advantages over other libraries doing
a similar job.
@table @asis
@@ -226,8 +226,8 @@
list of these parts.
@item It encapsulates the low level cryptography
-`@acronym{Libgcrypt}' provides 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 extensible and flexible API.
@end table
@@ -235,15 +235,15 @@
@section Overview
@noindent
-The `@acronym{Libgcrypt}' library is fully thread-safe, where it makes
-sense to be thread-safe. An exception for thread-safety are some
-cryptographic functions that modify a certain context stored in
-handles. If the user really intents to use such functions from
-different threads on the same handle, he has to take care of the
-serialization of such functions himself. If not described otherwise,
-every function is thread-safe.
+The Libgcrypt library is fully thread-safe, where it makes
+sense to be thread-safe. Not thread-safe are some cryptographic
+functions that modify a certain context stored in handles. If the
+user really intents to use such functions from different threads on
+the same handle, he has to take care of the serialization of such
+functions himself. If not described otherwise, every function is
+thread-safe.
- at acronym{Libgcrypt} depends on the library `libgpg-error', which
+Libgcrypt depends on the library `libgpg-error', which
contains common error handling related code for GnuPG components.
@c **********************************************************
@@ -252,7 +252,7 @@
@node Preparation
@chapter Preparation
-To use `@acronym{Libgcrypt}', you have to perform some changes to your
+To use Libgcrypt, you have to perform some changes to your
sources and the build system. The necessary changes are small and
explained in the following sections. At the end of this chapter, it
is described how the library is initialized, and how the requirements
@@ -263,7 +263,7 @@
* Building sources:: How to build sources using the library.
* Building sources using Automake:: How to build sources with the help of Automake.
* Initializing the library:: How to initialize the library.
-* Multi Threading:: How @acronym{Libgcrypt} can be used in a MT environment.
+* Multi-Threading:: How Libgcrypt can be used in a MT environment.
@end menu
@@ -279,16 +279,15 @@
#include <gcrypt.h>
@end example
-The name space of `@acronym{Libgcrypt}' is @code{gcry_*} for function
+The name space of Libgcrypt is @code{gcry_*} for function
and type names and @code{GCRY*} for other symbols. In addition the
same name prefixes with one prepended underscore are reserved for
-internal use and should never be used by an application. Furthermore
-`libgpg-error' defines functions prefixed with `gpg_' and preprocessor
-symbols prefixed with `GPG_'. Note that @acronym{Libgcrypt} uses
-libgpg-error, which uses @code{gpg_err_*} as name space for function
-and type names and @code{GPG_ERR_*} for other symbols, including all
-the error codes.
+internal use and should never be used by an application. Note that
+Libgcrypt uses libgpg-error, which uses @code{gpg_*} as
+name space for function and type names and @code{GPG_*} for other
+symbols, including all the error codes.
+
@node Building sources
@section Building sources
@@ -299,7 +298,7 @@
file search path (via the @option{-I} option).
However, the path to the include file is determined at the time the
-source is configured. To solve this problem, `@acronym{Libgcrypt}' ships with a small
+source is configured. To solve this problem, Libgcrypt ships with a small
helper program @command{libgcrypt-config} that knows the path to the
include file and other configuration options. The options that need
to be added to the compiler invocation at compile time are output by
@@ -311,7 +310,7 @@
@end example
Adding the output of @samp{libgcrypt-config --cflags} to the compilers
-command line will ensure that the compiler can find the `@acronym{Libgcrypt}' header
+command line will ensure that the compiler can find the Libgcrypt header
file.
A similar problem occurs when linking the program with the library.
@@ -320,8 +319,8 @@
(via the @option{-L} option). For this, the option @option{--libs} to
@command{libgcrypt-config} can be used. For convenience, this option
also outputs all other options that are required to link the program
-with the `@acronym{Libgcrypt}' libraries (in particular, the @samp{-lgcrypt}
-option). The example shows how to link @file{foo.o} with the `@acronym{Libgcrypt}'
+with the Libgcrypt libraries (in particular, the @samp{-lgcrypt}
+option). The example shows how to link @file{foo.o} with the Libgcrypt
library to a program @command{foo}.
@example
@@ -339,9 +338,9 @@
@section Building sources using Automake
It is much easier if you use GNU Automake instead of writing your own
-Makefiles. If you do that you do not have to worry about finding and
+Makefiles. If you do that, you do not have to worry about finding and
invoking the @command{libgcrypt-config} script at all.
- at acronym{Libgcrypt} provides an extension to Automake that does all
+Libgcrypt provides an extension to Automake that does all
the work for you.
@c A simple macro for optional variables.
@@ -349,7 +348,7 @@
@r{[}@var{\varname\}@r{]}
@end macro
@defmac AM_PATH_LIBGCRYPT (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
-Check whether @acronym{Libgcrypt} (at least version
+Check whether Libgcrypt (at least version
@var{minimum-version}, if given) exists on the host system. If it is
found, execute @var{action-if-found}, otherwise do
@var{action-if-not-found}, if given.
@@ -357,7 +356,7 @@
Additionally, the function defines @code{LIBGCRYPT_CFLAGS} to the
flags needed for compilation of the program to find the
@file{gcrypt.h} header file, and @code{LIBGCRYPT_LIBS} to the linker
-flags needed to link the program to the @acronym{Libgcrypt} library.
+flags needed to link the program to the Libgcrypt library.
@end defmac
You can use the defined Autoconf variables like this in your
@@ -371,28 +370,36 @@
@node Initializing the library
@section Initializing the library
-It is often desirable to check that the version of `@acronym{Libgcrypt}' used is
-indeed one which fits all requirements. Even with binary compatibility
-new features may have been introduced but due to problem with the
-dynamic linker an old version is actually used. So you may want to
-check that the version is okay right after program startup.
+Before the library can be used, it must initialize itself. This is
+achieved by invoking the function @code{gcry_check_version} described
+below.
+Also, it is often desirable to check that the version of
+Libgcrypt used is indeed one which fits all requirements.
+Even with binary compatibility, new features may have been introduced,
+but due to problem with the dynamic linker an old version may actually
+be used. So you may want to check that the version is okay right
+after program startup.
+
@deftypefun const char *gcry_check_version (const char *@var{req_version})
-The function @code{gcry_check_version} has three purposes. It can be
-used to retrieve the version number of the library. In addition it
-can verify that the version number is higher than a certain required
-version number.
+The function @code{gcry_check_version} initializes the sub-systems
+used by Libgcrypt and must be invoked before any other function in the
+library, with the exception of the @code{GCRYCTL_SET_THREAD_CBS}
+command (called via the @code{gcry_control} function), see
+ at xref{Multi-Threading}.
-In either case, the function initializes some sub-systems, and for
-this reason alone it must be invoked early in your program, before you
-make use of the other functions of @acronym{Libgcrypt}.
+Furthermore, this function returns the version number of the library.
+It can also verify that the version number is higher than a certain
+required version number @var{req_version}, if this value is not a null
+pointer.
@end deftypefun
- at node Multi Threading
- at section Multi Threading
-As mentioned earlier, the `@acronym{Libgcrypt}' library is
+ at node Multi-Threading
+ at section Multi-Threading
+
+As mentioned earlier, the Libgcrypt library is
thread-safe if you adhere to the following requirements:
@itemize @bullet
@@ -431,12 +438,12 @@
The function @code{gcry_check_version} must be called before any other
function in the library, except the @code{GCRYCTL_SET_THREAD_CBS}
command (called via the @code{gcry_control} function), because it
-initializes the thread support subsystem in @acronym{Libgcrypt}. To
+initializes the thread support subsystem in Libgcrypt. To
achieve this in multi-threaded programs, you must synchronize the
memory with respect to other threads that also want to use
- at acronym{Libgcrypt}. For this, it is sufficient to call
+Libgcrypt. For this, it is sufficient to call
@code{gcry_check_version} before creating the other threads using
- at acronym{Libgcrypt}@footnote{At least this is true for POSIX threads,
+Libgcrypt at footnote{At least this is true for POSIX threads,
as @code{pthread_create} is a function that synchronizes memory with
respects to other threads. There are many functions which have this
property, a complete list can be found in POSIX, IEEE Std 1003.1-2003,
@@ -446,12 +453,13 @@
@item
-As with the function @code{gpg_strerror}, @code{gcry_strerror} is not
-thread safe. You have to use @code{gpg_strerror_r} instead.
+Just like the function @code{gpg_strerror}, the function
+ at code{gcry_strerror} is not thread safe. You have to use
+ at code{gpg_strerror_r} instead.
@end itemize
- at acronym{Libgcrypt} contains convenient macros, which define the
+Libgcrypt contains convenient macros, which define the
necessary thread callbacks for PThread and for GNU Pth:
@table @code
@@ -488,7 +496,7 @@
@chapter Generalities
@menu
-* Controlling the library:: Controlling @acronym{Libgcrypt}'s behavior.
+* Controlling the library:: Controlling Libgcrypt's behavior.
* Modules:: Description of extension modules.
* Error Handling:: Error codes and such.
@end menu
@@ -499,7 +507,7 @@
@deftypefun gcry_error_t gcry_control (enum gcry_ctl_cmds @var{cmd}, ...)
This function can be used to influence the general behavior of
- at acronym{Libgcrypt} in several ways. Depending on @var{cmd}, more
+Libgcrypt in several ways. Depending on @var{cmd}, more
arguments can or have to be provided.
@table @code
@@ -581,7 +589,7 @@
@node Modules
@section Modules
- at acronym{Libgcrypt} supports the use of `extension modules', which
+Libgcrypt supports the use of `extension modules', which
implement algorithms in addition to those already built into the library
directly.
@@ -595,7 +603,7 @@
category. This ID can be used to reference the newly registered
module. After registering a module successfully, the new functionality
should be able to be used through the normal functions provided by
- at acronym{Libgcrypt} until it is unregistered again.
+Libgcrypt until it is unregistered again.
@c **********************************************************
@c ******************* Errors ****************************
@@ -603,7 +611,7 @@
@node Error Handling
@section Error Handling
-Many functions in @acronym{Libgcrypt} can return an error if they
+Many functions in Libgcrypt can return an error if they
fail. For this reason, the application should always catch the error
condition and take appropriate measures, for example by releasing the
resources and passing the error up to the caller, or by displaying a
@@ -618,20 +626,20 @@
specific meanings if returned by a certain functions. Such cases are
described in the documentation of those functions.
- at acronym{Libgcrypt} uses the @code{libgpg-error} library. This allows
-to share the error codes with other components of the GnuPG system,
-and thus pass error values transparently from the crypto engine, or
-some helper application of the crypto engine, to the user. This way
-no information is lost. As a consequence, @acronym{Libgcrypt} does
-not use its own identifiers for error codes, but uses those provided
-by @code{libgpg-error}. They usually start with @code{GPG_ERR_}.
+Libgcrypt uses the @code{libgpg-error} library. This allows to share
+the error codes with other components of the GnuPG system, and to pass
+error values transparently from the crypto engine, or some helper
+application of the crypto engine, to the user. This way no
+information is lost. As a consequence, Libgcrypt does not use its own
+identifiers for error codes, but uses those provided by
+ at code{libgpg-error}. They usually start with @code{GPG_ERR_}.
-However, @acronym{Libgcrypt} does provide aliases for the functions
+However, Libgcrypt does provide aliases for the functions
defined in libgpg-error, which might be preferred for name space
consistency.
-Most functions in @acronym{Libgcrypt} return an error code in the case
+Most functions in Libgcrypt return an error code in the case
of failure. For this reason, the application should always catch the
error condition and take appropriate measures, for example by
releasing the resources and passing the error up to the caller, or by
@@ -691,7 +699,7 @@
(@code{GPG_ERR_NO_ERROR}), and that in this case all other parts of
the error value are set to 0, too.
-Note that in @acronym{Libgcrypt}, the error source is used purely for
+Note that in Libgcrypt, the error source is used purely for
diagnostic purposes. Only the error code should be checked to test
for a certain outcome of a function. The manual only documents the
error code part of an error value. The error source is left
@@ -829,7 +837,7 @@
@item GPG_ERR_SOURCE_USER_4
These error sources are not used by any GnuPG component and can be
used by other software. For example, applications using
- at acronym{Libgcrypt} can use them to mark error values coming from callback
+Libgcrypt can use them to mark error values coming from callback
handlers. Thus @code{GPG_ERR_SOURCE_USER_1} is the default for errors
created with @code{gcry_error} and @code{gcry_error_from_errno},
unless you define @code{GCRY_ERR_SOURCE_DEFAULT} before including
@@ -914,7 +922,7 @@
@item ...
@item GPG_ERR_USER_16
These error codes are not used by any GnuPG component and can be
-freely used by other software. Applications using @acronym{Libgcrypt}
+freely used by other software. Applications using Libgcrypt
might use them to mark specific errors returned by callback handlers
if no suitable error codes (including the system errors) for these
errors exist already.
@@ -967,8 +975,8 @@
@node Handler Functions
@chapter Handler Functions
- at acronym{Libgcrypt} makes it possible to install so called `handler functions',
-which get called by @acronym{Libgcrypt} in case of certain events.
+Libgcrypt makes it possible to install so called `handler functions',
+which get called by Libgcrypt in case of certain events.
@menu
* Progress handler:: Using a progress handler function.
@@ -1048,7 +1056,7 @@
@node Allocation handler
@section Allocation handler
-It is possible to make @acronym{Libgcrypt} use special memory
+It is possible to make Libgcrypt use special memory
allocation functions instead of the built-in ones.
Memory allocation functions are of the following types:
@@ -1077,7 +1085,7 @@
@section Error handler
The following functions may be used to register handler functions that
-are called by @acronym{Libgcrypt} in case certain error conditions
+are called by Libgcrypt in case certain error conditions
occur.
@deftp {Data type} gcry_handler_no_mem_t
@@ -1107,7 +1115,7 @@
@deftypefun void gcry_set_log_handler (gcry_handler_log_t @var{func_log}, void *@var{cb_data})
This function registers @var{func_log} as `logging handler', which
-means that it will be called in case @acronym{Libgcrypt} wants to log
+means that it will be called in case Libgcrypt wants to log
a message.
@end deftypefun
@@ -1121,7 +1129,7 @@
The cipher functions are used for symmetrical cryptography,
i.e. cryptography using a shared key. The programming model follows
an open/process/close paradigm and is in that similar to other
-building blocks provided by @acronym{Libgcrypt}.
+building blocks provided by Libgcrypt.
@menu
* Available ciphers:: List of ciphers supported by the library.
@@ -1210,10 +1218,10 @@
@node Cipher modules
@section Cipher modules
- at acronym{Libgcrypt} makes it possible to load additional `cipher
-modules'; these cipher can be used just like the cipher algorithms
-that are built into the library directly. For an introduction into
-extension modules, see @xref{Modules}.
+Libgcrypt makes it possible to load additional `cipher modules'; these
+ciphers can be used just like the cipher algorithms that are built
+into the library directly. For an introduction into extension
+modules, see @xref{Modules}.
@deftp {Data type} gcry_cipher_spec_t
This is the `module specification structure' needed for registering
@@ -1382,10 +1390,10 @@
@table @code
@item GCRY_CIPHER_SECURE
Make sure that all operations are allocated in secure memory. This is
-useful, when the key material is highly confidential.
+useful when the key material is highly confidential.
@item GCRY_CIPHER_ENABLE_SYNC
This flag enables the CFB sync mode, which is a special feature of
- at acronym{Libgcrypt}'s CFB mode implementation to allow for OpenPGP's CFB variant.
+Libgcrypt's CFB mode implementation to allow for OpenPGP's CFB variant.
See @code{gcry_cipher_sync}.
@item GCRY_CIPHER_CBC_CTS
Enable cipher text stealing (CTS) for the CBC mode. Cannot be used
@@ -1418,8 +1426,8 @@
function checks this and returns an error if there is a problem. A
caller should always check for an error.
-Note, this is currently implemented as a macro but may be changed to a
-function in the future.
+Note that this is currently implemented as a macro but may be changed
+to a function in the future.
@end deftypefun
Most crypto modes requires an initialization vector (IV), which
@@ -1432,7 +1440,7 @@
Set the initialization vector used for encryption or decryption. The
vector is passed as the buffer @var{K} of length @var{l} and copied to
internal data structures. The function checks that the IV matches the
-requirement of the selected algorithm and mode. Note, that this is
+requirement of the selected algorithm and mode. Note that this is
implemented as a macro.
@end deftypefun
@@ -1442,7 +1450,7 @@
is passed as the buffer @var{c} of length @var{l} and copied to
internal data structures. The function checks that the counter
matches the requirement of the selected algorithm (i.e., it must be
-the same size as the block size). Note, that this is implemented as a
+the same size as the block size). Note that this is implemented as a
macro.
@end deftypefun
@@ -1451,7 +1459,7 @@
Set the given handle's context back to the state it had after the last
call to gcry_cipher_setkey and clear the initialization vector.
-Note, that gcry_cipher_reset is implemented as a macro.
+Note that gcry_cipher_reset is implemented as a macro.
@end deftypefun
The actual encryption and decryption is done by using one of the
@@ -1469,7 +1477,7 @@
@var{inlen} bytes are encrypted to the buffer @var{out} which must have
at least a size of @var{inlen}. @var{outsize} must be set to the
allocated size of @var{out}, so that the function can check that there
-is sufficient space. Note, that overlapping buffers are not allowed.
+is sufficient space. Note that overlapping buffers are not allowed.
Depending on the selected algorithms and encryption mode, the length of
the buffers must be a multiple of the block size.
@@ -1489,7 +1497,7 @@
@var{inlen} bytes are decrypted to the buffer @var{out} which must have
at least a size of @var{inlen}. @var{outsize} must be set to the
allocated size of @var{out}, so that the function can check that there
-is sufficient space. Note, that overlapping buffers are not allowed.
+is sufficient space. Note that overlapping buffers are not allowed.
Depending on the selected algorithms and encryption mode, the length of
the buffers must be a multiple of the block size.
@@ -1499,11 +1507,11 @@
OpenPGP (as defined in RFC-2440) requires a special sync operation in
-some places, the following function is used for this:
+some places. The following function is used for this:
@deftypefun gcry_error_t gcry_cipher_sync (gcry_cipher_hd_t @var{h})
-Perform the OpenPGP sync operation on context @var{h}. Note, that this
+Perform the OpenPGP sync operation on context @var{h}. Note that this
is a no-op unless the context was created with the flag
@code{GCRY_CIPHER_ENABLE_SYNC}
@end deftypefun
@@ -1602,12 +1610,12 @@
@node Hashing
@chapter Hashing
- at acronym{Libgcrypt} provides an easy and consistent to use interface
+Libgcrypt provides an easy and consistent to use interface
for hashing. Hashing is buffered and several hash algorithms can be
updated at once. It is possible to calculate a MAC using the same
routines. The programming model follows an open/process/close
paradigm and is in that similar to other building blocks provided by
- at acronym{Libgcrypt}.
+Libgcrypt.
For convenience reasons, a few cyclic redundancy check value operations
are also supported.
@@ -1690,7 +1698,7 @@
@node Hash algorithm modules
@section Hash algorithm modules
- at acronym{Libgcrypt} makes it possible to load additional `message
+Libgcrypt makes it possible to load additional `message
digest modules'; these digests can be used just like the message digest
algorithms that are built into the library directly. For an
introduction into extension modules, see @xref{Modules}.
@@ -1948,7 +1956,7 @@
@var{algo}. This required size may be obtained by using the function
@code{gcry_md_get_algo_dlen}.
-Note, that this function will abort the process if an unavailable
+Note that this function will abort the process if an unavailable
algorithm is used.
@end deftypefun
@@ -2019,7 +2027,7 @@
@deftypefun int gcry_md_get_algo (gcry_md_hd_t @var{h})
-Retrieve the algorithm used with the handle @var{h}. Note, that this
+Retrieve the algorithm used with the handle @var{h}. Note that this
does not work reliable if more than one algorithm is enabled in @var{h}.
@end deftypefun
@@ -2042,7 +2050,7 @@
Tracking bugs related to hashing is often a cumbersome task which
requires to add a lot of printf statements into the code.
- at acronym{Libgcrypt} provides an easy way to avoid this. The actual data
+Libgcrypt provides an easy way to avoid this. The actual data
hashed can be written to files on request.
@deftypefun void gcry_md_debug (gcry_md_hd_t @var{h}, const char *@var{suffix})
@@ -2088,7 +2096,7 @@
Public key cryptography, also known as asymmetric cryptography, is an
easy way for key management and to provide digital signatures.
- at acronym{Libgcrypt} provides two completely different interfaces to
+Libgcrypt provides two completely different interfaces to
public key cryptography, this chapter explains the one based on
S-expressions.
@@ -2103,16 +2111,16 @@
@node Available algorithms
@section Available algorithms
- at acronym{Libgcrypt} supports the RSA (Rivest-Shamir-Adleman) algorithms as well
+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.
@node Used S-expressions
@section Used S-expressions
- at acronym{Libgcrypt}'s API for asymmetric cryptography is based on data
+Libgcrypt's API for asymmetric cryptography is based on data
structures called S-expressions (see XXXX) and does not work with
-contexts as most of the other building blocks of @acronym{Libgcrypt}
+contexts as most of the other building blocks of Libgcrypt
do.
The following information are stored in S-expressions:
@@ -2129,7 +2137,7 @@
@end table
@noindent
-To describe how @acronym{Libgcrypt} expect keys, we use some examples. Note that
+To describe how Libgcrypt expect keys, we use some examples. Note that
words in
@ifnottex
uppercase
@@ -2208,7 +2216,7 @@
@node Public key modules
@section Public key modules
- at acronym{Libgcrypt} makes it possible to load additional `public key
+Libgcrypt makes it possible to load additional `public key
modules'; these public key algorithms can be used just like the
algorithms that are built into the library directly. For an
introduction into extension modules, see @xref{Modules}.
@@ -2339,7 +2347,7 @@
@section Cryptographic Functions
@noindent
-Note, that we will in future allow to use keys without p,q and u
+Note that we will in future allow to use keys without p,q and u
specified and may also support other parameters for performance
reasons.
@@ -2375,7 +2383,7 @@
operation, like e.g. padding rules.
@noindent
-If you don't want to let @acronym{Libgcrypt} handle the padding, you must pass an
+If you don't want to let Libgcrypt handle the padding, you must pass an
appropriate MPI using this expression for @var{data}:
@example
@@ -2405,7 +2413,7 @@
If the function could successfully perform the encryption, the return
value will be 0 and a a new S-expression with the encrypted result is
-allocated and assign to the variable at the address of @var{r_ciph}.
+allocated and assigned to the variable at the address of @var{r_ciph}.
The caller is responsible to release this value using
@code{gcry_sexp_release}. In case of an error, an error code is
returned and @var{r_ciph} will be set to @code{NULL}.
@@ -2453,7 +2461,7 @@
@end example
@noindent
-Note, that this function currently does not know of any padding
+Note that this function currently does not know of any padding
methods and the caller must do any un-padding on his own.
@noindent
@@ -2474,7 +2482,7 @@
Another operation commonly performed using public key cryptography is
signing data. In some sense this is even more important than
encryption because digital signatures are an important instrument for
-key management. @acronym{Libgcrypt} supports digital signatures using
+key management. Libgcrypt supports digital signatures using
2 functions, similar to the encryption functions:
@deftypefun gcry_error_t gcry_pk_sign (@w{gcry_sexp_t *@var{r_sig},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{skey}})
@@ -2483,7 +2491,7 @@
private key @var{skey} and place it into the variable at the address of
@var{r_sig}. @var{data} may either be the simple old style S-expression
with just one MPI or a modern and more versatile S-expression which
-allows to let @acronym{Libgcrypt} handle padding:
+allows to let Libgcrypt handle padding:
@example
(data
@@ -2495,7 +2503,7 @@
This example requests to sign the data in @var{block} after applying
PKCS#1 block type 1 style padding. @var{hash-algo} is a string with the
hash algorithm to be encoded into the signature, this may be any hash
-algorithm name as supported by @acronym{Libgcrypt}. Most likely, this will be
+algorithm name as supported by Libgcrypt. Most likely, this will be
"sha1", "rmd160" or "md5". It is obvious that the length of @var{block}
must match the size of that message digests; the function checks that
this and other constraints are valid.
@@ -2543,7 +2551,7 @@
@noindent
The operation most commonly used is definitely the verification of a
-signature. @acronym{Libgcrypt} provides this function:
+signature. Libgcrypt provides this function:
@deftypefun gcry_error_t gcry_pk_verify (@w{gcry_sexp_t @var{sig}}, @w{gcry_sexp_t @var{data}}, @w{gcry_sexp_t @var{pkey}})
@@ -2587,7 +2595,7 @@
@deftypefun int gcry_pk_test_algo (int @var{algo})
Return 0 if the public key algorithm @var{algo} is available for use.
-Note, that this is implemented as a macro.
+Note that this is implemented as a macro.
@end deftypefun
@@ -2612,7 +2620,7 @@
@deftypefun gcry_error_t gcry_pk_testkey (gcry_sexp_t @var{key})
Return zero if the private key @var{key} is `sane', an error code otherwise.
-Note, that it is not possible to check the `saneness' of a public key.
+Note that it is not possible to check the `saneness' of a public key.
@end deftypefun
@@ -2620,7 +2628,7 @@
@deftypefun gcry_error_t gcry_pk_algo_info (@w{int @var{algo}}, @w{int @var{what}}, @w{void *@var{buffer}}, @w{size_t *@var{nbytes}})
Depending on the value of @var{what} return various information about
-the public key algorithm with the id @var{algo}. Note, that the
+the public key algorithm with the id @var{algo}. Note that the
function returns @code{-1} on error and the actual error code must be
retrieved using the function @code{gcry_errno}. The currently defined
values for @var{what} are:
@@ -2689,7 +2697,7 @@
@c end gcry_pk_ctl
@noindent
- at acronym{Libgcrypt} also provides a function for generating public key
+Libgcrypt also provides a function for generating public key
pairs:
@deftypefun gcry_error_t gcry_pk_genkey (@w{gcry_sexp_t *@var{r_key}}, @w{gcry_sexp_t @var{parms}})
@@ -2737,7 +2745,7 @@
@end table
@noindent
-If this parameter is not used, @acronym{Libgcrypt} uses for historic reasons
+If this parameter is not used, Libgcrypt uses for historic reasons
65537.
@item qbits
@@ -2756,7 +2764,7 @@
w at item N = 15360
Q = 512
@end table
-Note, that in this case only the values for N, as given in the table,
+Note that in this case only the values for N, as given in the table,
are allowed. When specifying Q all values of N in the range 512 to
15680 are valid as long as they are multiples of 8.
@@ -2820,7 +2828,7 @@
@node Available asymmetric algorithms
@section Available asymmetric algorithms
- at acronym{Libgcrypt} supports the RSA (Rivest-Shamir-Adleman)
+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.
@@ -3093,12 +3101,12 @@
has the following meanings:
@table @code
@item = 0
-Let @acronym{Libgcrypt} decide what exponent should be used.
+Let 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.
@item > 2
-Try starting at this value until a working exponent is found. Note,
+Try starting at this value until a working exponent is found. Note
that the current implementation leaks some information about the
private key because the incrementation used is not randomized. Thus,
this function will be changed in the future to return a random
@@ -3336,7 +3344,7 @@
@chapter Random Numbers
@menu
-* Quality of random numbers:: @acronym{Libgcrypt} uses different quality levels.
+* Quality of random numbers:: Libgcrypt uses different quality levels.
* Retrieving random numbers:: How to retrieve random numbers.
@end menu
@@ -3403,7 +3411,7 @@
S-expressions are used by the public key functions to pass complex data
structures around. These LISP like objects are used by some
-cryptographic protocols (cf. RFC-2692) and @acronym{Libgcrypt} provides functions
+cryptographic protocols (cf. RFC-2692) and Libgcrypt provides functions
to parse and construct them. For detailed information, see
@cite{Ron Rivest, code and description of S-expressions,
@uref{http://theory.lcs.mit.edu/~rivest/sexp.html}}.
@@ -3417,7 +3425,7 @@
@section Data types for S-expressions
@deftp {Data type} gcry_sexp_t
-The @code{gcry_sexp_t} type describes an object with the @acronym{Libgcrypt} internal
+The @code{gcry_sexp_t} type describes an object with the Libgcrypt internal
representation of an S-expression.
@end deftp
@@ -3425,7 +3433,7 @@
@section Working with S-expressions
@noindent
-There are several functions to create an @acronym{Libgcrypt} S-expression object
+There are several functions to create an Libgcrypt S-expression object
from its external representation or from a string template. There is
also a function to convert the internal representation back into one of
the external formats:
@@ -3441,7 +3449,7 @@
the defined external formats. If @var{buffer} does not hold a valid
S-expression an error code is returned and @var{r_sexp} set to
@code{NULL}.
-Note, that the caller is responsible for releasing the newly allocated
+Note that the caller is responsible for releasing the newly allocated
S-expression using @code{gcry_sexp_release}.
@end deftypefun
@@ -3452,7 +3460,7 @@
to be a function to release the @var{buffer}; most likely the standard
@code{free} function is used for this argument. This has the effect of
transferring the ownership of @var{buffer} to the created object in
- at var{r_sexp}. The advantage of using this function is that @acronym{Libgcrypt}
+ at var{r_sexp}. The advantage of using this function is that Libgcrypt
might decide to directly use the provided buffer and thus avoid extra
copying.
@end deftypefun
@@ -3492,7 +3500,7 @@
@end table
@noindent
-No other format characters are defined and would return an error. Note,
+No other format characters are defined and would return an error. Note
that the format character @samp{%%} does not exists, because a percent
sign is not a valid character in an S-expression.
@end deftypefun
@@ -3538,7 +3546,7 @@
@deftypefun void gcry_sexp_dump (@w{gcry_sexp_t @var{sexp}})
-Dumps @var{sexp} in a format suitable for debugging to @acronym{Libgcrypt}'s
+Dumps @var{sexp} in a format suitable for debugging to Libgcrypt's
logging stream.
@end deftypefun
@@ -3597,7 +3605,7 @@
@deftypefun gcry_sexp_t gcry_sexp_cdr (@w{const gcry_sexp_t @var{list}})
Create and return a new list form all elements except for the first one.
-Note, that this function may return an invalid S-expression because it
+Note that this function may return an invalid S-expression because it
is not guaranteed, that the type exists and is a string. However, for
parsing a complex S-expression it might be useful for intermediate
lists. Returns @code{NULL} on error.
@@ -3630,7 +3638,7 @@
This function is used to get and convert data from a @var{list}. This
data is assumed to be an MPI stored in the format described by
- at var{mpifmt} and returned as a standard @acronym{Libgcrypt} MPI. The caller must
+ at var{mpifmt} and returned as a standard Libgcrypt MPI. The caller must
release this returned value using @code{gcry_mpi_release}. If there is
no data at the given index, the index represents a list or the value
can't be converted to an MPI, @code{NULL} is returned.
@@ -3656,7 +3664,7 @@
Public key cryptography is based on mathematics with large numbers. To
implement the public key functions, a library for handling these large
numbers is required. Because of the general usefulness of such a
-library, its interface is exposed by @acronym{Libgcrypt}. The implementation is
+library, its interface is exposed by Libgcrypt. The implementation is
based on an old release of GNU Multi-Precision Library (GMP) but in the
meantime heavily modified and stripped down to what is required for
cryptography. For a lot of CPUs, high performance assembler
@@ -3664,7 +3672,7 @@
better performance than with the standard C implementation.
@noindent
-In the context of @acronym{Libgcrypt} and in most other applications, these large
+In the context of Libgcrypt and in most other applications, these large
numbers are called MPIs (multi-precision-integers).
@node Data types
@@ -3686,7 +3694,7 @@
Allocate a new MPI object, initialize it to 0 and initially allocate
enough memory for a number of at least @var{nbits}. This pre-allocation is
only a small performance issue and not actually necessary because
- at acronym{Libgcrypt} automatically re-allocates the required memory.
+Libgcrypt automatically re-allocates the required memory.
@end deftypefun
@deftypefun gcry_mpi_t gcry_mpi_snew (@w{unsigned int @var{nbits}})
@@ -3739,7 +3747,7 @@
@noindent
The following functions are used to convert between an external
-representation of an MPI and the internal one of @acronym{Libgcrypt}.
+representation of an MPI and the internal one of Libgcrypt.
@deftypefun gcry_error_t gcry_mpi_scan (@w{gcry_mpi_t *@var{r_mpi}}, @w{enum gcry_mpi_format @var{format}}, @w{const unsigned char *@var{buffer}}, @w{size_t @var{buflen}}, @w{size_t *@var{nscanned}})
@@ -3773,7 +3781,7 @@
@end table
@noindent
-Note, that all of the above formats store the integer in big-endian
+Note that all of the above formats store the integer in big-endian
format (MSB first).
@end deftypefun
@@ -3819,7 +3827,7 @@
@deftypefun void gcry_mpi_add_ui (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{v}})
- at math{@var{w} = @var{u} + @var{v}}. Note, that @var{v} is an unsigned integer.
+ at math{@var{w} = @var{u} + @var{v}}. Note that @var{v} is an unsigned integer.
@end deftypefun
@@ -3980,7 +3988,7 @@
@deftypefun {void *} gcry_mpi_get_opaque (@w{gcry_mpi_t @var{a}}, @w{unsigned int *@var{nbits}})
Return a pointer to an opaque value stored in @var{a} and return its
-size in @var{nbits}. Note, that the returned pointer is still owned by
+size in @var{nbits}. Note that the returned pointer is still owned by
@var{a} and that the function should never be used for an non-opaque
MPI.
@end deftypefun
@@ -3994,7 +4002,7 @@
@deftypefun void gcry_mpi_clear_flag (@w{gcry_mpi_t @var{a}}, @w{enum gcry_mpi_flag @var{flag}})
-Clear @var{flag} for the big integer @var{a}. Note, that this function is
+Clear @var{flag} for the big integer @var{a}. Note that this function is
currently useless as no flags are allowed.
@end deftypefun
More information about the Gnupg-commits
mailing list