]>
Commit | Line | Data |
---|---|---|
797a89a1 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | OCSP_sendreq_new, OCSP_sendreq_nbio, OCSP_REQ_CTX_free, | |
6 | OCSP_set_max_response_length, OCSP_REQ_CTX_add1_header, | |
7 | OCSP_REQ_CTX_set1_req, OCSP_sendreq_bio - OCSP responder query functions | |
8 | ||
9 | =head1 SYNOPSIS | |
10 | ||
11 | #include <openssl/ocsp.h> | |
12 | ||
29f178bd DDO |
13 | OCSP_REQ_CTX *OCSP_sendreq_new(BIO *io, const char *path, |
14 | OCSP_REQUEST *req, int maxline); | |
797a89a1 DSH |
15 | |
16 | int OCSP_sendreq_nbio(OCSP_RESPONSE **presp, OCSP_REQ_CTX *rctx); | |
17 | ||
18 | void OCSP_REQ_CTX_free(OCSP_REQ_CTX *rctx); | |
19 | ||
29f178bd DDO |
20 | void OCSP_set_max_response_length(OCSP_REQ_CTX *rctx, |
21 | unsigned long len); | |
797a89a1 DSH |
22 | |
23 | int OCSP_REQ_CTX_add1_header(OCSP_REQ_CTX *rctx, | |
24 | const char *name, const char *value); | |
25 | ||
29f178bd | 26 | int OCSP_REQ_CTX_set1_req(OCSP_REQ_CTX *rctx, const OCSP_REQUEST *req); |
797a89a1 | 27 | |
29f178bd | 28 | OCSP_RESPONSE *OCSP_sendreq_bio(BIO *io, const char *path, OCSP_REQUEST *req); |
797a89a1 DSH |
29 | |
30 | =head1 DESCRIPTION | |
31 | ||
32 | The function OCSP_sendreq_new() returns an B<OCSP_CTX> structure using the | |
33 | responder B<io>, the URL path B<path>, the OCSP request B<req> and with a | |
34 | response header maximum line length of B<maxline>. If B<maxline> is zero a | |
35 | default value of 4k is used. The OCSP request B<req> may be set to B<NULL> | |
36 | and provided later if required. | |
37 | ||
29f178bd DDO |
38 | OCSP_sendreq_nbio() performs I/O on the OCSP request context B<rctx>. |
39 | When the operation is complete it returns the response in B<*presp>. | |
797a89a1 DSH |
40 | |
41 | OCSP_REQ_CTX_free() frees up the OCSP context B<rctx>. | |
42 | ||
29f178bd DDO |
43 | OCSP_set_max_response_length() sets the maximum response length |
44 | for B<rctx> to B<len>. If the response exceeds this length an error occurs. | |
45 | If not set a default value of 100k is used. | |
797a89a1 DSH |
46 | |
47 | OCSP_REQ_CTX_add1_header() adds header B<name> with value B<value> to the | |
48 | context B<rctx>. It can be called more than once to add multiple headers. | |
49 | It B<MUST> be called before any calls to OCSP_sendreq_nbio(). The B<req> | |
50 | parameter in the initial to OCSP_sendreq_new() call MUST be set to B<NULL> if | |
51 | additional headers are set. | |
52 | ||
53 | OCSP_REQ_CTX_set1_req() sets the OCSP request in B<rctx> to B<req>. This | |
54 | function should be called after any calls to OCSP_REQ_CTX_add1_header(). | |
55 | ||
56 | OCSP_sendreq_bio() performs an OCSP request using the responder B<io>, the URL | |
57 | path B<path>, the OCSP request B<req> and with a response header maximum line | |
29f178bd | 58 | length 4k. It waits indefinitely on a response. |
797a89a1 DSH |
59 | |
60 | =head1 RETURN VALUES | |
61 | ||
29f178bd DDO |
62 | OCSP_sendreq_new() returns a valid B<OCSP_REQ_CTX> structure or B<NULL> |
63 | if an error occurred. | |
797a89a1 | 64 | |
29f178bd DDO |
65 | OCSP_sendreq_nbio(), OCSP_REQ_CTX_add1_header() and OCSP_REQ_CTX_set1_req() |
66 | return B<1> for success and B<0> for failure. | |
797a89a1 DSH |
67 | |
68 | OCSP_sendreq_bio() returns the B<OCSP_RESPONSE> structure sent by the | |
69 | responder or B<NULL> if an error occurred. | |
70 | ||
29f178bd DDO |
71 | OCSP_REQ_CTX_free() and OCSP_set_max_response_length() |
72 | do not return values. | |
797a89a1 DSH |
73 | |
74 | =head1 NOTES | |
75 | ||
76 | These functions only perform a minimal HTTP query to a responder. If an | |
77 | application wishes to support more advanced features it should use an | |
78 | alternative more complete HTTP library. | |
79 | ||
80 | Currently only HTTP POST queries to responders are supported. | |
81 | ||
82 | The arguments to OCSP_sendreq_new() correspond to the components of the URL. | |
83 | For example if the responder URL is B<http://ocsp.com/ocspreq> the BIO | |
84 | B<io> should be connected to host B<ocsp.com> on port 80 and B<path> | |
85 | should be set to B<"/ocspreq"> | |
86 | ||
87 | The headers added with OCSP_REQ_CTX_add1_header() are of the form | |
88 | "B<name>: B<value>" or just "B<name>" if B<value> is B<NULL>. So to add | |
89 | a Host header for B<ocsp.com> you would call: | |
90 | ||
91 | OCSP_REQ_CTX_add1_header(ctx, "Host", "ocsp.com"); | |
92 | ||
29f178bd DDO |
93 | OCSP_sendreq_bio() does not support timeout nor setting extra headers. |
94 | It is retained for compatibility. | |
95 | Better use B<OCSP_sendreq_nbio()> instead. | |
797a89a1 DSH |
96 | |
97 | =head1 SEE ALSO | |
98 | ||
b97fdb57 | 99 | L<crypto(7)>, |
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 | |
e2f92610 RS |
106 | =head1 COPYRIGHT |
107 | ||
33388b44 | 108 | Copyright 2015-2020 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 109 | |
4746f25a | 110 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
111 | this file except in compliance with the License. You can obtain a copy |
112 | in the file LICENSE in the source distribution or at | |
113 | L<https://www.openssl.org/source/license.html>. | |
114 | ||
115 | =cut |