Document OCSP_basic_verify(3).

From David dot von dot Oheimb at siemens dot com
via OpenSSL commit b8c32081 Feb 10 15:45:11 2018 +0100, which is still
under a free license because it is before the 1.1.1 branch point.

1 files changed, 75 insertions, 5 deletions

diff --git a/src/lib/libcrypto/man/OCSP_resp_find_status.3 b/src/lib/libcrypto/man/OCSP_resp_find_status.3
index 1c4da4e99e..a32019c4d6 100644
--- a/src/lib/libcrypto/man/OCSP_resp_find_status.3
+++ b/src/lib/libcrypto/man/OCSP_resp_find_status.3
@@ -1,5 +1,6 @@
-.\" $OpenBSD: OCSP_resp_find_status.3,v 1.8 2018/03/23 23:18:17 schwarze Exp $
+.\" $OpenBSD: OCSP_resp_find_status.3,v 1.9 2019/03/15 11:15:33 schwarze Exp $
 .\" full merge up to: OpenSSL c952780c Jun 21 07:03:34 2016 -0400
+.\" selective merge up to: OpenSSL 1212818e Sep 11 13:22:14 2018 +0100
 .\"
 .\" This file is a derived work.
 .\" The changes are covered by the following Copyright and license:
@@ -18,8 +19,9 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
-.\" Copyright (c) 2014 The OpenSSL Project.  All rights reserved.
+.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>
+.\" and David von Oheimb <David.von.Oheimb@siemens.com>.
+.\" Copyright (c) 2014, 2018 The OpenSSL Project.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -65,7 +67,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: March 23 2018 $
+.Dd $Mdocdate: March 15 2019 $
 .Dt OCSP_RESP_FIND_STATUS 3
 .Os
 .Sh NAME
@@ -81,7 +83,8 @@
 .Nm OCSP_resp_find ,
 .Nm OCSP_SINGLERESP_get0_id ,
 .Nm OCSP_single_get0_status ,
-.Nm OCSP_check_validity
+.Nm OCSP_check_validity ,
+.Nm OCSP_basic_verify
 .Nd OCSP response utility functions
 .Sh SYNOPSIS
 .In openssl/ocsp.h
@@ -141,6 +144,13 @@
 .Fa "long sec"
 .Fa "long maxsec"
 .Fc
+.Ft int
+.Fo OCSP_basic_verify
+.Fa "OCSP_BASICRESP *bs"
+.Fa "STACK_OF(X509) *certs"
+.Fa "X509_STORE *st"
+.Fa "unsigned long flags"
+.Fc
 .Sh DESCRIPTION
 .Fn OCSP_SINGLERESP_new
 allocates and initializes an empty
@@ -322,6 +332,63 @@ application.
 Any or all of these parameters can be set to
 .Dv NULL
 if their value is not required.
+.Pp
+.Fn OCSP_basic_verify
+checks that the basic response message
+.Fa bs
+is correctly signed and that the signer certificate can be validated.
+It takes
+.Fa st
+as the trusted store and
+.Fa certs
+as a set of untrusted intermediate certificates.
+The function first tries to find the signer certificate of the response in
+.Fa certs .
+It also searches the certificates the responder may have included in
+.Fa bs
+unless the
+.Fa flags
+contain
+.Dv OCSP_NOINTERN .
+It fails if the signer certificate cannot be found.
+Next, the function checks the signature of
+.Fa bs
+and fails on error unless the
+.Fa flags
+contain
+.Dv OCSP_NOSIGS .
+Then the function already returns
+success if the
+.Fa flags
+contain
+.Dv OCSP_NOVERIFY
+or if the signer certificate was found in
+.Fa certs
+and the
+.Fa flags
+contain
+.Dv OCSP_TRUSTOTHER .
+Otherwise the function continues by validating the signer certificate.
+To this end, all certificates in
+.Fa certs
+and in
+.Fa bs
+are considered as untrusted certificates for the construction of
+the validation path for the signer certificate unless the
+.Dv OCSP_NOCHAIN
+flag is set.
+After successful path
+validation, the function returns success if the
+.Dv OCSP_NOCHECKS
+flag is set.
+Otherwise it verifies that the signer certificate meets the OCSP issuer
+criteria including potential delegation.
+If this does not succeed and the
+.Fa flags
+do not contain
+.Dv OCSP_NOEXPLICIT ,
+the function checks for explicit trust for OCSP signing
+in the root CA certificate.
 .Sh RETURN VALUES
 .Fn OCSP_SINGLERESP_new ,
 .Fn OCSP_CERTSTATUS_new ,
@@ -376,6 +443,9 @@ the returned pointer should not be freed by the caller.
 returns the status of
 .Fa single
 or -1 if an error occurred.
+.Pp
+.Fn OCSP_basic_verify
+returns 1 on success, 0 on error, or -1 on fatal error such as malloc failure.
 .Sh SEE ALSO
 .Xr OCSP_cert_to_id 3 ,
 .Xr OCSP_CRLID_new 3 ,