Add some OCSP documentation.

=pod

OCSP_REQUEST_new, OCSP_REQUEST_free, OCSP_request_add0_id, OCSP_request_sign,

OCSP_request_add1_cert, OCSP_request_onereq_count,

OCSP_request_onereq_get0 - OCSP request functions.

=head1 SYNOPSIS

 #include <openssl/ocsp.h>

 OCSP_REQUEST *OCSP_REQUEST_new(void);

 void OCSP_REQUEST_free(OCSP_REQUEST *req);

 OCSP_ONEREQ *OCSP_request_add0_id(OCSP_REQUEST *req, OCSP_CERTID *cid);

 int OCSP_request_sign(OCSP_REQUEST *req,

                       X509 *signer, EVP_PKEY *key, const EVP_MD *dgst,

                       STACK_OF(X509) *certs, unsigned long flags);

 int OCSP_request_add1_cert(OCSP_REQUEST *req, X509 *cert);

 int OCSP_request_onereq_count(OCSP_REQUEST *req);

 OCSP_ONEREQ *OCSP_request_onereq_get0(OCSP_REQUEST *req, int i);

=head1 DESCRIPTION

OCSP_REQUEST_new() allocates and returns an empty B<OCSP_REQUEST> structure.

OCSP_REQUEST_free() frees up the request structure B<req>.

OCSP_request_add0_id() adds certificate ID B<cid> to B<req>. It returns

the B<OCSP_ONEREQ> structure added so an application can add additional

extensions to the request. The B<id> parameter B<MUST NOT> be freed up after

the operation.

OCSP_request_sign() signs OCSP request B<req> using certificate

B<signer>, private key B<key>, digest B<dgst> and additional certificates

B<certs>. If the B<flags> option B<OCSP_NOCERTS> is set then no certificates

will be included in the request.

OCSP_request_add1_cert() adds certificate B<cert> to request B<req>. The

application is responsible for freeing up B<cert> after use.

OCSP_request_onereq_count() returns the total number of B<OCSP_ONEREQ>

structures in B<req>.

OCSP_request_onereq_get0() returns an internal pointer to the B<OCSP_ONEREQ>

contained in B<req> of index B<i>. The index value B<i> runs from 0 to

OCSP_request_onereq_count(req) - 1.

=head1 RETURN VALUES

OCSP_REQUEST_new() returns an empty B<OCSP_REQUEST> structure or B<NULL> if

an error occurred.

OCSP_request_add0_id() returns the B<OCSP_ONEREQ> structure containing B<cid>

or B<NULL> if an error occurred.

OCSP_request_sign() and OCSP_request_add1_cert() return 1 for success and 0

for failure.

OCSP_request_onereq_count() returns the total number of B<OCSP_ONEREQ>

structures in B<req>.

OCSP_request_onereq_get0() returns a pointer to an B<OCSP_ONEREQ> structure

or B<NULL> if the index value is out or range.

=head1 NOTES

An OCSP request structure contains one or more B<OCSP_ONEREQ> structures

corresponding to each certificate.

OCSP_request_onereq_count() and OCSP_request_onereq_get0() are mainly used by

OCSP responders.

=head1 EXAMPLE

Create an B<OCSP_REQUEST> structure for certificate B<cert> with issuer

B<issuer>:

 OCSP_REQUEST *req;

 OCSP_ID *cid;

 req = OCSP_REQUEST_new();

 if (req == NULL)

    /* error */

 cid = OCSP_cert_to_id(EVP_sha1(), cert, issuer);

 if (cid == NULL)

    /* error */

 if (OCSP_REQUEST_add0_id(req, cid) == NULL)

    /* error */

  /* Do something with req, e.g. query responder */

 OCSP_REQUEST_free(req);

=head1 SEE ALSO

L<crypto(3)|crypto(3)>,

L<OCSP_cert_to_id(3)|OCSP_cert_to_id(3)>,

L<OCSP_request_add1_nonce(3)|OCSP_request_add1_nonce(3)>,

L<OCSP_response_find_status(3)|OCSP_response_find_status(3)>,

L<OCSP_response_status(3)|OCSP_response_status(3)>,

L<OCSP_sendreq_new(3)|OCSP_sendreq_new(3)>

=cut

=pod

OCSP_cert_to_id, OCSP_cert_id_new, OCSP_CERTID_free, OCSP_id_issuer_cmp,

OCSP_id_cmp, OCSP_id_get0_info - OCSP certificate ID utility functions.

