Deprecate OCSP_xxx API for OSSL_HTTP_xxx

Deprecations made:
    OCSP_REQ_CTX typedef->OSSL_HTTP_REQ_CTX
    OCSP_REQ_CTX_new->OSSL_HTTP_REQ_CTX_new
    OCSP_REQ_CTX_free->OSSL_HTTP_REQ_CTX_free
    OCSP_REQ_CTX_http-> OSSL_HTTP_REQ_CTX_header
    OCSP_REQ_CTX_add1_header->OSSL_HTTP_REQ_CTX_add1_header
    OCSP_REQ_CTX_i2d->OSSL_HTTP_REQ_CTX_i2d
    OCSP_REQ_CTX_get0_mem_bio->OSSL_HTTP_REQ_CTX_get0_mem_bio
    OCSP_set_max_response_length->OSSL_HTTP_REQ_CTX_set_max_response_length
    OCSP_REQ_CTX_nbio_d2i->OSSL_HTTP_REQ_CTX_sendreq_d2i
    OCSP_REQ_CTX_nbio->OSSL_HTTP_REQ_CTX_nbio

Made some editorial changes to man3/OCSP_sendreq.pod; move the NOTES
text inline.  Some of the original functions had no documentation:
OCSP_REQ_CTX_new, OCSP_REQ_CTX_http, OCSP_REQ_CTX_get0_mem_bio,
OCSP_REQ_CTX_nbio_d2i, and OCSP_REQ_CTX_nbio.  Their new counterparts
are now documented in doc/man3/OSSL_HTTP_REQ_CTX.pod

Fixes #12234

Co-authored-by: Richard Levitte <levitte@openssl.org>

Reviewed-by: David von Oheimb <david.von.oheimb@siemens.com>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/13742)

2 files changed, 240 insertions, 77 deletions

diff --git a/doc/man3/OCSP_sendreq_new.pod b/doc/man3/OCSP_sendreq_new.pod
index 0f9d1339c9..6e346bdd44 100644
--- a/doc/man3/OCSP_sendreq_new.pod
+++ b/doc/man3/OCSP_sendreq_new.pod
@@ -4,11 +4,11 @@
 
 OCSP_sendreq_new,
 OCSP_sendreq_nbio,
-OCSP_REQ_CTX_free,
-OCSP_set_max_response_length,
-OCSP_REQ_CTX_add1_header,
 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
 
@@ -16,104 +16,78 @@ OCSP_REQ_CTX_set1_req
 
  #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);
+ OSSL_HTTP_REQ_CTX *OCSP_sendreq_new(BIO *io, const char *path,
+                                     OCSP_REQUEST *req, int maxline);
 
- int OCSP_REQ_CTX_add1_header(OCSP_REQ_CTX *rctx,
-                              const char *name, const char *value);
+ int OCSP_sendreq_nbio(OCSP_RESPONSE **presp, OSSL_HTTP_REQ_CTX *rctx);
 
  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);
-
 Deprecated since OpenSSL 3.0, can be hidden entirely by defining
 B<OPENSSL_API_COMPAT> with a suitable version value, see
 L<openssl_user_macros(7)>:
 
+ int OCSP_REQ_CTX_i2d(OCSP_REQ_CT *rctx, const char *content_type,
+                      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);
 
 =head1 DESCRIPTION
 
-The function OCSP_sendreq_new() returns an B<OCSP_CTX> structure using the
-responder B<io>, the URL path B<path>, the OCSP request B<req> and with a
-response header maximum line length of B<maxline>. If B<maxline> is zero a
-default value of 4k is used. The OCSP request B<req> may be set to B<NULL>
-and provided later if required.
-
-OCSP_sendreq_nbio() performs I/O on the OCSP request context B<rctx>.
-When the operation is complete it returns the response in B<*presp>.
-
-OCSP_REQ_CTX_free() frees up the OCSP context B<rctx>.
+These functions perform an OCSP request / response transfer over HTTP, using
+the HTTP request functions described in L<OSSL_HTTP_REQ_CTX(3)>.
 
-OCSP_set_max_response_length() sets the maximum response length
-for B<rctx> to B<len>. If the response exceeds this length an error occurs.
-If not set a default value of 100k is used.
+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 OCSP request I<req>
+may be set to NULL and provided later with L<OSSL_HTTP_REQ_CTX_i2d(3)> if
+required.
 
