doc/man3/SSL_CTX_get0_param.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 SSL_CTX_get0_param, SSL_get0_param, SSL_CTX_set1_param, SSL_set1_param,
   6 SSL_CTX_set_purpose, SSL_CTX_set_trust, SSL_set_purpose, SSL_set_trust -
   7 get and set verification parameters
   8
   9 =head1 SYNOPSIS
  10
  11  #include <openssl/ssl.h>
  12
  13  X509_VERIFY_PARAM *SSL_CTX_get0_param(SSL_CTX *ctx);
  14  X509_VERIFY_PARAM *SSL_get0_param(SSL *ssl);
  15  int SSL_CTX_set1_param(SSL_CTX *ctx, X509_VERIFY_PARAM *vpm);
  16  int SSL_set1_param(SSL *ssl, X509_VERIFY_PARAM *vpm);
  17
  18  int SSL_CTX_set_purpose(SSL_CTX *ctx, int purpose);
  19  int SSL_set_purpose(SSL *ssl, int purpose);
  20
  21  int SSL_CTX_set_trust(SSL_CTX *ctx, int trust);
  22  int SSL_set_trust(SSL *ssl, int trust);
  23
  24 =head1 DESCRIPTION
  25
  26 SSL_CTX_get0_param() and SSL_get0_param() retrieve an internal pointer to
  27 the verification parameters for B<ctx> or B<ssl> respectively. The returned
  28 pointer must not be freed by the calling application.
  29
  30 SSL_CTX_set1_param() and SSL_set1_param() set the verification parameters
  31 to B<vpm> for B<ctx> or B<ssl>.
  32
  33 The functions SSL_CTX_set_purpose() and SSL_set_purpose() are shorthands which
  34 set the purpose parameter on the verification parameters object. These functions
  35 are equivalent to calling X509_VERIFY_PARAM_set_purpose() directly.
  36
  37 The functions SSL_CTX_set_trust() and SSL_set_trust() are similarly shorthands
  38 which set the trust parameter on the verification parameters object. These
  39 functions are equivalent to calling X509_VERIFY_PARAM_set_trust() directly.
  40
  41 =head1 NOTES
  42
  43 Typically parameters are retrieved from an B<SSL_CTX> or B<SSL> structure
  44 using SSL_CTX_get0_param() or SSL_get0_param() and an application modifies
  45 them to suit its needs: for example to add a hostname check.
  46
  47 =head1 RETURN VALUES
  48
  49 SSL_CTX_get0_param() and SSL_get0_param() return a pointer to an
  50 B<X509_VERIFY_PARAM> structure.
  51
  52 SSL_CTX_set1_param(), SSL_set1_param(), SSL_CTX_set_purpose(),
  53 SSL_set_purpose(), SSL_CTX_set_trust() and SSL_set_trust() return 1 for success
  54 and 0 for failure.
  55
  56 =head1 EXAMPLES
  57
  58 Check hostname matches "www.foo.com" in peer certificate:
  59
  60  X509_VERIFY_PARAM *vpm = SSL_get0_param(ssl);
  61  X509_VERIFY_PARAM_set1_host(vpm, "www.foo.com", 0);
  62
  63 =head1 SEE ALSO
  64
  65 L<ssl(7)>,
  66 L<X509_VERIFY_PARAM_set_flags(3)>
  67
  68 =head1 HISTORY
  69
  70 These functions were added in OpenSSL 1.0.2.
  71
  72 =head1 COPYRIGHT
  73
  74 Copyright 2015-2022 The OpenSSL Project Authors. All Rights Reserved.
  75
  76 Licensed under the Apache License 2.0 (the "License").  You may not use
  77 this file except in compliance with the License.  You can obtain a copy
  78 in the file LICENSE in the source distribution or at
  79 L<https://www.openssl.org/source/license.html>.
  80
  81 =cut