more updates

1 files changed, 35 insertions, 17 deletions

diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi
index 437c68d034..30e9619aaa 100644
--- a/doc/cha-cert-auth.texi
+++ b/doc/cha-cert-auth.texi
@@ -28,11 +28,11 @@ certificates as well, following a hierarchical model.
 One needs to trust one or more CAs for his secure communications. In
 that case only the certificates issued by the trusted authorities are
 acceptable.  The framework is illustrated on @ref{fig:x509}.
-Detailed examples involving X.509 certificates are listed below.
 
 @menu
 * X.509 certificates::
 * Verifying X.509 certificate paths::
+* Verifying a certificate in the context of TLS session::
 * Certificate requests::
 * PKCS 12 structures::
 @end menu
@@ -141,7 +141,6 @@ demonstrate the @acronym{X.509} parsing capabilities can be found at
 @node Verifying X.509 certificate paths
 @subsection Verifying @acronym{X.509} certificate paths
 @cindex Verifying certificate paths
-@tindex gnutls_certificate_verify_flags
 
 Verifying certificate paths is important in @acronym{X.509}
 authentication. For this purpose the following functions are
@@ -158,11 +157,17 @@ provided.
 The verification function will verify a given certificate chain against a list of certificate
 authorities and certificate revocation lists, and output
 a bit-wise OR of elements of the @code{gnutls_certificate_status_t} 
-enumeration. It is also possible to have a set of certificates that
-are trusted for a particular server but not to authorize other certificates.
-This purpose is served by the functions @funcref{gnutls_x509_trust_list_add_named_crt} and @funcref{gnutls_x509_trust_list_verify_named_crt}.
+enumeration. 
 A detailed description of these elements can be found 
 in @ref{tab:cert-verify}. An example of certificate verification is shown in @ref{ex:verify2}.
+It is also possible to have a set of certificates that
+are trusted for a particular server but not to authorize other certificates.
+This purpose is served by the functions @funcref{gnutls_x509_trust_list_add_named_crt} and @funcref{gnutls_x509_trust_list_verify_named_crt}.
+
+@node Verifying a certificate in the context of TLS session
+@subsection Verifying a certificate in the context of TLS session
+@cindex Verifying certificate paths
+@tindex gnutls_certificate_verify_flags
 
 When operating in the context of a TLS session, the trusted certificate
 authority list has been set via the
@@ -201,7 +206,7 @@ MD5.  These algorithms have been broken and should not be trusted.
 @caption{Certificate verification output flags.}
 @end float
 
-There is also to possibility to pass some input to the verification
+There is also the possibility to pass some input to the verification
 functions in the form of flags. For @funcref{gnutls_x509_trust_list_verify_crt} the
 flags are passed straightforward, but
 @funcref{gnutls_certificate_verify_peers2} depends on the flags set by
@@ -270,7 +275,7 @@ A certificate request is a structure, which contain information about
 an applicant of a certificate service.  It usually contains a private
 key, a distinguished name and secondary data such as a challenge
 password. @acronym{GnuTLS} supports the requests defined in
-@acronym{PKCS} #10 @xcite{RFC2986}. Other certificate request's format
+@acronym{PKCS} #10 @xcite{RFC2986}. Other formats of certificate requests
 are not currently supported.
 
 The following example is about generating a certificate request, and a
@@ -290,9 +295,9 @@ export and import the user's identities.
 
 In @acronym{GnuTLS} the @acronym{PKCS} #12 structures are handled
 using the @code{gnutls_pkcs12_t} type. This is an abstract type that
-may hold several @code{gnutls_pkcs12_bag_t} types.  The Bag types are
+may hold several @code{gnutls_pkcs12_bag_t} types.  The bag types are
 the holders of the actual data, which may be certificates, private
-keys or encrypted data.  An Bag of type encrypted should be decrypted
+keys or encrypted data.  A bag of type encrypted should be decrypted
 in order for its data to be accessed.
 
 An example of a @acronym{PKCS} #12 structure generation can be found
@@ -340,7 +345,7 @@ and the corresponding private keys with the
 @code{gnutls_openpgp_privkey_t} type. All the prototypes for the key
 handling functions can be found at @file{gnutls/openpgp.h}.
 
-@subsection Verifying an @acronym{OpenPGP} key
+@subsection Verifying an @acronym{OpenPGP} certificate
 
 The verification functions of @acronym{OpenPGP} keys, included in
 @acronym{GnuTLS}, are simple ones, and do not use the features of the
@@ -349,8 +354,8 @@ complex, the assistance of external tools like @acronym{GnuPG} and
 GPGME@footnote{@url{http://www.gnupg.org/related_software/gpgme/}} is
 recommended.
 
-There is one verification function in @acronym{GnuTLS}, the
-@funcref{gnutls_openpgp_crt_verify_ring}.  This checks an
+In GnuTLS there is a verification function for OpenPGP certificates,
+the @funcref{gnutls_openpgp_crt_verify_ring}.  This checks an
 @acronym{OpenPGP} key against a given set of public keys (keyring) and
 returns the key status. The key verification status is the same as in
 @acronym{X.509} certificates, although the meaning and interpretation
@@ -358,6 +363,10 @@ are different. For example an @acronym{OpenPGP} key may be valid, if
 the self signature is ok, even if no signers were found.  The meaning
 of verification status is shown in the figure below.
 
+@showfuncdesc{gnutls_openpgp_crt_verify_ring}
+
+@showfuncdesc{gnutls_openpgp_crt_verify_self}
+
 @table @code
 
 @item CERT_INVALID:
@@ -376,6 +385,15 @@ MD5.  These algorithms have been broken and should not be trusted.
 
 @end table
 
+@subsection Verifying a certificate in the context of a TLS session
+
+Similarly with X.509 certificates, one needs to specify
+the OpenPGP keyring file in the credentials structure. The certificates
+in this file will be  used by @funcref{gnutls_certificate_verify_peers2}
+to verify the signatures in the certificate sent by the peer.
+
+@showfuncdesc{gnutls_certificate_set_openpgp_keyring_file}
+
 
 @node Hardware tokens
 @section Hardware tokens
@@ -433,16 +451,16 @@ All @acronym{PKCS} #11 objects are referenced by @acronym{GnuTLS} functions by
 URLs as described in @code{draft-pechanec-pkcs11uri-03}. For example a public
 key on a smart card may be referenced as:
 
-@example
+@smallexample
 pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315; \
 manufacturer=EnterSafe;object=test1;objecttype=public;\
 id=32f153f3e37990b08624141077ca5dec2d15faed
-@end example
+@end smallexample
 
 while the smart card itself can be referenced as:
-@example
+@smallexample
 pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315;manufacturer=EnterSafe
-@end example
+@end smallexample
 
 
 @acronym{PKCS} #11 objects can be accessed with the functions shown below.
@@ -511,7 +529,7 @@ to a token. This can be achieved with the following functions
 It is possible to use a @acronym{PKCS} #11 token to a TLS
 session, as shown in @ref{ex:pkcs11-client}. In addition
 the following functions can be used to load PKCS #11 key and
-certificates.
+certificates, by specifying a PKCS #11 URL instead of a filename.
 
 @showfuncB{gnutls_certificate_set_x509_trust_file,gnutls_certificate_set_x509_key_file}