doc/crypto/OCSP_REQUEST_new.pod

   1 =pod
   2
   3 OCSP_REQUEST_new, OCSP_REQUEST_free, OCSP_request_add0_id, OCSP_request_sign,
   4 OCSP_request_add1_cert, OCSP_request_onereq_count,
   5 OCSP_request_onereq_get0 - OCSP request functions.
   6
   7 =head1 SYNOPSIS
   8
   9  #include <openssl/ocsp.h>
  10
  11  OCSP_REQUEST *OCSP_REQUEST_new(void);
  12  void OCSP_REQUEST_free(OCSP_REQUEST *req);
  13
  14  OCSP_ONEREQ *OCSP_request_add0_id(OCSP_REQUEST *req, OCSP_CERTID *cid);
  15
  16  int OCSP_request_sign(OCSP_REQUEST *req,
  17                        X509 *signer, EVP_PKEY *key, const EVP_MD *dgst,
  18                        STACK_OF(X509) *certs, unsigned long flags);
  19
  20  int OCSP_request_add1_cert(OCSP_REQUEST *req, X509 *cert);
  21
  22  int OCSP_request_onereq_count(OCSP_REQUEST *req);
  23  OCSP_ONEREQ *OCSP_request_onereq_get0(OCSP_REQUEST *req, int i);
  24
  25 =head1 DESCRIPTION
  26
  27 OCSP_REQUEST_new() allocates and returns an empty B<OCSP_REQUEST> structure.
  28
  29 OCSP_REQUEST_free() frees up the request structure B<req>.
  30
  31 OCSP_request_add0_id() adds certificate ID B<cid> to B<req>. It returns
  32 the B<OCSP_ONEREQ> structure added so an application can add additional
  33 extensions to the request. The B<id> parameter B<MUST NOT> be freed up after
  34 the operation.
  35
  36 OCSP_request_sign() signs OCSP request B<req> using certificate
  37 B<signer>, private key B<key>, digest B<dgst> and additional certificates
  38 B<certs>. If the B<flags> option B<OCSP_NOCERTS> is set then no certificates
  39 will be included in the request.
  40
  41 OCSP_request_add1_cert() adds certificate B<cert> to request B<req>. The
  42 application is responsible for freeing up B<cert> after use.
  43
  44 OCSP_request_onereq_count() returns the total number of B<OCSP_ONEREQ>
  45 structures in B<req>.
  46
  47 OCSP_request_onereq_get0() returns an internal pointer to the B<OCSP_ONEREQ>
  48 contained in B<req> of index B<i>. The index value B<i> runs from 0 to
  49 OCSP_request_onereq_count(req) - 1.
  50
  51 =head1 RETURN VALUES
  52
  53 OCSP_REQUEST_new() returns an empty B<OCSP_REQUEST> structure or B<NULL> if
  54 an error occurred.
  55
  56 OCSP_request_add0_id() returns the B<OCSP_ONEREQ> structure containing B<cid>
  57 or B<NULL> if an error occurred.
  58
  59 OCSP_request_sign() and OCSP_request_add1_cert() return 1 for success and 0
  60 for failure.
  61
  62 OCSP_request_onereq_count() returns the total number of B<OCSP_ONEREQ>
  63 structures in B<req>.
  64
  65 OCSP_request_onereq_get0() returns a pointer to an B<OCSP_ONEREQ> structure
  66 or B<NULL> if the index value is out or range.
  67
  68 =head1 NOTES
  69
  70 An OCSP request structure contains one or more B<OCSP_ONEREQ> structures
  71 corresponding to each certificate.
  72
  73 OCSP_request_onereq_count() and OCSP_request_onereq_get0() are mainly used by
  74 OCSP responders.
  75
  76 =head1 EXAMPLE
  77
  78 Create an B<OCSP_REQUEST> structure for certificate B<cert> with issuer
  79 B<issuer>:
  80
  81  OCSP_REQUEST *req;
  82  OCSP_ID *cid;
  83
  84  req = OCSP_REQUEST_new();
  85  if (req == NULL)
  86     /* error */
  87  cid = OCSP_cert_to_id(EVP_sha1(), cert, issuer);
  88  if (cid == NULL)
  89     /* error */
  90
  91  if (OCSP_REQUEST_add0_id(req, cid) == NULL)
  92     /* error */
  93
  94   /* Do something with req, e.g. query responder */
  95
  96  OCSP_REQUEST_free(req);
  97
  98 =head1 SEE ALSO
  99
 100 L<crypto(3)>,
 101 L<OCSP_cert_to_id(3)>,
 102 L<OCSP_request_add1_nonce(3)>,
 103 L<OCSP_response_find_status(3)>,
 104 L<OCSP_response_status(3)>,
 105 L<OCSP_sendreq_new(3)>
 106
 107 =cut