SSL_set1_host.pod 4.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119
  1. =pod
  2. =head1 NAME
  3. SSL_set1_host, SSL_add1_host, SSL_set_hostflags, SSL_get0_peername -
  4. SSL server verification parameters
  5. =head1 SYNOPSIS
  6. #include <openssl/ssl.h>
  7. int SSL_set1_host(SSL *s, const char *hostname);
  8. int SSL_add1_host(SSL *s, const char *hostname);
  9. void SSL_set_hostflags(SSL *s, unsigned int flags);
  10. const char *SSL_get0_peername(SSL *s);
  11. =head1 DESCRIPTION
  12. These functions configure server hostname checks in the SSL client.
  13. SSL_set1_host() sets the expected DNS hostname to B<name> clearing
  14. any previously specified hostname. If B<name> is NULL
  15. or the empty string, the list of hostnames is cleared and name
  16. checks are not performed on the peer certificate. When a nonempty
  17. B<name> is specified, certificate verification automatically checks
  18. the peer hostname via L<X509_check_host(3)> with B<flags> as specified
  19. via SSL_set_hostflags(). Clients that enable DANE TLSA authentication
  20. via L<SSL_dane_enable(3)> should leave it to that function to set
  21. the primary reference identifier of the peer, and should not call
  22. SSL_set1_host().
  23. SSL_add1_host() adds B<name> as an additional reference identifier
  24. that can match the peer's certificate. Any previous names set via
  25. SSL_set1_host() or SSL_add1_host() are retained, no change is made
  26. if B<name> is NULL or empty. When multiple names are configured,
  27. the peer is considered verified when any name matches. This function
  28. is required for DANE TLSA in the presence of service name indirection
  29. via CNAME, MX or SRV records as specified in RFC7671, RFC7672 or
  30. RFC7673.
  31. SSL_set_hostflags() sets the B<flags> that will be passed to
  32. L<X509_check_host(3)> when name checks are applicable, by default
  33. the B<flags> value is 0. See L<X509_check_host(3)> for the list
  34. of available flags and their meaning.
  35. SSL_get0_peername() returns the DNS hostname or subject CommonName
  36. from the peer certificate that matched one of the reference
  37. identifiers. When wildcard matching is not disabled, the name
  38. matched in the peer certificate may be a wildcard name. When one
  39. of the reference identifiers configured via SSL_set1_host() or
  40. SSL_add1_host() starts with ".", which indicates a parent domain prefix
  41. rather than a fixed name, the matched peer name may be a sub-domain
  42. of the reference identifier. The returned string is allocated by
  43. the library and is no longer valid once the associated B<ssl> handle
  44. is cleared or freed, or a renegotiation takes place. Applications
  45. must not free the return value.
  46. SSL clients are advised to use these functions in preference to
  47. explicitly calling L<X509_check_host(3)>. Hostname checks may be out
  48. of scope with the RFC7671 DANE-EE(3) certificate usage, and the
  49. internal check will be suppressed as appropriate when DANE is
  50. enabled.
  51. =head1 RETURN VALUES
  52. SSL_set1_host() and SSL_add1_host() return 1 for success and 0 for
  53. failure.
  54. SSL_get0_peername() returns NULL if peername verification is not
  55. applicable (as with RFC7671 DANE-EE(3)), or no trusted peername was
  56. matched. Otherwise, it returns the matched peername. To determine
  57. whether verification succeeded call L<SSL_get_verify_result(3)>.
  58. =head1 EXAMPLES
  59. Suppose "smtp.example.com" is the MX host of the domain "example.com".
  60. The calls below will arrange to match either the MX hostname or the
  61. destination domain name in the SMTP server certificate. Wildcards
  62. are supported, but must match the entire label. The actual name
  63. matched in the certificate (which might be a wildcard) is retrieved,
  64. and must be copied by the application if it is to be retained beyond
  65. the lifetime of the SSL connection.
  66. SSL_set_hostflags(ssl, X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS);
  67. if (!SSL_set1_host(ssl, "smtp.example.com"))
  68. /* error */
  69. if (!SSL_add1_host(ssl, "example.com"))
  70. /* error */
  71. /* XXX: Perform SSL_connect() handshake and handle errors here */
  72. if (SSL_get_verify_result(ssl) == X509_V_OK) {
  73. const char *peername = SSL_get0_peername(ssl);
  74. if (peername != NULL)
  75. /* Name checks were in scope and matched the peername */
  76. }
  77. =head1 SEE ALSO
  78. L<ssl(7)>,
  79. L<X509_check_host(3)>,
  80. L<SSL_get_verify_result(3)>.
  81. L<SSL_dane_enable(3)>.
  82. =head1 HISTORY
  83. These functions were added in OpenSSL 1.1.0.
  84. =head1 COPYRIGHT
  85. Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.
  86. Licensed under the Apache License 2.0 (the "License"). You may not use
  87. this file except in compliance with the License. You can obtain a copy
  88. in the file LICENSE in the source distribution or at
  89. L<https://www.openssl.org/source/license.html>.
  90. =cut