doc/crypto/OCSP_response_find_status.pod

   1 =pod
   2
   3 OCSP_resp_find_status, OCSP_resp_count, OCSP_resp_get0, OCSP_resp_find, OCSP_single_get0_status, OCSP_check_validity - OCSP reponse utility functions.
   4
   5 =head1 SYNOPSIS
   6
   7  #include <openssl/ocsp.h>
   8
   9  int OCSP_resp_find_status(OCSP_BASICRESP *bs, OCSP_CERTID *id, int *status,
  10                            int *reason,
  11                            ASN1_GENERALIZEDTIME **revtime,
  12                            ASN1_GENERALIZEDTIME **thisupd,
  13                            ASN1_GENERALIZEDTIME **nextupd);
  14
  15  int OCSP_resp_count(OCSP_BASICRESP *bs);
  16  OCSP_SINGLERESP *OCSP_resp_get0(OCSP_BASICRESP *bs, int idx);
  17  int OCSP_resp_find(OCSP_BASICRESP *bs, OCSP_CERTID *id, int last);
  18  int OCSP_single_get0_status(OCSP_SINGLERESP *single, int *reason,
  19                              ASN1_GENERALIZEDTIME **revtime,
  20                              ASN1_GENERALIZEDTIME **thisupd,
  21                              ASN1_GENERALIZEDTIME **nextupd);
  22
  23  ASN1_GENERALIZEDTIME *OCSP_resp_get0_produced_at(OCSP_BASICRESP* single);
  24
  25  int OCSP_check_validity(ASN1_GENERALIZEDTIME *thisupd,
  26                          ASN1_GENERALIZEDTIME *nextupd,
  27                          long sec, long maxsec);
  28
  29 =head1 DESCRIPTION
  30
  31 OCSP_resp_find_status() searches B<bs> for an OCSP response for B<id>. If it is
  32 successful the fields of the response are returned in B<*status>, B<*reason>,
  33 B<*revtime>, B<*thisupd> and B<*nextupd>.  The B<*status> value will be one of
  34 B<V_OCSP_CERTSTATUS_GOOD>, B<V_OCSP_CERTSTATUS_REVOKED> or
  35 B<V_OCSP_CERTSTATUS_UNKNOWN>. The B<*reason> and B<*revtime> fields are only
  36 set if the status is B<V_OCSP_CERTSTATUS_REVOKED>. If set the B<*reason> field
  37 will be set to the revocation reason which will be one of
  38 B<OCSP_REVOKED_STATUS_NOSTATUS>, B<OCSP_REVOKED_STATUS_UNSPECIFIED>,
  39 B<OCSP_REVOKED_STATUS_KEYCOMPROMISE>, B<OCSP_REVOKED_STATUS_CACOMPROMISE>,
  40 B<OCSP_REVOKED_STATUS_AFFILIATIONCHANGED>, B<OCSP_REVOKED_STATUS_SUPERSEDED>,
  41 B<OCSP_REVOKED_STATUS_CESSATIONOFOPERATION>,
  42 B<OCSP_REVOKED_STATUS_CERTIFICATEHOLD> or B<OCSP_REVOKED_STATUS_REMOVEFROMCRL>.
  43
  44 OCSP_resp_count() returns the number of B<OCSP_SINGLERESP> structures in B<bs>.
  45
  46 OCSP_resp_get0() returns the B<OCSP_SINGLERESP> structure in B<bs>
  47 corresponding to index B<idx>. Where B<idx> runs from 0 to
  48 OCSP_resp_count(bs) - 1.
  49
  50 OCSP_resp_find() searches B<bs> for B<id> and returns the index of the first
  51 matching entry after B<last> or starting from the beginning if B<last> is -1.
  52
  53 OCSP_single_get0_status() extracts the fields of B<single> in B<*reason>,
  54 B<*revtime>, B<*thisupd> and B<*nextupd>.
  55
  56 OCSP_resp_get0_produced_at() extracts the B<producedAt> field from the
  57 single response B<bs>.
  58
  59 OCSP_check_validity() checks the validity of B<thisupd> and B<nextupd> values
  60 which will be typically obtained from OCSP_resp_find_status() or
  61 OCSP_single_get0_status(). If B<sec> is non-zero it indicates how many seconds
  62 leeway should be allowed in the check. If B<maxsec> is positive it indicates
  63 the maximum age of B<thisupd> in seconds.
  64
  65 =head1 RETURN VALUES
  66
  67 OCSP_resp_find_status() returns 1 if B<id> is found in B<bs> and 0 otherwise.
  68
  69 OCSP_resp_count() returns the total number of B<OCSP_SINGLERESP> fields in
  70 B<bs>.
  71
  72 OCSP_resp_get0() returns a pointer to an B<OCSP_SINGLERESP> structure or
  73 B<NULL> if B<idx> is out of range.
  74
  75 OCSP_resp_find() returns the index of B<id> in B<bs> (which may be 0) or -1 if
  76 B<id> was not found.
  77
  78 OCSP_single_get0_status() returns the status of B<single> or -1 if an error
  79 occurred.
  80
  81 =head1 NOTES
  82
  83 Applications will typically call OCSP_resp_find_status() using the certificate
  84 ID of interest and then check its validity using OCSP_check_validity(). They
  85 can then take appropriate action based on the status of the certificate.
  86
  87 An OCSP response for a certificate contains B<thisUpdate> and B<nextUpdate>
  88 fields. Normally the current time should be between these two values. To
  89 account for clock skew the B<maxsec> field can be set to non-zero in
  90 OCSP_check_validity(). Some responders do not set the B<nextUpdate> field, this
  91 would otherwise mean an ancient response would be considered valid: the
  92 B<maxsec> parameter to OCSP_check_validity() can be used to limit the permitted
  93 age of responses.
  94
  95 The values written to B<*revtime>, B<*thisupd> and B<*nextupd> by
  96 OCSP_resp_find_status() and OCSP_single_get0_status() are internal pointers
  97 which B<MUST NOT> be freed up by the calling application. Any or all of these
  98 parameters can be set to NULL if their value is not required.
  99
 100 =head1 SEE ALSO
 101
 102 L<crypto(3)>,
 103 L<OCSP_cert_to_id(3)>,
 104 L<OCSP_request_add1_nonce(3)>,
 105 L<OCSP_REQUEST_new(3)>,
 106 L<OCSP_response_status(3)>,
 107 L<OCSP_sendreq_new(3)>
 108
 109 =cut