openpgp doc update

1 files changed, 71 insertions, 7 deletions

diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi
index 144de2c681..46195f9fe0 100644
--- a/doc/cha-cert-auth.texi
+++ b/doc/cha-cert-auth.texi
@@ -50,8 +50,8 @@ of the Digital Signature Standard (DSS).
 @item ECDHE_@-ECDSA @tab
 The Elliptic curve DSA algorithm is used to sign ephemeral elliptic
 curve Diffie-Hellman parameters which are sent to the peer. The 
-certificate must contain ECDSA parameters to use this key exchange 
-algorithm. 
+certificate must contain ECDSA parameters (i.e., EC and marked for signing) 
+to use this key exchange algorithm. 
 
 @end multitable
 @caption{Supported key exchange algorithms.}
@@ -192,7 +192,7 @@ handled using the @code{gnutls_x509_crt_t} type and the corresponding
 private keys with the @code{gnutls_x509_privkey_t} type.  All the
 available functions for @acronym{X.509} certificate handling have
 their prototypes in @file{gnutls/x509.h}. An example program to
-demonstrate the @acronym{X.509} parsing capabilities can be found at
+demonstrate the @acronym{X.509} parsing capabilities can be found in
 @ref{ex:x509-info}.
 
 @node Importing an X.509 certificate
@@ -370,13 +370,77 @@ only Kevin, for some reason. A reason could be that Bob is lazy
 enough, and signs other people's keys without being sure that they
 belong to the actual owner.
 
+@float Table,tab:openpgp-certificate
+@multitable @columnfractions .2 .7
+
+@headitem Field @tab Description
+
+@item version @tab
+The field that indicates the version of the OpenPGP structure.
+
+@item user ID @tab
+An RFC 2822 string that identifies the owner of the key. There may be
+multiple user identifiers in a key.
+
+@item public key @tab
+The main public key of the certificate.
+
+@item expiration @tab
+The expiration time of the main public key.
+
+@item public subkey @tab
+An additional public key of the certificate. There may be multiple subkeys
+in a certificate.
+
+@item public subkey expiration @tab
+The expiration time of the subkey.
+
+@end multitable
+@caption{OpenPGP certificate fields.}
+@end float
+
+
 @subsection @acronym{OpenPGP} certificate structure
 
-In @acronym{GnuTLS} the @acronym{OpenPGP} key structures
-@xcite{RFC2440} are handled using the @code{gnutls_openpgp_crt_t} type
-and the corresponding private keys with the
+In @acronym{GnuTLS} the @acronym{OpenPGP} certificate structures
+@xcite{RFC2440} are handled using the @code{gnutls_openpgp_crt_t} type.
+A typical certificate contains the user ID, which is an RFC 2822
+mail and name address, a public key, possibly a number of additional
+public keys (called subkeys), and a number of signatures. The various
+fields are shown in @ref{tab:openpgp-certificate}.
+
+The additional subkeys may provide key for various different purposes,
+e.g. one key to encrypt mail, and another to sign a TLS key exchange.
+Each subkey is identified by a unique key ID.
+The keys that are to be used in a TLS key exchange that requires
+signatures are called authentication keys in the OpenPGP jargon.
+The mapping of TLS key exchange methods to public keys is shown in
+@ref{tab:openpgp-key-exchange}.
+
+@float Table,tab:openpgp-key-exchange
+@multitable @columnfractions .2 .7
+
+@headitem Key exchange @tab Public key requirements
+
+@item RSA @tab
+An RSA public key that allows encryption.
+
+@item DHE_@-RSA @tab
+An RSA public key that is marked for authentication.
+
+@item ECDHE_@-RSA @tab
+An RSA public key that is marked for authentication.
+
+@item DHE_@-DSS @tab
+A DSA public key that is marked for authentication.
+
+@end multitable
+@caption{The types of (sub)keys required for the various TLS key exchange methods.}
+@end float
+
+The corresponding private keys are stored in the
 @code{gnutls_openpgp_privkey_t} type. All the prototypes for the key
-handling functions can be found at @file{gnutls/openpgp.h}.
+handling functions can be found in @file{gnutls/openpgp.h}.
 
 @subsection Verifying an @acronym{OpenPGP} certificate