]>
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 | ||
13 | OCSP_REQ_CTX *OCSP_sendreq_new(BIO *io, const char *path, OCSP_REQUEST *req, | |
14 | int maxline); | |
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 | ||
20 | void OCSP_set_max_response_length(OCSP_REQ_CTX *rctx, unsigned long len); | |
21 | ||
22 | int OCSP_REQ_CTX_add1_header(OCSP_REQ_CTX *rctx, | |
23 | const char *name, const char *value); | |
24 | ||
25 | int OCSP_REQ_CTX_set1_req(OCSP_REQ_CTX *rctx, OCSP_REQUEST *req); | |
26 | ||
27 | OCSP_RESPONSE *OCSP_sendreq_bio(BIO *io, const char *path, OCSP_REQUEST *req, | |
28 | int maxline); | |
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 | ||
38 | OCSP_sendreq_nbio() performs non-blocking I/O on the OCSP request context | |
39 | B<rctx>. When the operation is complete it returns the response in B<*presp>. | |
40 | ||
41 | OCSP_REQ_CTX_free() frees up the OCSP context B<rctx>. | |
42 | ||
43 | OCSP_set_max_response_length() sets the maximum reponse length for B<rctx> | |
44 | to B<len>. If the response exceeds this length an error occurs. If not | |
45 | set a default value of 100k is used. | |
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 | |
58 | length of B<maxline>. If B<maxline> is zero a default value of 4k is used. | |
59 | ||
60 | =head1 RETURN VALUES | |
61 | ||
62 | OCSP_sendreq_new() returns a valid B<OCSP_REQ_CTX> structure or B<NULL> if | |
63 | an error occurred. | |
64 | ||
65 | OCSP_sendreq_nbio() returns B<1> if the operation was completed successfully, | |
66 | B<-1> if the operation should be retried and B<0> if an error occurred. | |
67 | ||
68 | OCSP_REQ_CTX_add1_header() and OCSP_REQ_CTX_set1_req() return B<1> for success | |
69 | and B<0> for failure. | |
70 | ||
71 | OCSP_sendreq_bio() returns the B<OCSP_RESPONSE> structure sent by the | |
72 | responder or B<NULL> if an error occurred. | |
73 | ||
74 | OCSP_REQ_CTX_free() and OCSP_set_max_response_length() do not return values. | |
75 | ||
76 | =head1 NOTES | |
77 | ||
78 | These functions only perform a minimal HTTP query to a responder. If an | |
79 | application wishes to support more advanced features it should use an | |
80 | alternative more complete HTTP library. | |
81 | ||
82 | Currently only HTTP POST queries to responders are supported. | |
83 | ||
84 | The arguments to OCSP_sendreq_new() correspond to the components of the URL. | |
85 | For example if the responder URL is B<http://ocsp.com/ocspreq> the BIO | |
86 | B<io> should be connected to host B<ocsp.com> on port 80 and B<path> | |
87 | should be set to B<"/ocspreq"> | |
88 | ||
89 | The headers added with OCSP_REQ_CTX_add1_header() are of the form | |
90 | "B<name>: B<value>" or just "B<name>" if B<value> is B<NULL>. So to add | |
91 | a Host header for B<ocsp.com> you would call: | |
92 | ||
93 | OCSP_REQ_CTX_add1_header(ctx, "Host", "ocsp.com"); | |
94 | ||
95 | If OCSP_sendreq_nbio() indicates an operation should be retried the | |
96 | corresponding BIO can be examined to determine which operation (read or | |
97 | write) should be retried and appropriate action taken (for example a select() | |
98 | call on the underlying socket). | |
99 | ||
100 | OCSP_sendreq_bio() does not support retries and so cannot handle non-blocking | |
101 | I/O efficiently. It is retained for compatibility and its use in new | |
102 | applications is not recommended. | |
103 | ||
104 | =head1 SEE ALSO | |
105 | ||
106 | L<crypto(3)|crypto(3)>, | |
107 | L<OCSP_cert_to_id(3)|OCSP_cert_to_id(3)>, | |
108 | L<OCSP_request_add1_nonce(3)|OCSP_request_add1_nonce(3)>, | |
109 | L<OCSP_REQUEST_new(3)|OCSP_REQUEST_new(3)>, | |
110 | L<OCSP_response_find_status(3)|OCSP_response_find_status(3)>, | |
111 | L<OCSP_response_status(3)|OCSP_response_status(3)> | |
112 | ||
113 | =cut |