=head1 SYNOPSIS

 #include <openssl/ocsp.h>

 OCSP_CERTID *OCSP_cert_to_id(const EVP_MD *dgst,

                              X509 *subject, X509 *issuer);

 OCSP_CERTID *OCSP_cert_id_new(const EVP_MD *dgst,

                               X509_NAME *issuerName,

                               ASN1_BIT_STRING *issuerKey,

                               ASN1_INTEGER *serialNumber);

 void OCSP_CERTID_free(OCSP_CERTID *id);

 int OCSP_id_issuer_cmp(OCSP_CERTID *a, OCSP_CERTID *b);

 int OCSP_id_cmp(OCSP_CERTID *a, OCSP_CERTID *b);

 int OCSP_id_get0_info(ASN1_OCTET_STRING **piNameHash, ASN1_OBJECT **pmd,

                       ASN1_OCTET_STRING **pikeyHash,

                       ASN1_INTEGER **pserial, OCSP_CERTID *cid);

=head1 DESCRIPTION

OCSP_cert_to_id() creates and returns a new B<OCSP_CERTID> structure using

message digest B<dgst> for certificate B<subject> with issuer B<issuer>. If

B<dgst> is B<NULL> then SHA1 is used.

OCSP_cert_id_new() creates and returns a new B<OCSP_CERTID> using B<dgst> and

issuer name B<issuerName>, issuer key hash B<issuerKey> and serial number

B<serialNumber>.

OCSP_CERTID_free() frees up B<id>.

OCSP_id_cmp() compares B<OCSP_CERTID> B<a> and B<b>.

OCSP_id_issuer_cmp() compares only the issuer name of B<OCSP_CERTID> B<a> and B<b>.

OCSP_id_get0_info() returns the issuer name hash, hash OID, issuer key hash and

serial number contained in B<cid>. If any of the values are not required the

corresponding parameter can be set to B<NULL>.

=head1 RETURN VALUES

OCSP_cert_to_id() and OCSP_cert_id_new() return either a pointer to a valid

B<OCSP_CERTID> structure or B<NULL> if an error occurred.

OCSP_id_cmp() and OCSP_id_issuer_cmp() returns zero for a match and non-zero

otherwise.

OCSP_CERTID_free() does not return a value.

OCSP_id_get0_info() returns 1 for sucess and 0 for failure.

=head1 NOTES

OCSP clients will typically only use OCSP_cert_to_id() or OCSP_cert_id_new():

the other functions are used by responder applications.

The values returned by OCSP_id_get0_info() are internal pointers and B<MUST

NOT> be freed up by an application: they will be freed when the corresponding

B<OCSP_CERTID> structure is freed.

=head1 SEE ALSO

L<crypto(3)|crypto(3)>,

L<OCSP_request_add1_nonce(3)|OCSP_request_add1_nonce(3)>,

L<OCSP_REQUEST_new(3)|OCSP_REQUEST_new(3)>,

L<OCSP_response_find_status(3)|OCSP_response_find_status(3)>,

L<OCSP_response_status(3)|OCSP_response_status(3)>,

L<OCSP_sendreq_new(3)|OCSP_sendreq_new(3)>

=cut

=pod

OCSP_request_add1_nonce, OCSP_basic_add1_nonce, OCSP_check_nonce, OCSP_copy_nonce - OCSP nonce functions.

=head1 SYNOPSIS

 #include <openssl/ocsp.h>

 int OCSP_request_add1_nonce(OCSP_REQUEST *req, unsigned char *val, int len);

 int OCSP_basic_add1_nonce(OCSP_BASICRESP *resp, unsigned char *val, int len);

 int OCSP_copy_nonce(OCSP_BASICRESP *resp, OCSP_REQUEST *req);

 int OCSP_check_nonce(OCSP_REQUEST *req, OCSP_BASICRESP *resp);

=head1 DESCRIPTION

OCSP_request_add1_nonce() adds a nonce of value B<val> and length B<len> to

OCSP request B<req>. If B<val> is B<NULL> a random nonce is used. If B<len>

is zero or negative a default length will be used (currently 16 bytes).

OCSP_basic_add1_nonce() is identical to OCSP_request_add1_nonce() except

it adds a nonce to OCSP basic response B<resp>.

OCSP_check_nonce() compares the nonce value in B<req> and B<resp>.

OCSP_copy_nonce() copys any nonce value present in B<req> to B<resp>.

=head1 RETURN VALUES

OCSP_request_add1_nonce() and OCSP_basic_add1_nonce() return 1 for success

and 0 for failure.

OCSP_copy_nonce() returns 1 if a nonce was successfully copied, 2 if no nonce

was present in B<req> and 0 if an error occurred.

OCSP_check_nonce() returns the result of the nonce comparison between B<req>

and B<resp>. The return value indicates the result of the comparison.  If

nonces are present and equal 1 is returned. If the nonces are absent 2 is

returned. If a nonce is present in the response only 3 is returned. If nonces

are present and unequal 0 is returned. If the nonce is present in the request

