doc/crypto/OCSP_REQUEST_new.pod

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