]>
Commit | Line | Data |
---|---|---|
797a89a1 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
7031f582 | 5 | OCSP_REQ_CTX, |
2f06c34b RS |
6 | OCSP_sendreq_new, |
7 | OCSP_sendreq_nbio, | |
2f06c34b RS |
8 | OCSP_sendreq_bio, |
9 | OCSP_REQ_CTX_i2d, | |
83b6dc8d RS |
10 | OCSP_REQ_CTX_add1_header, |
11 | OCSP_REQ_CTX_free, | |
12 | OCSP_set_max_response_length, | |
2f06c34b RS |
13 | OCSP_REQ_CTX_set1_req |
14 | - OCSP responder query functions | |
797a89a1 DSH |
15 | |
16 | =head1 SYNOPSIS | |
17 | ||
18 | #include <openssl/ocsp.h> | |
19 | ||
83b6dc8d | 20 | OSSL_HTTP_REQ_CTX *OCSP_sendreq_new(BIO *io, const char *path, |
8f965908 | 21 | const OCSP_REQUEST *req, int buf_size); |
29f178bd | 22 | OCSP_RESPONSE *OCSP_sendreq_bio(BIO *io, const char *path, OCSP_REQUEST *req); |
797a89a1 | 23 | |
3dbf8243 MC |
24 | The following functions have been deprecated since OpenSSL 3.0, and can be |
25 | hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, | |
26 | see L<openssl_user_macros(7)>: | |
ecef17c3 | 27 | |
7031f582 | 28 | typedef OSSL_HTTP_REQ_CTX OCSP_REQ_CTX; |
8f965908 | 29 | int OCSP_sendreq_nbio(OCSP_RESPONSE **presp, OSSL_HTTP_REQ_CTX *rctx); |
c9603dfa | 30 | int OCSP_REQ_CTX_i2d(OCSP_REQ_CT *rctx, const ASN1_ITEM *it, ASN1_VALUE *req); |
83b6dc8d RS |
31 | int OCSP_REQ_CTX_add1_header(OCSP_REQ_CT *rctx, |
32 | const char *name, const char *value); | |
7031f582 | 33 | void OCSP_REQ_CTX_free(OCSP_REQ_CTX *rctx); |
8f965908 | 34 | void OCSP_set_max_response_length(OCSP_REQ_CT *rctx, unsigned long len); |
7031f582 | 35 | int OCSP_REQ_CTX_set1_req(OCSP_REQ_CTX *rctx, const OCSP_REQUEST *req); |
ecef17c3 | 36 | |
797a89a1 DSH |
37 | =head1 DESCRIPTION |
38 | ||
c9603dfa DDO |
39 | These functions perform an OCSP POST request / response transfer over HTTP, |
40 | using the HTTP request functions described in L<OSSL_HTTP_REQ_CTX(3)>. | |
797a89a1 | 41 | |
8f965908 | 42 | The function OCSP_sendreq_new() builds a complete B<OSSL_HTTP_REQ_CTX> structure |
e304aa87 | 43 | with the B<BIO> I<io> to be used for requests and response, the URL path I<path>, |
8f965908 DDO |
44 | optionally the OCSP request I<req>, and a response header maximum line length |
45 | of I<buf_size>. If I<buf_size> is zero a default value of 4KiB is used. | |
c9603dfa | 46 | The I<req> may be set to NULL and provided later using OCSP_REQ_CTX_set1_req() |
8f965908 | 47 | or L<OSSL_HTTP_REQ_CTX_set1_req(3)>. |
83b6dc8d RS |
48 | The I<io> and I<path> arguments to OCSP_sendreq_new() correspond to the |
49 | components of the URL. | |
50 | For example if the responder URL is C<http://example.com/ocspreq> the BIO | |
8f965908 | 51 | I<io> should haven been connected to host C<example.com> on port 80 and I<path> |
83b6dc8d | 52 | should be set to C</ocspreq>. |
797a89a1 | 53 | |
8f965908 DDO |
54 | OCSP_sendreq_nbio() attempts to send the request prepared in I<rctx> |
55 | and to gather the response via HTTP, using the BIO I<io> and I<path> | |
56 | that were given when calling OCSP_sendreq_new(). | |
57 | If the operation gets completed it assigns the response, | |
58 | a pointer to a B<OCSP_RESPONSE> structure, in I<*presp>. | |
59 | The function may need to be called again if its result is -1, which indicates | |
60 | L<BIO_should_retry(3)>. In such a case it is advisable to sleep a little in | |
61 | between, using L<BIO_wait(3)> on the read BIO to prevent a busy loop. | |
62 | ||
63 | OCSP_sendreq_bio() combines OCSP_sendreq_new() with as many calls of | |
64 | OCSP_sendreq_nbio() as needed and then OCSP_REQ_CTX_free(), with a | |
83b6dc8d RS |
65 | response header maximum line length 4k. It waits indefinitely on a response. |
66 | It does not support setting a timeout or adding headers and is retained | |
8f965908 | 67 | for compatibility; use L<OSSL_HTTP_transfer(3)> instead. |
2f06c34b | 68 | |
c9603dfa DDO |
69 | OCSP_REQ_CTX_i2d(rctx, it, req) is equivalent to the following: |
70 | ||
1c8505fb | 71 | OSSL_HTTP_REQ_CTX_set1_req(rctx, "application/ocsp-request", it, req) |
c9603dfa | 72 | |
2f06c34b RS |
73 | OCSP_REQ_CTX_set1_req(rctx, req) is equivalent to the following: |
74 | ||
1c8505fb | 75 | OSSL_HTTP_REQ_CTX_set1_req(rctx, "application/ocsp-request", |
7031f582 DDO |
76 | ASN1_ITEM_rptr(OCSP_REQUEST), |
77 | (const ASN1_VALUE *)req) | |
83b6dc8d | 78 | |
7031f582 DDO |
79 | The deprecated type and the remaining deprecated functions |
80 | have been superseded by the following equivalents: | |
83b6dc8d | 81 | B<OCSP_REQ_CTX> by L<OSSL_HTTP_REQ_CTX(3)>, |
83b6dc8d RS |
82 | OCSP_REQ_CTX_add1_header() by L<OSSL_HTTP_REQ_CTX_add1_header(3)>, |
83 | OCSP_REQ_CTX_free() by L<OSSL_HTTP_REQ_CTX_free(3)>, and | |
84 | OCSP_set_max_response_length() by | |
85 | L<OSSL_HTTP_REQ_CTX_set_max_response_length(3)>. | |
ecef17c3 | 86 | |
797a89a1 DSH |
87 | =head1 RETURN VALUES |
88 | ||
83b6dc8d | 89 | OCSP_sendreq_new() returns a valid B<OSSL_HTTP_REQ_CTX> structure or NULL |
29f178bd | 90 | if an error occurred. |
797a89a1 | 91 | |
8f965908 | 92 | OCSP_sendreq_nbio() returns 1 for success, 0 on error, -1 if retry is needed. |
797a89a1 DSH |
93 | |
94 | OCSP_sendreq_bio() returns the B<OCSP_RESPONSE> structure sent by the | |
83b6dc8d | 95 | responder or NULL if an error occurred. |
797a89a1 DSH |
96 | |
97 | =head1 SEE ALSO | |
98 | ||
8f965908 | 99 | L<OSSL_HTTP_REQ_CTX(3)>, L<OSSL_HTTP_transfer(3)>, |
9b86974e RS |
100 | L<OCSP_cert_to_id(3)>, |
101 | L<OCSP_request_add1_nonce(3)>, | |
102 | L<OCSP_REQUEST_new(3)>, | |
b97fdb57 | 103 | L<OCSP_resp_find_status(3)>, |
9b86974e | 104 | L<OCSP_response_status(3)> |
797a89a1 | 105 | |
ecef17c3 RS |
106 | =head1 HISTORY |
107 | ||
83b6dc8d RS |
108 | B<OCSP_REQ_CTX>, |
109 | OCSP_REQ_CTX_i2d(), | |
110 | OCSP_REQ_CTX_add1_header(), | |
111 | OCSP_REQ_CTX_free(), | |
112 | OCSP_set_max_response_length(), | |
113 | and OCSP_REQ_CTX_set1_req() | |
114 | were deprecated in OpenSSL 3.0. | |
ecef17c3 | 115 | |
e2f92610 RS |
116 | =head1 COPYRIGHT |
117 | ||
fecb3aae | 118 | Copyright 2015-2022 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 119 | |
4746f25a | 120 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
121 | this file except in compliance with the License. You can obtain a copy |
122 | in the file LICENSE in the source distribution or at | |
123 | L<https://www.openssl.org/source/license.html>. | |
124 | ||
125 | =cut |