doc update

1 files changed, 84 insertions, 79 deletions

diff --git a/doc/cha-cert-auth2.texi b/doc/cha-cert-auth2.texi
index fa6c55d179..e375050a3c 100644
--- a/doc/cha-cert-auth2.texi
+++ b/doc/cha-cert-auth2.texi
@@ -57,17 +57,13 @@ which should return a signed certificate.
 @cindex CRL
 
 A certificate revocation list (CRL) is a structure issued by an authority
-periodically containing a list of revoked certificates serial numbers. 
+periodically containing a list of revoked certificates serial numbers.
 The CRL structure is signed with the issuing authorities' keys. A typical
 CRL contains the fields as shown in @ref{tab:crl}.
 Certificate revocation lists are used to complement the expiration date of a certificate,
 in order to account for other reasons of revocation, such as compromised keys, etc.
 
-A certificate request can be generated by
-associating it with a private key, setting the
-subject's information and finally self signing it.
-The last step ensures that the requester is in
-possession of the private key. Each CRL is valid for limited amount of
+Each CRL is valid for limited amount of
 time and is required to provide, except for the current issuing time, also 
 the issuing time of the next update.
 
@@ -101,6 +97,24 @@ Optional CRL structure extensions.
 @caption{Certificate revocation list fields.}
 @end float
 
+The basic CRL structure functions follow.
+
+@showfuncC{gnutls_x509_crl_init,gnutls_x509_crl_import,gnutls_x509_crl_export}
+
+@subheading Reading a CRL
+
+The most important function that extracts the certificate revocation
+information from a CRL is @funcref{gnutls_x509_crl_get_crt_serial}. Other
+functions that return other fields of the CRL structure are also provided.
+
+@showfuncdesc{gnutls_x509_crl_get_crt_serial}
+
+@showfuncE{gnutls_x509_crl_get_version,gnutls_x509_crl_get_issuer_dn,gnutls_x509_crl_get_this_update,gnutls_x509_crl_get_next_update,gnutls_x509_crl_get_crt_count}
+
+
+@subheading Generation of a CRL
+
+The following functions can be used to generate a CRL.
 
 @showfuncE{gnutls_x509_crl_set_version,gnutls_x509_crl_set_crt_serial,gnutls_x509_crl_set_crt,gnutls_x509_crl_set_next_update,gnutls_x509_crl_set_this_update}
 
@@ -140,10 +154,9 @@ in a CRL and/or perform an OCSP check for the certificate.
 Before performing the OCSP query, the application will need to figure
 out the address of the OCSP server.  The OCSP server address can be
 provided by the local user in manual configuration or may be stored
-in the certificate that is being checked.  The latter is due to
-an extension field called the Authority Information Access (AIA) which
-may hold the location of the OCSP responder in 
-the access method called @code{id-ad-ocsp}. The following function
+in the certificate that is being checked.  When stored in a certificate
+the OCSP server is in the extension field called the Authority Information 
+Access (AIA). The following function
 extracts this information from a certificate.
 
 @showfuncA{gnutls_x509_crt_get_authority_info_access}
@@ -191,19 +204,22 @@ requests are the following.
 
 @showfuncE{gnutls_ocsp_req_init,gnutls_ocsp_req_deinit,gnutls_ocsp_req_import,gnutls_ocsp_req_export,gnutls_ocsp_req_print}
 
-There are two interfaces for setting the identity of a certificate in
-a OCSP request, the first being a low-level function when you have the
+To generate an OCSP request the issuer name hash, issuer key hash, and 
+the checked certificate's serial number are required. There are two
+interfaces available for setting those in an OCSP request.
+The is a low-level function when you have the
 issuer name hash, issuer key hash, and certificate serial number in
-binary form.  The second is usually more useful if you have the
+binary form.  The second is more useful if you have the
 certificate (and its issuer) in a @code{gnutls_x509_crt_t} type.
-There is also a function to extract this information from an OCSP
+There is also a function to extract this information from existing an OCSP
 request.
 
 @showfuncC{gnutls_ocsp_req_add_cert_id,gnutls_ocsp_req_add_cert,gnutls_ocsp_req_get_cert_id}
 
 Each OCSP request may contain a number of extensions.  Extensions are
 identified by an Object Identifier (OID) and an opaque data buffer
-whose syntax and semantics is implied by the OID.
+whose syntax and semantics is implied by the OID. You can extract or
+set those extensions using the following functions.
 
 @showfuncB{gnutls_ocsp_req_get_extension,gnutls_ocsp_req_set_extension}
 
@@ -215,76 +231,65 @@ attacker will not be able to give a stale response for the same nonce.
 
 @showfuncC{gnutls_ocsp_req_get_nonce,gnutls_ocsp_req_set_nonce,gnutls_ocsp_req_randomize_nonce}
 
