From: Hugo Landau <hlandau@openssl.org>
Date: Mon, 4 Apr 2022 12:45:44 +0000 (+0100)
Subject: Document {SSL|SSL_CTX}_set_{purpose|trust}()
X-Git-Tag: openssl-3.2.0-alpha1~2778
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=eb27a90e41a62d3337c5e21e24ee72f1e49a445c;p=thirdparty%2Fopenssl.git

Document {SSL|SSL_CTX}_set_{purpose|trust}()

Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/18037)
---

diff --git a/doc/man3/SSL_CTX_get0_param.pod b/doc/man3/SSL_CTX_get0_param.pod
index 69855173662..7e2be4a404d 100644
--- a/doc/man3/SSL_CTX_get0_param.pod
+++ b/doc/man3/SSL_CTX_get0_param.pod
@@ -2,7 +2,8 @@
 
 =head1 NAME
 
-SSL_CTX_get0_param, SSL_get0_param, SSL_CTX_set1_param, SSL_set1_param -
+SSL_CTX_get0_param, SSL_get0_param, SSL_CTX_set1_param, SSL_set1_param,
+SSL_CTX_set_purpose, SSL_CTX_set_trust, SSL_set_purpose, SSL_set_trust -
 get and set verification parameters
 
 =head1 SYNOPSIS
@@ -14,6 +15,12 @@ get and set verification parameters
  int SSL_CTX_set1_param(SSL_CTX *ctx, X509_VERIFY_PARAM *vpm);
  int SSL_set1_param(SSL *ssl, X509_VERIFY_PARAM *vpm);
 
+ int SSL_CTX_set_purpose(SSL_CTX *ctx, int purpose);
+ int SSL_set_purpose(SSL *ssl, int purpose);
+
+ int SSL_CTX_set_trust(SSL_CTX *ctx, int trust);
+ int SSL_set_trust(SSL *ssl, int trust);
+
 =head1 DESCRIPTION
 
 SSL_CTX_get0_param() and SSL_get0_param() retrieve an internal pointer to
@@ -23,6 +30,14 @@ pointer must not be freed by the calling application.
 SSL_CTX_set1_param() and SSL_set1_param() set the verification parameters
 to B<vpm> for B<ctx> or B<ssl>.
 
+The functions SSL_CTX_set_purpose() and SSL_set_purpose() are shorthands which
+set the purpose parameter on the verification parameters object. These functions
+are equivalent to calling X509_VERIFY_PARAM_set_purpose() directly.
+
+The functions SSL_CTX_set_trust() and SSL_set_trust() are similarly shorthands
+which set the trust parameter on the verification parameters object. These
+functions are equivalent to calling X509_VERIFY_PARAM_set_trust() directly.
+
 =head1 NOTES
 
 Typically parameters are retrieved from an B<SSL_CTX> or B<SSL> structure
@@ -34,8 +49,9 @@ them to suit its needs: for example to add a hostname check.
 SSL_CTX_get0_param() and SSL_get0_param() return a pointer to an
 B<X509_VERIFY_PARAM> structure.
 
-SSL_CTX_set1_param() and SSL_set1_param() return 1 for success and 0
-for failure.
+SSL_CTX_set1_param(), SSL_set1_param(), SSL_CTX_set_purpose(),
+SSL_set_purpose(), SSL_CTX_set_trust() and SSL_set_trust() return 1 for success
+and 0 for failure.
 
 =head1 EXAMPLES
 
diff --git a/util/missingssl.txt b/util/missingssl.txt
index 8a7e2682033..48219fd99a9 100644
--- a/util/missingssl.txt
+++ b/util/missingssl.txt
@@ -12,8 +12,6 @@ SSL_CTX_get0_privatekey(3)
 SSL_CTX_set0_ctlog_store(3)
 SSL_CTX_set_client_cert_engine(3)
 SSL_CTX_set_not_resumable_session_callback(3)
-SSL_CTX_set_purpose(3)
-SSL_CTX_set_trust(3)
 SSL_SRP_CTX_free(3)
 SSL_SRP_CTX_init(3)
 SSL_add_ssl_module(3)
@@ -28,11 +26,9 @@ SSL_get_peer_finished(3)
 SSL_set_SSL_CTX(3)
 SSL_set_debug(3)
 SSL_set_not_resumable_session_callback(3)
-SSL_set_purpose(3)
 SSL_set_session_secret_cb(3)
 SSL_set_session_ticket_ext(3)
 SSL_set_session_ticket_ext_cb(3)
-SSL_set_trust(3)
 SSL_srp_server_param_with_username(3)
 SSL_test_functions(3)
 SSL_trace(3)