-OCSP_REQ_CTX_add1_header() adds header B<name> with value B<value> to the
-context B<rctx>. It can be called more than once to add multiple headers.
-It B<MUST> be called before any calls to OCSP_sendreq_nbio(). The B<req>
-parameter in the initial to OCSP_sendreq_new() call MUST be set to B<NULL> if
-additional headers are set.
+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>
+should be set to C</ocspreq>.
 
-OCSP_sendreq_bio() performs an OCSP request using the responder B<io>, the URL
-path B<path>, the OCSP request B<req> and with a response header maximum line
-length 4k. It waits indefinitely on a response.
+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_REQ_CTX_i2d() sets the request context B<rctx> to have the request
-B<req>, which has the ASN.1 type B<it>.
-The B<content_type>, if not NULL, will be included in the HTTP request.
-The function should be called after all other headers have already been added.
+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
+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.
 
 OCSP_REQ_CTX_set1_req(rctx, req) is equivalent to the following:
 
- OCSP_REQ_CTX_i2d(rctx, "application/ocsp-request",
-                        ASN1_ITEM_rptr(OCSP_REQUEST), (ASN1_VALUE *)req)
+ OSSL_HTTP_REQ_CTX_i2d(rctx, "application/ocsp-request",
+                       ASN1_ITEM_rptr(OCSP_REQUEST), (ASN1_VALUE *)req)
+
+The other deprecated type and functions have been superseded by the
+following equivalents:
+B<OCSP_REQ_CTX> by L<OSSL_HTTP_REQ_CTX(3)>,
+OCSP_REQ_CTX_i2d() by L<OSSL_HTTP_REQ_CTX_i2d(3)>,
+OCSP_REQ_CTX_add1_header() by L<OSSL_HTTP_REQ_CTX_add1_header(3)>,
+OCSP_REQ_CTX_free() by L<OSSL_HTTP_REQ_CTX_free(3)>, and
+OCSP_set_max_response_length() by
+L<OSSL_HTTP_REQ_CTX_set_max_response_length(3)>.
 
 =head1 RETURN VALUES
 
-OCSP_sendreq_new() returns a valid B<OCSP_REQ_CTX> structure or B<NULL>
+OCSP_sendreq_new() returns a valid B<OSSL_HTTP_REQ_CTX> structure or NULL
 if an error occurred.
 
-OCSP_sendreq_nbio(), OCSP_REQ_CTX_add1_header(), OCSP_REQ_CTX_i2d(),
-and OCSP_REQ_CTX_set1_req()
-return B<1> for success and B<0> for failure.
+OCSP_sendreq_nbio(), OCSP_REQ_CTX_i2d(), and OCSP_REQ_CTX_set1_req()
+return 1 for success and 0 for failure.
 
 OCSP_sendreq_bio() returns the B<OCSP_RESPONSE> structure sent by the
-responder or B<NULL> if an error occurred.
-
-OCSP_REQ_CTX_free() and OCSP_set_max_response_length()
-do not return values.
-
-=head1 NOTES
-
-These functions only perform a minimal HTTP query to a responder. If an
-application wishes to support more advanced features it should use an
-alternative more complete HTTP library.
-
-Currently only HTTP POST queries to responders are supported.
-
-The arguments to OCSP_sendreq_new() correspond to the components of the URL.
-For example if the responder URL is B<http://ocsp.com/ocspreq> the BIO
-B<io> should be connected to host B<ocsp.com> on port 80 and B<path>
-should be set to B<"/ocspreq">
-
-The headers added with OCSP_REQ_CTX_add1_header() are of the form
-"B<name>: B<value>" or just "B<name>" if B<value> is B<NULL>. So to add
-a Host header for B<ocsp.com> you would call:
-
- OCSP_REQ_CTX_add1_header(ctx, "Host", "ocsp.com");
-
-OCSP_sendreq_bio() does not support timeout nor setting extra headers.
-It is retained for compatibility.
-Better use B<OCSP_sendreq_nbio()> instead.
+responder or NULL if an error occurred.
 
 =head1 SEE ALSO
 
@@ -126,11 +100,17 @@ L<OCSP_response_status(3)>
 
 =head1 HISTORY
 
-The OCSP_REQ_CTX_set1_req() function was deprecated in OpenSSL 3.0.
+B<OCSP_REQ_CTX>,
+OCSP_REQ_CTX_i2d(),
+OCSP_REQ_CTX_add1_header(),
+OCSP_REQ_CTX_free(),
+OCSP_set_max_response_length(),
+and OCSP_REQ_CTX_set1_req()
+were deprecated in OpenSSL 3.0.
 
 =head1 COPYRIGHT
 
