diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/OCSP_sendreq_new.3')
| -rw-r--r-- | secure/lib/libcrypto/man/man3/OCSP_sendreq_new.3 | 182 |
1 files changed, 88 insertions, 94 deletions
diff --git a/secure/lib/libcrypto/man/man3/OCSP_sendreq_new.3 b/secure/lib/libcrypto/man/man3/OCSP_sendreq_new.3 index ab6b315b739b..8d8a42d3f8ce 100644 --- a/secure/lib/libcrypto/man/man3/OCSP_sendreq_new.3 +++ b/secure/lib/libcrypto/man/man3/OCSP_sendreq_new.3 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== @@ -68,8 +68,6 @@ . \} .\} .rr rF -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ @@ -132,135 +130,131 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "OCSP_SENDREQ_NEW 3" -.TH OCSP_SENDREQ_NEW 3 "2022-07-05" "1.1.1q" "OpenSSL" +.IX Title "OCSP_SENDREQ_NEW 3ossl" +.TH OCSP_SENDREQ_NEW 3ossl "2023-09-19" "3.0.11" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" -OCSP_sendreq_new, OCSP_sendreq_nbio, OCSP_REQ_CTX_free, OCSP_set_max_response_length, OCSP_REQ_CTX_add1_header, OCSP_REQ_CTX_set1_req, OCSP_sendreq_bio, OCSP_REQ_CTX_i2d \&\- OCSP responder query functions +OCSP_REQ_CTX, +OCSP_sendreq_new, +OCSP_sendreq_nbio, +OCSP_sendreq_bio, +OCSP_REQ_CTX_i2d, +OCSP_REQ_CTX_add1_header, +OCSP_REQ_CTX_free, +OCSP_set_max_response_length, +OCSP_REQ_CTX_set1_req +\&\- OCSP responder query functions .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include <openssl/ocsp.h> \& -\& OCSP_REQ_CTX *OCSP_sendreq_new(BIO *io, const char *path, OCSP_REQUEST *req, -\& int maxline); -\& -\& int OCSP_sendreq_nbio(OCSP_RESPONSE **presp, OCSP_REQ_CTX *rctx); -\& -\& void OCSP_REQ_CTX_free(OCSP_REQ_CTX *rctx); -\& -\& void OCSP_set_max_response_length(OCSP_REQ_CTX *rctx, unsigned long len); -\& -\& int OCSP_REQ_CTX_add1_header(OCSP_REQ_CTX *rctx, -\& const char *name, const char *value); -\& -\& int OCSP_REQ_CTX_set1_req(OCSP_REQ_CTX *rctx, OCSP_REQUEST *req); -\& +\& OSSL_HTTP_REQ_CTX *OCSP_sendreq_new(BIO *io, const char *path, +\& const OCSP_REQUEST *req, int buf_size); \& OCSP_RESPONSE *OCSP_sendreq_bio(BIO *io, const char *path, OCSP_REQUEST *req); -\& -\& int OCSP_REQ_CTX_i2d(OCSP_REQ_CTX *rctx, const char *content_type, -\& const ASN1_ITEM *it, ASN1_VALUE *req); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fB\s-1OPENSSL_API_COMPAT\s0\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 8 +\& typedef OSSL_HTTP_REQ_CTX OCSP_REQ_CTX; +\& int OCSP_sendreq_nbio(OCSP_RESPONSE **presp, OSSL_HTTP_REQ_CTX *rctx); +\& int OCSP_REQ_CTX_i2d(OCSP_REQ_CT *rctx, const ASN1_ITEM *it, ASN1_VALUE *req); +\& int OCSP_REQ_CTX_add1_header(OCSP_REQ_CT *rctx, +\& const char *name, const char *value); +\& void OCSP_REQ_CTX_free(OCSP_REQ_CTX *rctx); +\& void OCSP_set_max_response_length(OCSP_REQ_CT *rctx, unsigned long len); +\& int OCSP_REQ_CTX_set1_req(OCSP_REQ_CTX *rctx, const OCSP_REQUEST *req); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" -The function \fBOCSP_sendreq_new()\fR returns an \fB\s-1OCSP_CTX\s0\fR structure using the -responder \fBio\fR, the \s-1URL\s0 path \fBpath\fR, the \s-1OCSP\s0 request \fBreq\fR and with a -response header maximum line length of \fBmaxline\fR. If \fBmaxline\fR is zero a -default value of 4k is used. The \s-1OCSP\s0 request \fBreq\fR may be set to \fB\s-1NULL\s0\fR -and provided later if required. +These functions perform an \s-1OCSP POST\s0 request / response transfer over \s-1HTTP,\s0 +using the \s-1HTTP\s0 request functions described in \s-1\fBOSSL_HTTP_REQ_CTX\s0\fR\|(3). .PP -\&\fBOCSP_sendreq_nbio()\fR performs nonblocking I/O on the \s-1OCSP\s0 request context -\&\fBrctx\fR. When the operation is complete it returns the response in \fB*presp\fR. +The function \fBOCSP_sendreq_new()\fR builds a complete \fB\s-1OSSL_HTTP_REQ_CTX\s0\fR structure +with the \fB\s-1BIO\s0\fR \fIio\fR to be used for requests and response, the \s-1URL\s0 path \fIpath\fR, +optionally the \s-1OCSP\s0 request \fIreq\fR, and a response header maximum line length +of \fIbuf_size\fR. If \fIbuf_size\fR is zero a default value of 4KiB is used. +The \fIreq\fR may be set to \s-1NULL\s0 and provided later using \fBOCSP_REQ_CTX_set1_req()\fR +or \fBOSSL_HTTP_REQ_CTX_set1_req\fR\|(3). +The \fIio\fR and \fIpath\fR arguments to \fBOCSP_sendreq_new()\fR correspond to the +components of the \s-1URL.\s0 +For example if the responder \s-1URL\s0 is \f(CW\*(C`http://example.com/ocspreq\*(C'\fR the \s-1BIO\s0 +\&\fIio\fR should haven been connected to host \f(CW\*(C`example.com\*(C'\fR on port 80 and \fIpath\fR +should be set to \f(CW\*(C`/ocspreq\*(C'\fR. .PP -\&\fBOCSP_REQ_CTX_free()\fR frees up the \s-1OCSP\s0 context \fBrctx\fR. +\&\fBOCSP_sendreq_nbio()\fR attempts to send the request prepared in \fIrctx\fR +and to gather the response via \s-1HTTP,\s0 using the \s-1BIO\s0 \fIio\fR and \fIpath\fR +that were given when calling \fBOCSP_sendreq_new()\fR. +If the operation gets completed it assigns the response, +a pointer to a \fB\s-1OCSP_RESPONSE\s0\fR structure, in \fI*presp\fR. +The function may need to be called again if its result is \-1, which indicates +\&\fBBIO_should_retry\fR\|(3). In such a case it is advisable to sleep a little in +between, using \fBBIO_wait\fR\|(3) on the read \s-1BIO\s0 to prevent a busy loop. .PP -\&\fBOCSP_set_max_response_length()\fR sets the maximum response length for \fBrctx\fR -to \fBlen\fR. If the response exceeds this length an error occurs. If not -set a default value of 100k is used. +\&\fBOCSP_sendreq_bio()\fR combines \fBOCSP_sendreq_new()\fR with as many calls of +\&\fBOCSP_sendreq_nbio()\fR as needed and then \fBOCSP_REQ_CTX_free()\fR, with a +response header maximum line length 4k. It waits indefinitely on a response. +It does not support setting a timeout or adding headers and is retained +for compatibility; use \fBOSSL_HTTP_transfer\fR\|(3) instead. .PP -\&\fBOCSP_REQ_CTX_add1_header()\fR adds header \fBname\fR with value \fBvalue\fR to the -context \fBrctx\fR. It can be called more than once to add multiple headers. -It \fB\s-1MUST\s0\fR be called before any calls to \fBOCSP_sendreq_nbio()\fR. The \fBreq\fR -parameter in the initial to \fBOCSP_sendreq_new()\fR call \s-1MUST\s0 be set to \fB\s-1NULL\s0\fR if -additional headers are set. +OCSP_REQ_CTX_i2d(rctx, it, req) is equivalent to the following: +.PP +.Vb 1 +\& OSSL_HTTP_REQ_CTX_set1_req(rctx, "application/ocsp\-request", it, req) +.Ve .PP -\&\fBOCSP_REQ_CTX_set1_req()\fR sets the \s-1OCSP\s0 request in \fBrctx\fR to \fBreq\fR. This -function should be called after any calls to \fBOCSP_REQ_CTX_add1_header()\fR. OCSP_REQ_CTX_set1_req(rctx, req) is equivalent to the following: .PP -.Vb 2 -\& OCSP_REQ_CTX_i2d(rctx, "application/ocsp\-request", -\& ASN1_ITEM_rptr(OCSP_REQUEST), (ASN1_VALUE *)req) +.Vb 3 +\& OSSL_HTTP_REQ_CTX_set1_req(rctx, "application/ocsp\-request", +\& ASN1_ITEM_rptr(OCSP_REQUEST), +\& (const ASN1_VALUE *)req) .Ve .PP -\&\fBOCSP_REQ_CTX_i2d()\fR sets the request context \fBrctx\fR to have the request -\&\fBreq\fR, which has the \s-1ASN.1\s0 type \fBit\fR. -The \fBcontent_type\fR, if not \s-1NULL,\s0 will be included in the \s-1HTTP\s0 request. -The function should be called after all other headers have already been added. -.PP -\&\fBOCSP_sendreq_bio()\fR performs an \s-1OCSP\s0 request using the responder \fBio\fR, the \s-1URL\s0 -path \fBpath\fR, and the \s-1OCSP\s0 request \fBreq\fR with a response header maximum line -length 4k. It waits indefinitely on a response. +The deprecated type and the remaining deprecated functions +have been superseded by the following equivalents: +\&\fB\s-1OCSP_REQ_CTX\s0\fR by \s-1\fBOSSL_HTTP_REQ_CTX\s0\fR\|(3), +\&\fBOCSP_REQ_CTX_add1_header()\fR by \fBOSSL_HTTP_REQ_CTX_add1_header\fR\|(3), +\&\fBOCSP_REQ_CTX_free()\fR by \fBOSSL_HTTP_REQ_CTX_free\fR\|(3), and +\&\fBOCSP_set_max_response_length()\fR by +\&\fBOSSL_HTTP_REQ_CTX_set_max_response_length\fR\|(3). .SH "RETURN VALUES" .IX Header "RETURN VALUES" -\&\fBOCSP_sendreq_new()\fR returns a valid \fB\s-1OCSP_REQ_CTX\s0\fR structure or \fB\s-1NULL\s0\fR if -an error occurred. +\&\fBOCSP_sendreq_new()\fR returns a valid \fB\s-1OSSL_HTTP_REQ_CTX\s0\fR structure or \s-1NULL\s0 +if an error occurred. .PP -\&\fBOCSP_sendreq_nbio()\fR returns \fB1\fR if the operation was completed successfully, -\&\fB\-1\fR if the operation should be retried and \fB0\fR if an error occurred. -.PP -\&\fBOCSP_REQ_CTX_add1_header()\fR, \fBOCSP_REQ_CTX_set1_req()\fR, and \fBOCSP_REQ_CTX_i2d()\fR -return \fB1\fR for success and \fB0\fR for failure. +\&\fBOCSP_sendreq_nbio()\fR returns 1 for success, 0 on error, \-1 if retry is needed. .PP \&\fBOCSP_sendreq_bio()\fR returns the \fB\s-1OCSP_RESPONSE\s0\fR structure sent by the -responder or \fB\s-1NULL\s0\fR if an error occurred. -.PP -\&\fBOCSP_REQ_CTX_free()\fR and \fBOCSP_set_max_response_length()\fR do not return values. -.SH "NOTES" -.IX Header "NOTES" -These functions only perform a minimal \s-1HTTP\s0 query to a responder. If an -application wishes to support more advanced features it should use an -alternative more complete \s-1HTTP\s0 library. -.PP -Currently only \s-1HTTP POST\s0 queries to responders are supported. -.PP -The arguments to \fBOCSP_sendreq_new()\fR correspond to the components of the \s-1URL.\s0 -For example if the responder \s-1URL\s0 is \fBhttp://ocsp.com/ocspreq\fR the \s-1BIO\s0 -\&\fBio\fR should be connected to host \fBocsp.com\fR on port 80 and \fBpath\fR -should be set to \fB\*(L"/ocspreq\*(R"\fR -.PP -The headers added with \fBOCSP_REQ_CTX_add1_header()\fR are of the form -"\fBname\fR: \fBvalue\fR\*(L" or just \*(R"\fBname\fR" if \fBvalue\fR is \fB\s-1NULL\s0\fR. So to add -a Host header for \fBocsp.com\fR you would call: -.PP -.Vb 1 -\& OCSP_REQ_CTX_add1_header(ctx, "Host", "ocsp.com"); -.Ve -.PP -If \fBOCSP_sendreq_nbio()\fR indicates an operation should be retried the -corresponding \s-1BIO\s0 can be examined to determine which operation (read or -write) should be retried and appropriate action taken (for example a \fBselect()\fR -call on the underlying socket). -.PP -\&\fBOCSP_sendreq_bio()\fR does not support retries and so cannot handle nonblocking -I/O efficiently. It is retained for compatibility and its use in new -applications is not recommended. +responder or \s-1NULL\s0 if an error occurred. .SH "SEE ALSO" .IX Header "SEE ALSO" -\&\fBcrypto\fR\|(7), +\&\s-1\fBOSSL_HTTP_REQ_CTX\s0\fR\|(3), \fBOSSL_HTTP_transfer\fR\|(3), \&\fBOCSP_cert_to_id\fR\|(3), \&\fBOCSP_request_add1_nonce\fR\|(3), \&\fBOCSP_REQUEST_new\fR\|(3), \&\fBOCSP_resp_find_status\fR\|(3), \&\fBOCSP_response_status\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +\&\fB\s-1OCSP_REQ_CTX\s0\fR, +\&\fBOCSP_REQ_CTX_i2d()\fR, +\&\fBOCSP_REQ_CTX_add1_header()\fR, +\&\fBOCSP_REQ_CTX_free()\fR, +\&\fBOCSP_set_max_response_length()\fR, +and \fBOCSP_REQ_CTX_set1_req()\fR +were deprecated in OpenSSL 3.0. .SH "COPYRIGHT" .IX Header "COPYRIGHT" -Copyright 2015\-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2015\-2023 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at <https://www.openssl.org/source/license.html>. |