only then -1 is returned.

=head1 NOTES

For most purposes the nonce value in a request is set to a random value so

the B<val> parameter in OCSP_request_add1_nonce() is usually NULL.

An OCSP nonce is typically added to an OCSP request to thwart replay attacks

by checking the same nonce value appears in the response.

Some responders may include a nonce in all responses even if one is not

supplied.

Some responders cache OCSP responses and do not sign each response for

performance reasons. As a result they do not support nonces.

The return values of OCSP_check_nonce() can be checked to cover each case.  A

positive return value effectively indicates success: nonces are both present

and match, both absent or present in the response only. A non-zero return

additionally covers the case where the nonce is present in the request only:

this will happen if the responder doesn't support nonces. A zero return value

indicates present and mismatched nonces: this should be treated as an error

condition.

=head1 SEE ALSO

L<crypto(3)|crypto(3)>,

L<OCSP_cert_to_id(3)|OCSP_cert_to_id(3)>,

L<OCSP_REQUEST_new(3)|OCSP_REQUEST_new(3)>,

L<OCSP_response_find_status(3)|OCSP_response_find_status(3)>,

L<OCSP_response_status(3)|OCSP_response_status(3)>,

L<OCSP_sendreq_new(3)|OCSP_sendreq_new(3)>

=cut

=pod

OCSP_resp_find_status, OCSP_resp_count, OCSP_resp_get0, OCSP_resp_find, OCSP_single_get0_status, OCSP_check_validity - OCSP reponse utility functions.

=head1 SYNOPSIS

 #include <openssl/ocsp.h>

 int OCSP_resp_find_status(OCSP_BASICRESP *bs, OCSP_CERTID *id, int *status,

                           int *reason,

                           ASN1_GENERALIZEDTIME **revtime,

                           ASN1_GENERALIZEDTIME **thisupd,

                           ASN1_GENERALIZEDTIME **nextupd);

 int OCSP_resp_count(OCSP_BASICRESP *bs);

 OCSP_SINGLERESP *OCSP_resp_get0(OCSP_BASICRESP *bs, int idx);

 int OCSP_resp_find(OCSP_BASICRESP *bs, OCSP_CERTID *id, int last);

 int OCSP_single_get0_status(OCSP_SINGLERESP *single, int *reason,

                             ASN1_GENERALIZEDTIME **revtime,

                             ASN1_GENERALIZEDTIME **thisupd,

                             ASN1_GENERALIZEDTIME **nextupd);

 int OCSP_check_validity(ASN1_GENERALIZEDTIME *thisupd,

                         ASN1_GENERALIZEDTIME *nextupd,

                         long sec, long maxsec);

=head1 DESCRIPTION

OCSP_resp_find_status() searches B<bs> for an OCSP response for B<id>. If it is

successful the fields of the response are returned in B<*status>, B<*reason>,

B<*revtime>, B<*thisupd> and B<*nextupd>.  The B<*status> value will be one of

B<V_OCSP_CERTSTATUS_GOOD>, B<V_OCSP_CERTSTATUS_REVOKED> or

B<V_OCSP_CERTSTATUS_UNKNOWN>. The B<*reason> and B<*revtime> fields are only

set if the status is B<V_OCSP_CERTSTATUS_REVOKED>. If set the B<*reason> field

will be set to the revocation reason which will be one of

B<OCSP_REVOKED_STATUS_NOSTATUS>, B<OCSP_REVOKED_STATUS_UNSPECIFIED>,

B<OCSP_REVOKED_STATUS_KEYCOMPROMISE>, B<OCSP_REVOKED_STATUS_CACOMPROMISE>,

B<OCSP_REVOKED_STATUS_AFFILIATIONCHANGED>, B<OCSP_REVOKED_STATUS_SUPERSEDED>,

B<OCSP_REVOKED_STATUS_CESSATIONOFOPERATION>,

B<OCSP_REVOKED_STATUS_CERTIFICATEHOLD> or B<OCSP_REVOKED_STATUS_REMOVEFROMCRL>.

OCSP_resp_count() returns the number of B<OCSP_SINGLERESP> structures in B<bs>.

OCSP_resp_get0() returns the B<OCSP_SINGLERESP> structure in B<bs>

corresponding to index B<idx>. Where B<idx> runs from 0 to

OCSP_resp_count(bs) - 1.

OCSP_resp_find() searches B<bs> for B<id> and returns the index of the first

matching entry after B<last> or starting from the beginning if B<last> is -1.

OCSP_single_get0_status() extracts the fields of B<single> in B<*reason>,

B<*revtime>, B<*thisupd> and B<*nextupd>.

OCSP_check_validity() checks the validity of B<thisupd> and B<nextupd> values

which will be typically obtained from OCSP_resp_find_status() or