-The OCSP response structures is a bit more complex than the request.
-The important ASN.1 structure is as follows.  In practice, all OCSP
-responses contain a Basic OCSP response sub-structure.
+The OCSP response structures is a complex structure. A simplified overview
+of it is in @ref{tab:ocsp-response}. Note that a response may contain 
+information on multiple certificates.
+
+@float Table,tab:ocsp-response
+@multitable @columnfractions .2 .7
+
+@headitem Field @tab Description
+
+@item version @tab
+The OCSP response version number (typically 1).
+
+@item responder ID @tab
+An identifier of the responder (DN name or a hash of its key).
+
+@item issue time @tab
+The time the response was generated.
+
+@item thisUpdate @tab
+The issuing time of the revocation information.
+
+@item nextUpdate @tab
+The issuing time of the revocation information that will update that one.
+
+@item certificate status @tab
+The status of the certificate.
+
+@item certificate serial @tab
+The certificate's serial number.
+
+@item Revocation time @tab
+The time the certificate was revoked.
+
+@item Revocation reason @tab
+The reason the certificate was revoked.
+
+@end multitable
+@caption{The most important OCSP response fields.}
+@end float
 
-@example
-OCSPResponse ::= SEQUENCE @{
-   responseStatus         OCSPResponseStatus,
-   responseBytes          [0] EXPLICIT ResponseBytes OPTIONAL @}
-
-OCSPResponseStatus ::= ENUMERATED @{
-    successful            (0),  --Response has valid confirmations
-    malformedRequest      (1),  --Illegal confirmation request
-    internalError         (2),  --Internal error in issuer
-    tryLater              (3),  --Try again later
-                                --(4) is not used
-    sigRequired           (5),  --Must sign the request
-    unauthorized          (6)   --Request unauthorized @}
-
-ResponseBytes ::=       SEQUENCE @{
-    responseType   OBJECT IDENTIFIER,
-    response       OCTET STRING @}
-
-id-pkix-ocsp-basic     OBJECT IDENTIFIER ::= @{ id-pkix-ocsp 1 @}
-
-BasicOCSPResponse       ::= SEQUENCE @{
-   tbsResponseData      ResponseData,
-   signatureAlgorithm   AlgorithmIdentifier,
-   signature            BIT STRING,
-   certs                [0] EXPLICIT SEQUENCE OF Certificate OPTIONAL @}
-
-ResponseData ::= SEQUENCE @{
-   version              [0] EXPLICIT Version DEFAULT v1,
-   responderID              ResponderID,
-   producedAt               GeneralizedTime,
-   responses                SEQUENCE OF SingleResponse,
-   responseExtensions   [1] EXPLICIT Extensions OPTIONAL @}
-
-ResponderID ::= CHOICE @{
-   byName               [1] Name,
-   byKey                [2] KeyHash @}
-
-KeyHash ::= OCTET STRING -- SHA-1 hash of responder's public key
-(excluding the tag and length fields)
-
-SingleResponse ::= SEQUENCE @{
-   certID                       CertID,
-   certStatus                   CertStatus,
-   thisUpdate                   GeneralizedTime,
-   nextUpdate         [0]       EXPLICIT GeneralizedTime OPTIONAL,
-   singleExtensions   [1]       EXPLICIT Extensions OPTIONAL @}
-
-CertStatus ::= CHOICE @{
-    good        [0]     IMPLICIT NULL,
-    revoked     [1]     IMPLICIT RevokedInfo,
-    unknown     [2]     IMPLICIT UnknownInfo @}
-
-RevokedInfo ::= SEQUENCE @{
-    revocationTime              GeneralizedTime,
-    revocationReason    [0]     EXPLICIT CRLReason OPTIONAL @}
-@end example
 
 We provide basic functions for initialization, importing, exporting
-and deallocating OCSP responses.  The Basic OCSP Response structure is
-automatically parsed when an OCSP Response is imported.
+and deallocating OCSP responses.  
 
 @showfuncE{gnutls_ocsp_resp_init,gnutls_ocsp_resp_deinit,gnutls_ocsp_resp_import,gnutls_ocsp_resp_export,gnutls_ocsp_resp_print}
 
-The OCSP response needs to be verified against some set of trust
-anchors before it can be relied upon, and it is wise to check whether
-the OCSP response corresponds to the certificate being checked.
+The utility function that extracts the revocation as well as other information
+from a response is shown below.
+
+@showfuncdesc{gnutls_ocsp_resp_get_single}
+
+The possible revocation reasons available in an OCSP response are shown
+below.
+
+@showenumdesc{gnutls_x509_crl_reason_t,The revocation reasons}
+
+Note, that the OCSP response needs to be verified against some set of trust
+anchors before it can be relied upon. It is also important to check
+whether the received OCSP response corresponds to the certificate being checked.
 
 @showfuncC{gnutls_ocsp_resp_verify,gnutls_ocsp_resp_verify_direct,gnutls_ocsp_resp_check_crt}