From 333e3fac8a4e3fe018e0505e67cccf23d2d97747 Mon Sep 17 00:00:00 2001 From: Nikos Mavrogiannopoulos Date: Mon, 24 Sep 2012 20:44:48 +0200 Subject: [PATCH] openpgp doc update --- doc/cha-cert-auth.texi | 78 +++++++++++++++++++++++++++++++++++++++++++++----- lib/openpgp/pgp.c | 8 ++---- 2 files changed, 73 insertions(+), 13 deletions(-) diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi index 144de2c68..46195f9fe 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 diff --git a/lib/openpgp/pgp.c b/lib/openpgp/pgp.c index fb7708772..dc6cadcad 100644 --- a/lib/openpgp/pgp.c +++ b/lib/openpgp/pgp.c @@ -1586,14 +1586,10 @@ gnutls_openpgp_crt_set_preferred_key_id (gnutls_openpgp_crt_t key, * gnutls_openpgp_crt_get_auth_subkey: * @crt: the structure that contains the OpenPGP public key. * @keyid: the struct to save the keyid. - * @flag: Non (0) indicates that a valid subkey is always returned. + * @flag: Non-zero indicates that a valid subkey is always returned. * * Returns the 64-bit keyID of the first valid OpenPGP subkey marked - * for authentication. If flag is non (0) and no authentication - * subkey exists, then a valid subkey will be returned even if it is - * not marked for authentication. - * Returns the 64-bit keyID of the first valid OpenPGP subkey marked - * for authentication. If flag is non (0) and no authentication + * for authentication. If flag is non-zero and no authentication * subkey exists, then a valid subkey will be returned even if it is * not marked for authentication. * -- 2.11.4.GIT