diff options
Diffstat (limited to 'doc/man3/OCSP_sendreq_new.pod')
| -rw-r--r-- | doc/man3/OCSP_sendreq_new.pod | 46 |
1 files changed, 23 insertions, 23 deletions
diff --git a/doc/man3/OCSP_sendreq_new.pod b/doc/man3/OCSP_sendreq_new.pod index 10c6131f86..51469661de 100644 --- a/doc/man3/OCSP_sendreq_new.pod +++ b/doc/man3/OCSP_sendreq_new.pod @@ -18,10 +18,7 @@ OCSP_REQ_CTX_set1_req #include <openssl/ocsp.h> OSSL_HTTP_REQ_CTX *OCSP_sendreq_new(BIO *io, const char *path, - const OCSP_REQUEST *req, int maxline); - - int OCSP_sendreq_nbio(OCSP_RESPONSE **presp, OSSL_HTTP_REQ_CTX *rctx); - + const OCSP_REQUEST *req, int buf_size); OCSP_RESPONSE *OCSP_sendreq_bio(BIO *io, const char *path, OCSP_REQUEST *req); Deprecated since OpenSSL 3.0, can be hidden entirely by defining @@ -29,12 +26,12 @@ B<OPENSSL_API_COMPAT> with a suitable version value, see L<openssl_user_macros(7)>: 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); + 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); =head1 DESCRIPTION @@ -42,28 +39,32 @@ L<openssl_user_macros(7)>: These functions perform an OCSP POST request / response transfer over HTTP, using the HTTP request functions described in L<OSSL_HTTP_REQ_CTX(3)>. -The function OCSP_sendreq_new() builds a complete B<OSSL_HTTP_REQ_CTX> -structure using connection B<BIO> I<io>, the URL path I<path>, the OCSP -request I<req>, and with a response header maximum line length of I<maxline>. -If I<maxline> is zero a default value of 4k is used. +The function OCSP_sendreq_new() builds a complete B<OSSL_HTTP_REQ_CTX> structure +with the B<BIO> I<io> to be used for requests and reponse, the URL path I<path>, +optionally the OCSP request I<req>, and a response header maximum line length +of I<buf_size>. If I<buf_size> is zero a default value of 4KiB is used. The I<req> may be set to NULL and provided later using OCSP_REQ_CTX_set1_req() -or L<OSSL_HTTP_REQ_CTX_set1_req(3)> . - +or L<OSSL_HTTP_REQ_CTX_set1_req(3)>. The I<io> and I<path> arguments to OCSP_sendreq_new() correspond to the components of the URL. For example if the responder URL is C<http://example.com/ocspreq> the BIO -I<io> should be connected to host C<example.com> on port 80 and I<path> +I<io> should haven been connected to host C<example.com> on port 80 and I<path> should be set to C</ocspreq>. -OCSP_sendreq_nbio() performs I/O on the OCSP request context I<rctx>. -When the operation is complete it assigns the response, a pointer to a -B<OCSP_RESPONSE> structure, in I<*presp>. - -OCSP_sendreq_bio() is the same as a call to OCSP_sendreq_new() followed by -OCSP_sendreq_nbio() and then OCSP_REQ_CTX_free() in a single call, with a +OCSP_sendreq_nbio() attempts to send the request prepared in I<rctx> +and to gather the response via HTTP, using the BIO I<io> and I<path> +that were given when calling OCSP_sendreq_new(). +If the operation gets completed it assigns the response, +a pointer to a B<OCSP_RESPONSE> structure, in I<*presp>. +The function may need to be called again if its result is -1, which indicates +L<BIO_should_retry(3)>. In such a case it is advisable to sleep a little in +between, using L<BIO_wait(3)> on the read BIO to prevent a busy loop. + +OCSP_sendreq_bio() combines OCSP_sendreq_new() with as many calls of +OCSP_sendreq_nbio() as needed and then OCSP_REQ_CTX_free(), 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 OCSP_sendreq_nbio() instead. +for compatibility; use L<OSSL_HTTP_transfer(3)> instead. OCSP_REQ_CTX_i2d(rctx, it, req) is equivalent to the following: @@ -88,15 +89,14 @@ L<OSSL_HTTP_REQ_CTX_set_max_response_length(3)>. OCSP_sendreq_new() returns a valid B<OSSL_HTTP_REQ_CTX> structure or NULL if an error occurred. -OCSP_sendreq_nbio(), OCSP_REQ_CTX_i2d(), and OCSP_REQ_CTX_set1_req() -return 1 for success and 0 for failure. +OCSP_sendreq_nbio() returns 1 for success, 0 on error, -1 if retry is needed. OCSP_sendreq_bio() returns the B<OCSP_RESPONSE> structure sent by the responder or NULL if an error occurred. =head1 SEE ALSO -L<OSSL_HTTP_REQ_CTX(3)> +L<OSSL_HTTP_REQ_CTX(3)>, L<OSSL_HTTP_transfer(3)>, L<OCSP_cert_to_id(3)>, L<OCSP_request_add1_nonce(3)>, L<OCSP_REQUEST_new(3)>, |