summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/OCSP_sendreq_new.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/OCSP_sendreq_new.3')
-rw-r--r--src/lib/libcrypto/man/OCSP_sendreq_new.3323
1 files changed, 0 insertions, 323 deletions
diff --git a/src/lib/libcrypto/man/OCSP_sendreq_new.3 b/src/lib/libcrypto/man/OCSP_sendreq_new.3
deleted file mode 100644
index 300f719525..0000000000
--- a/src/lib/libcrypto/man/OCSP_sendreq_new.3
+++ /dev/null
@@ -1,323 +0,0 @@
1.\" $OpenBSD: OCSP_sendreq_new.3,v 1.10 2022/03/31 17:27:17 naddy Exp $
2.\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
3.\"
4.\" This file is a derived work.
5.\" The changes are covered by the following Copyright and license:
6.\"
7.\" Copyright (c) 2018, 2019 Ingo Schwarze <schwarze@openbsd.org>
8.\"
9.\" Permission to use, copy, modify, and distribute this software for any
10.\" purpose with or without fee is hereby granted, provided that the above
11.\" copyright notice and this permission notice appear in all copies.
12.\"
13.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
14.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
15.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
16.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
17.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
18.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
19.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
20.\"
21.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
22.\" Copyright (c) 2014, 2016 The OpenSSL Project. All rights reserved.
23.\"
24.\" Redistribution and use in source and binary forms, with or without
25.\" modification, are permitted provided that the following conditions
26.\" are met:
27.\"
28.\" 1. Redistributions of source code must retain the above copyright
29.\" notice, this list of conditions and the following disclaimer.
30.\"
31.\" 2. Redistributions in binary form must reproduce the above copyright
32.\" notice, this list of conditions and the following disclaimer in
33.\" the documentation and/or other materials provided with the
34.\" distribution.
35.\"
36.\" 3. All advertising materials mentioning features or use of this
37.\" software must display the following acknowledgment:
38.\" "This product includes software developed by the OpenSSL Project
39.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
40.\"
41.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
42.\" endorse or promote products derived from this software without
43.\" prior written permission. For written permission, please contact
44.\" openssl-core@openssl.org.
45.\"
46.\" 5. Products derived from this software may not be called "OpenSSL"
47.\" nor may "OpenSSL" appear in their names without prior written
48.\" permission of the OpenSSL Project.
49.\"
50.\" 6. Redistributions of any form whatsoever must retain the following
51.\" acknowledgment:
52.\" "This product includes software developed by the OpenSSL Project
53.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
54.\"
55.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
56.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
57.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
58.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
59.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
60.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
61.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
62.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
63.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
64.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
65.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
66.\" OF THE POSSIBILITY OF SUCH DAMAGE.
67.\"
68.Dd $Mdocdate: March 31 2022 $
69.Dt OCSP_SENDREQ_NEW 3
70.Os
71.Sh NAME
72.Nm OCSP_sendreq_new ,
73.Nm OCSP_sendreq_nbio ,
74.Nm OCSP_REQ_CTX_free ,
75.Nm OCSP_REQ_CTX_add1_header ,
76.Nm OCSP_REQ_CTX_set1_req ,
77.Nm OCSP_parse_url ,
78.Nm OCSP_sendreq_bio
79.Nd OCSP responder query functions
80.Sh SYNOPSIS
81.In openssl/ocsp.h
82.Ft OCSP_REQ_CTX *
83.Fo OCSP_sendreq_new
84.Fa "BIO *io"
85.Fa "const char *path"
86.Fa "OCSP_REQUEST *req"
87.Fa "int maxline"
88.Fc
89.Ft int
90.Fo OCSP_sendreq_nbio
91.Fa "OCSP_RESPONSE **presp"
92.Fa "OCSP_REQ_CTX *rctx"
93.Fc
94.Ft void
95.Fo OCSP_REQ_CTX_free
96.Fa "OCSP_REQ_CTX *rctx"
97.Fc
98.Ft int
99.Fo OCSP_REQ_CTX_add1_header
100.Fa "OCSP_REQ_CTX *rctx"
101.Fa "const char *name"
102.Fa "const char *value"
103.Fc
104.Ft int
105.Fo OCSP_REQ_CTX_set1_req
106.Fa "OCSP_REQ_CTX *rctx"
107.Fa "OCSP_REQUEST *req"
108.Fc
109.Ft int
110.Fo OCSP_parse_url
111.Fa "const char *url"
112.Fa "char **phost"
113.Fa "char **pport"
114.Fa "char **ppath"
115.Fa "int *pssl"
116.Fc
117.Ft OCSP_RESPONSE *
118.Fo OCSP_sendreq_bio
119.Fa "BIO *io"
120.Fa "const char *path"
121.Fa "OCSP_REQUEST *req"
122.Fc
123.Sh DESCRIPTION
124The function
125.Fn OCSP_sendreq_new
126returns an
127.Vt OCSP_REQ_CTX
128structure using the responder
129.Fa io ,
130the URI path
131.Fa path ,
132the OCSP request
133.Fa req
134and with a response header maximum line length of
135.Fa maxline .
136If
137.Fa maxline
138is zero, a default value of 4k is used.
139The OCSP request
140.Fa req
141may be set to
142.Dv NULL
143and provided later if required.
144.Pp
145The arguments to
146.Fn OCSP_sendreq_new
147correspond to the components of the URI.
148For example, if the responder URI is
149.Pa http://ocsp.com/ocspreq ,
150the BIO
151.Fa io
152should be connected to host
153.Pa ocsp.com
154on port 80 and
155.Fa path
156should be set to
157.Qq /ocspreq .
158.Pp
159.Fn OCSP_sendreq_nbio
160performs non-blocking I/O on the OCSP request context
161.Fa rctx .
162When the operation is complete, it returns the response in
163.Pf * Fa presp .
164If
165.Fn OCSP_sendreq_nbio
166indicates an operation should be retried, the corresponding BIO can
167be examined to determine which operation (read or write) should be
168retried and appropriate action can be taken, for example a
169.Xr select 2
170call on the underlying socket.
171.Pp
172.Fn OCSP_REQ_CTX_free
173frees up the OCSP context
174.Fa rctx .
175.Pp
176.Fn OCSP_REQ_CTX_add1_header
177adds header
178.Fa name
179with value
180.Fa value
181to the context
182.Fa rctx .
183The added headers are of the form
184.Qq Fa name : value
185or just
186.Qq Fa name
187if
188.Fa value
189is
190.Dv NULL .
191.Fn OCSP_REQ_CTX_add1_header
192can be called more than once to add multiple headers.
193It must be called before any calls to
194.Fn OCSP_sendreq_nbio .
195The
196.Fa req
197parameter in the initial to
198.Fn OCSP_sendreq_new
199call must be set to
200.Dv NULL
201if additional headers are set.
202.Pp
203.Fn OCSP_REQ_CTX_set1_req
204sets the OCSP request in
205.Fa rctx
206to
207.Fa req .
208This function should be called after any calls to
209.Fn OCSP_REQ_CTX_add1_header .
210.Pp
211.Fn OCSP_parse_url
212is a utility function to parse a
213.Fa url
214of the form
215.Sm off
216.Sy http Op Sy s
217.Pf :// Ar host
218.Op : Ar port
219.Op / Ar path
220.Sm on
221and store pointers to newly allocated copies of the strings
222.Ar host ,
223.Ar port ,
224and
225.Ar path
226in
227.Pf * phost ,
228.Pf * pport ,
229and
230.Pf * ppath ,
231respectively.
232By default,
233.Pf * ppath
234is set to
235.Qq /
236and
237.Pf * pport
238to
239.Qq 443
240for
241.Sy https
242or
243.Qq 80
244for
245.Sy http .
246For
247.Sy https ,
248.Pf * Fa pssl
249is set to 1; otherwise, to 0.
250.Pp
251.Fn OCSP_sendreq_bio
252performs an OCSP request using the responder
253.Fa io ,
254the URI path
255.Fa path ,
256the OCSP request
257.Fa req .
258It does not support retries and so cannot handle non-blocking I/O
259efficiently.
260It is retained for compatibility and its use in new applications
261is not recommended.
262.Sh RETURN VALUES
263.Fn OCSP_sendreq_new
264returns a valid
265.Vt OCSP_REQ_CTX
266structure or
267.Dv NULL
268if an error occurred.
269.Pp
270.Fn OCSP_sendreq_nbio
271returns 1 if the operation was completed successfully,
272-1 if the operation should be retried,
273or 0 if an error occurred.
274.Pp
275.Fn OCSP_REQ_CTX_add1_header ,
276.Fn OCSP_REQ_CTX_set1_req ,
277and
278.Fn OCSP_parse_url
279return 1 for success or 0 for failure.
280.Pp
281.Fn OCSP_sendreq_bio
282returns the
283.Vt OCSP_RESPONSE
284structure sent by the responder or
285.Dv NULL
286if an error occurred.
287.Sh EXAMPLES
288Add a Host header for
289.Pa ocsp.com :
290.Pp
291.Dl OCSP_REQ_CTX_add1_header(ctx, "Host", "ocsp.com");
292.Sh SEE ALSO
293.Xr OCSP_cert_to_id 3 ,
294.Xr OCSP_request_add1_nonce 3 ,
295.Xr OCSP_REQUEST_new 3 ,
296.Xr OCSP_resp_find_status 3 ,
297.Xr OCSP_response_status 3 ,
298.Xr X509_get1_ocsp 3
299.Sh HISTORY
300.Fn OCSP_parse_url
301and
302.Fn OCSP_sendreq_bio
303first appeared in OpenSSL 0.9.7 and have been available since
304.Ox 3.2 .
305.Pp
306.Fn OCSP_sendreq_new ,
307.Fn OCSP_sendreq_nbio ,
308and
309.Fn OCSP_REQ_CTX_free
310first appeared in OpenSSL 0.9.8h and have been available since
311.Ox 4.5 .
312.Pp
313.Fn OCSP_REQ_CTX_add1_header
314and
315.Fn OCSP_REQ_CTX_set1_req
316first appeared in OpenSSL 1.0.0 and have been available since
317.Ox 4.9 .
318.Sh CAVEATS
319These functions only perform a minimal HTTP query to a responder.
320If an application wishes to support more advanced features, it
321should use an alternative, more complete, HTTP library.
322.Pp
323Currently only HTTP POST queries to responders are supported.
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-05-06 17:41:55 +0000