-Copyright 2015-2020 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2015-2021 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/doc/man3/OSSL_HTTP_REQ_CTX.pod b/doc/man3/OSSL_HTTP_REQ_CTX.pod
new file mode 100644
index 0000000000..b75bac5f8c
--- /dev/null
+++ b/doc/man3/OSSL_HTTP_REQ_CTX.pod
@@ -0,0 +1,183 @@
+=pod
+
+=head1 NAME
+
+OSSL_HTTP_REQ_CTX,
+OSSL_HTTP_REQ_CTX_new,
+OSSL_HTTP_REQ_CTX_free,
+OSSL_HTTP_REQ_CTX_header,
+OSSL_HTTP_REQ_CTX_add1_header,
+OSSL_HTTP_REQ_CTX_i2d,
+OSSL_HTTP_REQ_CTX_nbio,
+OSSL_HTTP_REQ_CTX_sendreq_d2i,
+OSSL_HTTP_REQ_CTX_get0_mem_bio,
+OSSL_HTTP_REQ_CTX_set_max_response_length
+- HTTP request functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/http.h>
+
+ typedef struct ossl_http_req_ctx_st OSSL_HTTP_REQ_CTX;
+
+ OSSL_HTTP_REQ_CTX *OSSL_HTTP_REQ_CTX_new(BIO *wbio, BIO *rbio,
+                                          int method_GET, int maxline,
+                                          unsigned long max_resp_len,
+                                          int timeout,
+                                          const char *expected_content_type,
+                                          int expect_asn1);
+ void OSSL_HTTP_REQ_CTX_free(OSSL_HTTP_REQ_CTX *rctx);
+
+ int OSSL_HTTP_REQ_CTX_header(OSSL_HTTP_REQ_CTX *rctx,
+                              const char *server,
+                              const char *port, const char *path);
+ int OSSL_HTTP_REQ_CTX_add1_header(OSSL_HTTP_REQ_CTX *rctx,
+                                   const char *name, const char *value);
+
+ int OSSL_HTTP_REQ_CTX_i2d(OSSL_HTTP_REQ_CTX *rctx, const char *content_type,
+                           const ASN1_ITEM *it, ASN1_VALUE *req);
+ int OSSL_HTTP_REQ_CTX_nbio(OSSL_HTTP_REQ_CTX *rctx);
+ ASN1_VALUE *OSSL_HTTP_REQ_CTX_sendreq_d2i(OSSL_HTTP_REQ_CTX *rctx,
+                                           const ASN1_ITEM *it);
+
+ BIO *OSSL_HTTP_REQ_CTX_get0_mem_bio(OSSL_HTTP_REQ_CTX *rctx);
+ void OSSL_HTTP_REQ_CTX_set_max_response_length(OSSL_HTTP_REQ_CTX *rctx,
+                                                unsigned long len);
+
+=head1 DESCRIPTION
+
+B<OSSL_HTTP_REQ_CTX> is a context structure for an HTTP request, used to
+collect all the necessary data to perform that request.
+
+This file documents low-level HTTP functions rarely used directly.  High-level
+HTTP client functions like L<OSSL_HTTP_get(3)> and L<OSSL_HTTP_transfer(3)>
+should be preferred.
+
+OSSL_HTTP_REQ_CTX_new() allocates a new HTTP request context structure, which
+gets populated with the B<BIO> to send the request to (I<wbio>), the B<BIO> to
+read the response from (I<rbio>, which may be the same as I<wbio>), the
+request method (I<method_GET>, which may be 1 to indicate that the C<GET>
+method is to be used, or 0 to indicate that the C<POST> method is to be used),
+the maximum expected response header length (I<max_resp_len>, where any zero
+or less indicates the default of 4KiB), a response timeout measure in seconds
+(I<timeout>, where 0 indicates no timeout, i.e., waiting indefinitely), the
+expected MIME content type of the response (I<expected_content_type>, which
+may be NULL for no expectation), and a flag indicating that the response is
+expected to be a DER encoded ASN.1 structure (I<expect_asn1>).
+The allocated context structure is also populated with an internal allocated
+memory B<BIO>, which collects the HTTP request and additional headers as text.
+The returned context should only be used for a single HTTP request/response.
+
+OSSL_HTTP_REQ_CTX_free() frees up the HTTP request context I<rctx>.
+The I<wbio> and I<rbio> are not free'd and it is up to the application
+to do so.
+
+OSSL_HTTP_REQ_CTX_header() adds an HTTP request line to the request context.
+The request command itself becomes C<GET> or C<POST> depending on the value
+of I<method_GET> in the OSSL_HTTP_REQ_CTX_new() call.  I<server> and I<port>
+may be set to indicate a proxy server and port that the request should go
+through, otherwise they should be left NULL.  I<path> is the HTTP request path;
+if left NULL, C</> is used.
+
+OSSL_HTTP_REQ_CTX_add1_header() adds header I<name> with value I<value> to the
+context I<rctx>. It can be called more than once to add multiple headers.
+For example, to add a C<Host> header for C<example.com> you would call:
+
+ OSSL_HTTP_REQ_CTX_add1_header(ctx, "Host", "example.com");
+
+OSSL_HTTP_REQ_CTX_i2d() finalizes the HTTP request context by adding the DER
+encoding of I<req>, using the ASN.1 template I<it> to do the encoding.  The
+HTTP header C<Content-Length> is automatically filled out, and if
+I<content_type> isn't NULL, the HTTP header C<Content-Type> is also added with
+its content as value.  All of this ends up in the internal memory B<BIO>.
+This requires that the request type be C<POST>, i.e. that I<method_GET> is 0
+in the OSSL_HTTP_REQ_CTX_new() call.
+
+OSSL_HTTP_REQ_CTX_nbio() attempts the exchange of request and response via HTTP,
+using the I<rbio> and I<wbio> that were given in the OSSL_HTTP_REQ_CTX_new()
+call.  When successful, the contents of the internal memory B<BIO> is replaced
+with the contents of the HTTP response, without the response headers.
+It 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 to prevent a busy loop.
+
+OSSL_HTTP_REQ_CTX_sendreq_d2i() calls OSSL_HTTP_REQ_CTX_nbio(), possibly
+several times until a timeout is reached, and DER decodes the received
+response using the ASN.1 template I<it>.
+
+OSSL_HTTP_REQ_CTX_set_max_response_length() sets the maximum response length
+for I<rctx> to I<len>. If the response exceeds this length an error occurs.
+If not set a default value of 100k is used.
+
+OSSL_HTTP_REQ_CTX_get0_mem_bio() returns the internal memory B<BIO>.  This can
+be used to affect the HTTP request text.  I<Use with caution!>
+
+=head1 WARNINGS
+
+The server's response may be unexpected if the hostname that was used to
+create the I<wbio>, any C<Host> header, and the host specified in the
+request URL do not match.
+
+Many of these functions must be called in a certain order.
+
+First, the HTTP request context must be allocated:
+OSSL_HTTP_REQ_CTX_new().
+
+Then, the HTTP request must be prepared with request data:
+
+=over 4
+
+=item 1.
+
+Calling OSSL_HTTP_REQ_CTX_header().  This must be done exactly once.
+
+=item 2.
+
+Adding extra headers with OSSL_HTTP_REQ_CTX_add1_header().  This is optional.
+
+=item 3.
+
+Add C<POST> data with OSSL_HTTP_REQ_CTX_i2d().  This may only be done if
+I<method_GET> was 0 in the OSSL_HTTP_REQ_CTX_new() call, and must be done
+exactly once in that case.
+
+=back
+
+When the request context is fully prepared, the HTTP exchange may be performed
+with OSSL_HTTP_REQ_CTX_nbio() or OSSL_HTTP_REQ_CTX_sendreq_d2i().
+
+Furthermore, all calls of OSSL_HTTP_REQ_CTX_header() and
+OSSL_HTTP_REQ_CTX_add1_header() must be done before any call to
+int OSSL_HTTP_REQ_CTX_nbio() or OSSL_HTTP_REQ_CTX_sendreq_d2i().
+
+=head1 RETURN VALUES
+
+OSSL_HTTP_REQ_CTX_new() returns a pointer to a B<OSSL_HTTP_REQ_CTX>, or NULL
+on error.
+
+OSSL_HTTP_REQ_CTX_free() and OSSL_HTTP_REQ_CTX_set_max_response_length()
+do not return values.
+
+OSSL_HTTP_REQ_CTX_header(), OSSL_HTTP_REQ_CTX_add1_header(),
+OSSL_HTTP_REQ_CTX_i2d() and OSSL_HTTP_REQ_CTX_nbio return 1 for success and 0
+for failure.
+
+OSSL_HTTP_REQ_CTX_sendreq_d2i() returns a pointer to an B<ASN1_VALUE> for
+success and NULL for failure.
+
+OSSL_HTTP_REQ_CTX_get0_mem_bio() returns the internal memory B<BIO>.
+
+=head1 SEE ALSO
+
+L<OSSL_HTTP_transfer(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2015-2021 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut