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