xref: /openssl/doc/man3/OCSP_REQUEST_new.pod (revision 7ed6de99)
1=pod
2
3=head1 NAME
4
5OCSP_REQUEST_new, OCSP_REQUEST_free, OCSP_request_add0_id, OCSP_request_sign,
6OCSP_request_add1_cert, OCSP_request_onereq_count,
7OCSP_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
29OCSP_REQUEST_new() allocates and returns an empty B<OCSP_REQUEST> structure.
30
31OCSP_REQUEST_free() frees up the request structure B<req>.
32If the argument is NULL, nothing is done.
33
34OCSP_request_add0_id() adds certificate ID B<cid> to B<req>. It returns
35the B<OCSP_ONEREQ> structure added so an application can add additional
36extensions to the request. The B<id> parameter B<MUST NOT> be freed up after
37the operation.
38
39OCSP_request_sign() signs OCSP request B<req> using certificate
40B<signer>, private key B<key>, digest B<dgst> and additional certificates
41B<certs>. If the B<flags> option B<OCSP_NOCERTS> is set then no certificates
42will be included in the request.
43
44OCSP_request_add1_cert() adds certificate B<cert> to request B<req>. The
45application is responsible for freeing up B<cert> after use.
46
47OCSP_request_onereq_count() returns the total number of B<OCSP_ONEREQ>
48structures in B<req>.
49
50OCSP_request_onereq_get0() returns an internal pointer to the B<OCSP_ONEREQ>
51contained in B<req> of index B<i>. The index value B<i> runs from 0 to
52OCSP_request_onereq_count(req) - 1.
53
54=head1 RETURN VALUES
55
56OCSP_REQUEST_new() returns an empty B<OCSP_REQUEST> structure or B<NULL> if
57an error occurred.
58
59OCSP_request_add0_id() returns the B<OCSP_ONEREQ> structure containing B<cid>
60or B<NULL> if an error occurred.
61
62OCSP_request_sign() and OCSP_request_add1_cert() return 1 for success and 0
63for failure.
64
65OCSP_request_onereq_count() returns the total number of B<OCSP_ONEREQ>
66structures in B<req> and -1 on error.
67
68OCSP_request_onereq_get0() returns a pointer to an B<OCSP_ONEREQ> structure
69or B<NULL> if the index value is out or range.
70
71=head1 NOTES
72
73An OCSP request structure contains one or more B<OCSP_ONEREQ> structures
74corresponding to each certificate.
75
76OCSP_request_onereq_count() and OCSP_request_onereq_get0() are mainly used by
77OCSP responders.
78
79=head1 EXAMPLES
80
81Create an B<OCSP_REQUEST> structure for certificate B<cert> with issuer
82B<issuer>:
83
84 OCSP_REQUEST *req;
85 OCSP_ID *cid;
86
87 req = OCSP_REQUEST_new();
88 if (req == NULL)
89    /* error */
90 cid = OCSP_cert_to_id(EVP_sha1(), cert, issuer);
91 if (cid == NULL)
92    /* error */
93
94 if (OCSP_REQUEST_add0_id(req, cid) == NULL)
95    /* error */
96
97 /* Do something with req, e.g. query responder */
98
99 OCSP_REQUEST_free(req);
100
101=head1 SEE ALSO
102
103L<crypto(7)>,
104L<OCSP_cert_to_id(3)>,
105L<OCSP_request_add1_nonce(3)>,
106L<OCSP_resp_find_status(3)>,
107L<OCSP_response_status(3)>,
108L<OCSP_sendreq_new(3)>
109
110=head1 COPYRIGHT
111
112Copyright 2015-2024 The OpenSSL Project Authors. All Rights Reserved.
113
114Licensed under the Apache License 2.0 (the "License").  You may not use
115this file except in compliance with the License.  You can obtain a copy
116in the file LICENSE in the source distribution or at
117L<https://www.openssl.org/source/license.html>.
118
119=cut
120