OCSP_single_get0_status(). If B<sec> is non-zero it indicates how many seconds

leeway should be allowed in the check. If B<maxsec> is positive it indicates

the maximum age of B<thisupd> in seconds.

=head1 RETURN VALUES

OCSP_resp_find_status() returns 1 if B<id> is found in B<bs> and 0 otherwise.

OCSP_resp_count() returns the total number of B<OCSP_SINGLERESP> fields in

B<bs>.

OCSP_resp_get0() returns a pointer to an B<OCSP_SINGLERESP> structure or

B<NULL> if B<idx> is out of range.

OCSP_resp_find() returns the index of B<id> in B<bs> (which may be 0) or -1 if

B<id> was not found.

OCSP_single_get0_status() returns the status of B<single> or -1 if an error

occurred.

=head1 NOTES

Applications will typically call OCSP_resp_find_status() using the certificate

ID of interest and then check its validity using OCSP_check_validity(). They

can then take appropriate action based on the status of the certificate.

An OCSP response for a certificate contains B<thisUpdate> and B<nextUpdate>

fields. Normally the current time should be between these two values. To

account for clock skew the B<maxsec> field can be set to non-zero in

OCSP_check_validity(). Some responders do not set the B<nextUpdate> field, this

would otherwise mean an ancient response would be considered valid: the

B<maxsec> parameter to OCSP_check_validity() can be used to limit the permitted

age of responses.

The values written to B<*revtime>, B<*thisupd> and B<*nextupd> by

OCSP_resp_find_status() and OCSP_single_get0_status() are internal pointers

which B<MUST NOT> be freed up by the calling application. Any or all of these

parameters can be set to NULL if their value is not required.

=head1 SEE ALSO

L<crypto(3)|crypto(3)>,

L<OCSP_cert_to_id(3)|OCSP_cert_to_id(3)>,

L<OCSP_request_add1_nonce(3)|OCSP_request_add1_nonce(3)>,

L<OCSP_REQUEST_new(3)|OCSP_REQUEST_new(3)>,

L<OCSP_response_status(3)|OCSP_response_status(3)>,

L<OCSP_sendreq_new(3)|OCSP_sendreq_new(3)>

=cut

=pod

OCSP_response_status, OCSP_response_get1_basic, OCSP_response_create,

OCSP_RESPONSE_free - OCSP response functions.

=head1 SYNOPSIS

 #include <openssl/ocsp.h>

 int OCSP_response_status(OCSP_RESPONSE *resp);

 OCSP_BASICRESP *OCSP_response_get1_basic(OCSP_RESPONSE *resp);

 OCSP_RESPONSE *OCSP_response_create(int status, OCSP_BASICRESP *bs);

 void OCSP_RESPONSE_free(OCSP_RESPONSE *resp);

=head1 DESCRIPTION

OCSP_response_status() returns the OCSP response status of B<resp>. It returns

one of the values: B<OCSP_RESPONSE_STATUS_SUCCESSFUL>,

B<OCSP_RESPONSE_STATUS_MALFORMEDREQUEST>,

B<OCSP_RESPONSE_STATUS_INTERNALERROR>, B<OCSP_RESPONSE_STATUS_TRYLATER>

B<OCSP_RESPONSE_STATUS_SIGREQUIRED>, or B<OCSP_RESPONSE_STATUS_UNAUTHORIZED>.

OCSP_response_get1_basic() decodes and returns the B<OCSP_BASICRESP> structure

contained in B<resp>. 

OCSP_response_create() creates and returns an B<OCSP_RESPONSE> structure for

B<status> and optionally including basic response B<bs>.

OCSP_RESPONSE_free() frees up OCSP reponse B<resp>.

=head1 RETURN VALUES

OCSP_RESPONSE_status() returns a status value.

OCSP_response_get1_basic() returns an B<OCSP_BASICRESP> structure pointer or

B<NULL> if an error occurred.

OCSP_response_create() returns an B<OCSP_RESPONSE> structure pointer or B<NULL>

if an error occurred.

OCSP_RESPONSE_free() does not return a value.

=head1 NOTES

OCSP_response_get1_basic() is only called if the status of a response is

B<OCSP_RESPONSE_STATUS_SUCCESSFUL>.

=head1 SEE ALSO

L<crypto(3)|crypto(3)>

L<OCSP_cert_to_id(3)|OCSP_cert_to_id(3)>

L<OCSP_request_add1_nonce(3)|OCSP_request_add1_nonce(3)>

L<OCSP_REQUEST_new(3)|OCSP_REQUEST_new(3)>

L<OCSP_response_find_status(3)|OCSP_response_find_status(3)>

L<OCSP_sendreq_new(3)|OCSP_sendreq_new(3)>

=cut