Fixed EVP_MAC_final argument count in example

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

diff --git a/doc/man3/CT_POLICY_EVAL_CTX_new.pod b/doc/man3/CT_POLICY_EVAL_CTX_new.pod
index 0f50078b51f0d400a6a835bad7c3569a7eaad65f..126607609793c37b2a6734716f696e2c3afe895f 100644 (file)
--- a/doc/man3/CT_POLICY_EVAL_CTX_new.pod
+++ b/doc/man3/CT_POLICY_EVAL_CTX_new.pod
@@ -2,6 +2,7 @@
 
 =head1 NAME
 
+CT_POLICY_EVAL_CTX_new_with_libctx,
 CT_POLICY_EVAL_CTX_new, CT_POLICY_EVAL_CTX_free,
 CT_POLICY_EVAL_CTX_get0_cert, CT_POLICY_EVAL_CTX_set1_cert,
 CT_POLICY_EVAL_CTX_get0_issuer, CT_POLICY_EVAL_CTX_set1_issuer,
@@ -13,6 +14,8 @@ Encapsulates the data required to evaluate whether SCTs meet a Certificate Trans
 
  #include <openssl/ct.h>
 
+ CT_POLICY_EVAL_CTX *CT_POLICY_EVAL_CTX_new_with_libctx(OPENSSL_CTX *libctx,
+                                                        const char *propq);
  CT_POLICY_EVAL_CTX *CT_POLICY_EVAL_CTX_new(void);
  void CT_POLICY_EVAL_CTX_free(CT_POLICY_EVAL_CTX *ctx);
  X509* CT_POLICY_EVAL_CTX_get0_cert(const CT_POLICY_EVAL_CTX *ctx);
@@ -20,7 +23,8 @@ Encapsulates the data required to evaluate whether SCTs meet a Certificate Trans
  X509* CT_POLICY_EVAL_CTX_get0_issuer(const CT_POLICY_EVAL_CTX *ctx);
  int CT_POLICY_EVAL_CTX_set1_issuer(CT_POLICY_EVAL_CTX *ctx, X509 *issuer);
  const CTLOG_STORE *CT_POLICY_EVAL_CTX_get0_log_store(const CT_POLICY_EVAL_CTX *ctx);
- void CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE(CT_POLICY_EVAL_CTX *ctx, CTLOG_STORE *log_store);
+ void CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE(CT_POLICY_EVAL_CTX *ctx,
+                                                CTLOG_STORE *log_store);
  uint64_t CT_POLICY_EVAL_CTX_get_time(const CT_POLICY_EVAL_CTX *ctx);
  void CT_POLICY_EVAL_CTX_set_time(CT_POLICY_EVAL_CTX *ctx, uint64_t time_in_ms);
 
@@ -32,43 +36,69 @@ This policy may be, for example, that at least one valid SCT is available. To
 determine this, an SCT's timestamp and signature must be verified.
 This requires:
 
-=over
+=over 2
 
-=item * the public key of the log that issued the SCT
+=item *
 
-=item * the certificate that the SCT was issued for
+the public key of the log that issued the SCT
 
-=item * the issuer certificate (if the SCT was issued for a pre-certificate)
+=item *
 
-=item * the current time
+the certificate that the SCT was issued for
+
+=item *
+
+the issuer certificate (if the SCT was issued for a pre-certificate)
+
+=item *
+
+the current time
 
 =back
 
 The above requirements are met using the setters described below.
 
-CT_POLICY_EVAL_CTX_new() creates an empty policy evaluation context. This
-should then be populated using:
+CT_POLICY_EVAL_CTX_new_with_libctx() creates an empty policy evaluation context
+and associates it with the given library context I<libctx> and property query
+string I<propq>.
+
+CT_POLICY_EVAL_CTX_new() does the same thing as
+CT_POLICY_EVAL_CTX_new_with_libctx() except that it uses the default library
+context and property query string.
+
+The CT_POLICY_EVAL_CTX should then be populated using:
 
-=over
+=over 2
 
-=item * CT_POLICY_EVAL_CTX_set1_cert() to provide the certificate the SCTs were issued for
+=item *
+
+CT_POLICY_EVAL_CTX_set1_cert() to provide the certificate the SCTs were issued for
 
 Increments the reference count of the certificate.
 
-=item * CT_POLICY_EVAL_CTX_set1_issuer() to provide the issuer certificate
+=item *
+
+CT_POLICY_EVAL_CTX_set1_issuer() to provide the issuer certificate
 
 Increments the reference count of the certificate.
 
-=item * CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE() to provide a list of logs that are trusted as sources of SCTs
+=item *
+
+CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE() to provide a list of logs that are trusted as sources of SCTs
 
 Holds a pointer to the CTLOG_STORE, so the CTLOG_STORE must outlive the
 CT_POLICY_EVAL_CTX.
 
-=item * CT_POLICY_EVAL_CTX_set_time() to provide the current time
+=item *
+
+CT_POLICY_EVAL_CTX_set_time() to set the time SCTs should be compared with to determine if they are valid
 
 The SCT timestamp will be compared to this time to check whether the SCT was
-supposedly issued in the future. RFC6962 states that "TLS clients MUST reject
-SCTs whose timestamp is in the future".
+issued in the future. RFC6962 states that "TLS clients MUST reject SCTs whose
+timestamp is in the future". By default, this will be set to 5 minutes in the
+future (e.g. (time() + 300) * 1000), to allow for clock drift.
+
+The time should be in milliseconds since the Unix Epoch.
 
 =back
 
@@ -86,7 +116,8 @@ found in the TLS SCT extension or OCSP response.
 
 =head1 RETURN VALUES
 
-CT_POLICY_EVAL_CTX_new() will return NULL if malloc fails.
+CT_POLICY_EVAL_CTX_new_with_libctx() and CT_POLICY_EVAL_CTX_new() will return
+NULL if malloc fails.
 
 =head1 SEE ALSO
 
@@ -94,13 +125,14 @@ L<ct(7)>
 
 =head1 HISTORY
 
-These functions were added in OpenSSL 1.1.0.
+CT_POLICY_EVAL_CTX_new_with_libctx was added in OpenSSL 3.0. All other
+functions were added in OpenSSL 1.1.0.
 
 =head1 COPYRIGHT
 
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.
 
-Licensed under the OpenSSL license (the "License").  You may not use
+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>.