Fix some SSL_export_keying_material() issues

[openssl.git] / doc / man3 / OCSP_resp_find_status.pod

diff --git a/doc/man3/OCSP_resp_find_status.pod b/doc/man3/OCSP_resp_find_status.pod
index e1442eb97ec05dca39dddd0b1bb1c0562fb38db5..35f7d35e99764cc4b0a1ee1b184cd05baedcadd4 100644 (file)
--- a/doc/man3/OCSP_resp_find_status.pod
+++ b/doc/man3/OCSP_resp_find_status.pod
@@ -3,11 +3,16 @@
 =head1 NAME
 
 OCSP_resp_get0_certs,
+OCSP_resp_get0_signer,
 OCSP_resp_get0_id,
 OCSP_resp_get1_id,
 OCSP_resp_get0_produced_at,
+OCSP_resp_get0_signature,
+OCSP_resp_get0_tbs_sigalg,
+OCSP_resp_get0_respdata,
 OCSP_resp_find_status, OCSP_resp_count, OCSP_resp_get0, OCSP_resp_find,
-OCSP_single_get0_status, OCSP_check_validity
+OCSP_single_get0_status, OCSP_check_validity,
+OCSP_basic_verify
 - OCSP response utility functions
 
 =head1 SYNOPSIS
@@ -31,8 +36,14 @@ OCSP_single_get0_status, OCSP_check_validity
  const ASN1_GENERALIZEDTIME *OCSP_resp_get0_produced_at(
                              const OCSP_BASICRESP* single);
 
+ const ASN1_OCTET_STRING *OCSP_resp_get0_signature(const OCSP_BASICRESP *bs);
+ const X509_ALGOR *OCSP_resp_get0_tbs_sigalg(const OCSP_BASICRESP *bs);
+ const OCSP_RESPDATA *OCSP_resp_get0_respdata(const OCSP_BASICRESP *bs);
  const STACK_OF(X509) *OCSP_resp_get0_certs(const OCSP_BASICRESP *bs);
 
+ int OCSP_resp_get0_signer(OCSP_BASICRESP *bs, X509 **signer,
+                           STACK_OF(X509) *extra_certs);
+
  int OCSP_resp_get0_id(const OCSP_BASICRESP *bs,
                        const ASN1_OCTET_STRING **pid,
                        const X509_NAME **pname);
@@ -44,6 +55,9 @@ OCSP_single_get0_status, OCSP_check_validity
                          ASN1_GENERALIZEDTIME *nextupd,
                          long sec, long maxsec);
 
+ int OCSP_basic_verify(OCSP_BASICRESP *bs, STACK_OF(X509) *certs,
+                      X509_STORE *st, unsigned long flags);
+
 =head1 DESCRIPTION
 
 OCSP_resp_find_status() searches B<bs> for an OCSP response for B<id>. If it is
@@ -74,9 +88,21 @@ B<*revtime>, B<*thisupd> and B<*nextupd>.
 OCSP_resp_get0_produced_at() extracts the B<producedAt> field from the
 single response B<bs>.
 
+OCSP_resp_get0_signature() returns the signature from B<bs>.
+
+OCSP_resp_get0_tbs_sigalg() returns the B<signatureAlgorithm> from B<bs>.
+
+OCSP_resp_get0_respdata() returns the B<tbsResponseData> from B<bs>.
+
 OCSP_resp_get0_certs() returns any certificates included in B<bs>.
 
-OCSP_resp_get0_id() gets the responder id of <bs>. If the responder ID is
+OCSP_resp_get0_signer() attempts to retrieve the certificate that directly
+signed B<bs>.  The OCSP protocol does not require that this certificate
+is included in the B<certs> field of the response, so additional certificates
+can be supplied in B<extra_certs> if the certificates that may have
+signed the response are known via some out-of-band mechanism.
+
+OCSP_resp_get0_id() gets the responder id of B<bs>. If the responder ID is
 a name then <*pname> is set to the name and B<*pid> is set to NULL. If the
 responder ID is by key ID then B<*pid> is set to the key ID and B<*pname>
 is set to NULL. OCSP_resp_get1_id() leaves ownership of B<*pid> and B<*pname>
@@ -90,6 +116,27 @@ OCSP_single_get0_status(). If B<sec> is non-zero it indicates how many seconds
 leeway should be allowed in the check. If B<maxsec> is positive it indicates
 the maximum age of B<thisupd> in seconds.
 
+OCSP_basic_verify() checks that the basic response message B<bs> is correctly
+signed and that the signer certificate can be validated. It takes B<st> as
+the trusted store and B<certs> as a set of untrusted intermediate certificates.
+The function first tries to find the signer certificate of the response
+in <certs>. It also searches the certificates the responder may have included
+in B<bs> unless the B<flags> contain B<OCSP_NOINTERN>.
+It fails if the signer certificate cannot be found.
+Next, the function checks the signature of B<bs> and fails on error
+unless the B<flags> contain B<OCSP_NOSIGS>. Then the function already returns
+success if the B<flags> contain B<OCSP_NOVERIFY> or if the signer certificate
+was found in B<certs> and the B<flags> contain B<OCSP_TRUSTOTHER>.
+Otherwise the function continues by validating the signer certificate.
+To this end, all certificates in B<cert> and in B<bs> are considered as
+untrusted certificates for the construction of the validation path for the
+signer certificate unless the B<OCSP_NOCHAIN> flag is set. After successful path
+validation the function returns success if the B<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
+B<flags> do not contain B<OCSP_NOEXPLICIT> the function checks for explicit
+trust for OCSP signing in the root CA certificate.
+
 =head1 RETURN VALUES
 
 OCSP_resp_find_status() returns 1 if B<id> is found in B<bs> and 0 otherwise.
@@ -106,6 +153,12 @@ B<id> was not found.
 OCSP_single_get0_status() returns the status of B<single> or -1 if an error
 occurred.
 
+OCSP_resp_get0_signer() returns 1 if the signing certificate was located,
+or 0 on error.
+
+OCSP_basic_verify() returns 1 on success, 0 on error, or -1 on fatal error such
+as malloc failure.
+
 =head1 NOTES
 
 Applications will typically call OCSP_resp_find_status() using the certificate
@@ -136,7 +189,7 @@ L<OCSP_sendreq_new(3)>
 
 =head1 COPYRIGHT
 
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy