.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.48) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Required to disable full justification in groff 1.23.0. .if n .ds AD l .\" ======================================================================== .\" .IX Title "X509_VERIFY_PARAM_SET1_HOST 3ssl" .TH X509_VERIFY_PARAM_SET1_HOST 3ssl 2026-10-23 4.1.0 OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME X509_VERIFY_PARAM_set1_host, X509_VERIFY_PARAM_add1_host, X509_VERIFY_PARAM_get0_host, X509_VERIFY_PARAM_set1_email, X509_VERIFY_PARAM_get0_email, X509_VERIFY_PARAM_set1_rfc822, X509_VERIFY_PARAM_add1_rfc822, X509_VERIFY_PARAM_set1_smtputf8, X509_VERIFY_PARAM_add1_smtputf8, X509_VERIFY_PARAM_set1_ip, X509_VERIFY_PARAM_add1_ip, X509_VERIFY_PARAM_set1_ip_asc, X509_VERIFY_PARAM_add1_ip_asc, X509_VERIFY_PARAM_get1_ip_asc, X509_VERIFY_PARAM_set1_host_input_validation, X509_VERIFY_PARAM_set1_rfc822_input_validation, X509_VERIFY_PARAM_set1_smtputf8_input_validation, X509_VERIFY_PARAM_set1_ip_input_validation \&\- X509 verification reference identifier configuration .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& #include \& \& int X509_VERIFY_PARAM_set1_host(X509_VERIFY_PARAM *param, \& const char *name, size_t namelen); \& int X509_VERIFY_PARAM_add1_host(X509_VERIFY_PARAM *param, \& const char *name, size_t namelen); \& char *X509_VERIFY_PARAM_get0_host(X509_VERIFY_PARAM *param, int idx); \& \& int X509_VERIFY_PARAM_set1_email(X509_VERIFY_PARAM *param, \& const char *email, size_t emaillen); \& char *X509_VERIFY_PARAM_get0_email(X509_VERIFY_PARAM *param); \& int X509_VERIFY_PARAM_set1_rfc822(X509_VERIFY_PARAM *param, \& const char *email, size_t emaillen); \& int X509_VERIFY_PARAM_add1_rfc822(X509_VERIFY_PARAM *param, \& const char *email, size_t emaillen); \& int X509_VERIFY_PARAM_set1_smtputf8(X509_VERIFY_PARAM *param, \& const char *email, size_t emaillen); \& int X509_VERIFY_PARAM_add1_smtputf8(X509_VERIFY_PARAM *param, \& const char *email, size_t emaillen); \& \& int X509_VERIFY_PARAM_set1_ip(X509_VERIFY_PARAM *param, \& const unsigned char *ip, size_t iplen); \& int X509_VERIFY_PARAM_add1_ip(X509_VERIFY_PARAM *param, \& const unsigned char *ip, size_t iplen); \& int X509_VERIFY_PARAM_set1_ip_asc(X509_VERIFY_PARAM *param, \& const char *ip_asc); \& int X509_VERIFY_PARAM_add1_ip_asc(X509_VERIFY_PARAM *param, \& const char *ip_asc); \& char *X509_VERIFY_PARAM_get1_ip_asc(X509_VERIFY_PARAM *param); \& \& void X509_VERIFY_PARAM_set1_host_input_validation(X509_VERIFY_PARAM *param, \& int (*validate_host)(const char *name, size_t len)); \& void X509_VERIFY_PARAM_set1_rfc822_input_validation(X509_VERIFY_PARAM *param, \& int (*validate_rfc822)(const char *name, size_t len)); \& void X509_VERIFY_PARAM_set1_smtputf8_input_validation(X509_VERIFY_PARAM *param, \& int (*validate_smtputf8)(const char *name, size_t len)); \& void X509_VERIFY_PARAM_set1_ip_input_validation(X509_VERIFY_PARAM *param, \& int (*validate_ip)(const uint8_t *name, size_t len)); .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" These functions configure the set of \fBreference identifiers\fR that an \&\fBX509_VERIFY_PARAM\fR will match against the names asserted by a peer\*(Aqs certificate during certificate verification. Four families of reference identifier are supported, each matched against a distinct location in the certificate: .IP \(bu 4 \&\fBDNS hostnames\fR, matched against \fBdNSName\fR entries in the certificate\*(Aqs subject alternative name (SAN) extension. .IP \(bu 4 \&\fBRFC 822 email addresses\fR, matched against \fBrfc822Name\fR entries in the certificate\*(Aqs SAN. .IP \(bu 4 \&\fBSMTPUTF8 email addresses\fR, matched against \fBotherName\fR entries of type \&\fBid\-on\-SmtpUTF8Mailbox\fR (RFC 8398) in the certificate\*(Aqs SAN. .IP \(bu 4 \&\fBIP addresses\fR, matched against \fBiPAddress\fR entries in the certificate\*(Aqs SAN. .PP For each family the \f(CW\*(C`set1_\*(C'\fR form clears any previously configured values and installs the supplied value as the sole reference identifier, and the \&\f(CW\*(C`add1_\*(C'\fR form appends the supplied value to the existing list. When a list contains more than one entry, the certificate is considered to match if any of the configured values matches a corresponding name in the certificate. .PP For the functions whose value is a string with an explicit length (the hostname and email families), if the length argument is zero the value must be NUL\-terminated; otherwise the length argument must be the length of the value in bytes. .SS "Hostname matching" .IX Subsection "Hostname matching" \&\fBX509_VERIFY_PARAM_set1_host()\fR sets in \fIparam\fR the expected DNS hostname to \&\fIname\fR, for matching against \fBdNSName\fR SAN entries in the peer\*(Aqs certificate, clearing any previously specified hostname. If \fIname\fR is NULL or the empty string, the host list is cleared, hostname matching is disabled, and the call succeeds. .PP \&\fBX509_VERIFY_PARAM_add1_host()\fR adds \fIname\fR as an additional reference identifier that can match a \fBdNSName\fR SAN entry in the peer\*(Aqs certificate. Any previous names set via \fBX509_VERIFY_PARAM_set1_host()\fR or \&\fBX509_VERIFY_PARAM_add1_host()\fR are retained. If \fIname\fR is NULL or the empty string, the list is left unchanged and the call succeeds. .PP \&\fBX509_VERIFY_PARAM_get0_host()\fR returns the \fIidx\fRth DNS hostname previously configured on \fIparam\fR via \fBX509_VERIFY_PARAM_set1_host()\fR or \&\fBX509_VERIFY_PARAM_add1_host()\fR, or NULL if \fIidx\fR is out of range. To iterate over the configured hostnames, start with \fIidx\fR = 0 and increment \fIidx\fR until the function returns NULL. The returned string is owned by the library and remains valid until \fIparam\fR is modified or freed; the caller must not free it. .PP Hostname matching is governed by the \fBX509_CHECK_FLAG_*\fR host flags; see \fBX509_VERIFY_PARAM_set_hostflags\fR\|(3) for the available flags and their effect on wildcards and subject\-DN consultation. The names by which the peer matched can be retrieved via \fBX509_VERIFY_PARAM_get0_peername\fR\|(3). .SS "Email matching" .IX Subsection "Email matching" The \f(CW_rfc822()\fR family of functions is used for email names that have ASCII localpart addresses, in which case the domain part of the address must be represented in A\-label form. They are used to specify the list of values to match against the SAN \fBrfc822Name\fR entries in certificates. .PP \&\fBX509_VERIFY_PARAM_set1_rfc822()\fR clears all expected RFC 822 email addresses, and sets the expected RFC 822 email address to \fIemail\fR for matching against \fBrfc822Name\fR SAN entries in the peer\*(Aqs certificate. A NULL \&\fIemail\fR clears the RFC 822 list and returns success; the empty string clears the list but returns failure. .PP \&\fBX509_VERIFY_PARAM_add1_rfc822()\fR adds \fIemail\fR as an additional reference identifier that can match a \fBrfc822Name\fR SAN entry in the peer\*(Aqs certificate. Any previous names set via \fBX509_VERIFY_PARAM_set1_rfc822()\fR, \&\fBX509_VERIFY_PARAM_add1_rfc822()\fR, or \fBX509_VERIFY_PARAM_set1_email()\fR are retained on success; no change is made on failure. \fIemail\fR must not be NULL, and the empty string is rejected as a failure. .PP The \f(CW_smtputf8()\fR family of functions is used for email names that have a non\-ASCII localpart, in which case the domain part of the address must be represented in U\-label form. They are used to specify the list of values to match against the \fBotherName\fR entries of type \&\fBid\-on\-SmtpUTF8Mailbox\fR (RFC 8398) in certificates. .PP \&\fBX509_VERIFY_PARAM_set1_smtputf8()\fR sets the expected SMTPUTF8 email address to \fIemail\fR for matching against \fBotherName\fR SAN entries of type \&\fBid\-on\-SmtpUTF8Mailbox\fR, clearing any previously specified SMTPUTF8 email address. A NULL \fIemail\fR clears the SMTPUTF8 list and returns success; the empty string clears the list but returns failure. .PP \&\fBX509_VERIFY_PARAM_add1_smtputf8()\fR adds \fIemail\fR as an additional reference identifier that can match an \fBotherName\fR SAN entry of type \&\fBid\-on\-SmtpUTF8Mailbox\fR in the peer\*(Aqs certificate. Any previous names set via \fBX509_VERIFY_PARAM_set1_smtputf8()\fR, \fBX509_VERIFY_PARAM_add1_smtputf8()\fR, or \fBX509_VERIFY_PARAM_set1_email()\fR are retained on success; no change is made on failure. \fIemail\fR must not be NULL, and the empty string is rejected as a failure. .PP \&\fBX509_VERIFY_PARAM_set1_email()\fR is a convenience function that calls \&\fBX509_VERIFY_PARAM_set1_rfc822()\fR and \fBX509_VERIFY_PARAM_set1_smtputf8()\fR with the same \fIemail\fR argument and succeeds if either call succeeds. This allows a caller that does not know whether a given email value is ASCII\-localpart or SMTPUTF8 to install it for matching against both \&\fBrfc822Name\fR and \fBotherName\fR id\-on\-SmtpUTF8Mailbox SAN entries. A NULL \&\fIemail\fR clears both lists and returns success. .PP When any email address is configured, certificate verification automatically invokes \fBX509_check_email\fR\|(3). The peer is considered verified when any one of the specified RFC 822 names matches an \&\fBrfc822Name\fR SAN entry, or any one of the specified SMTPUTF8 names matches an \fBotherName\fR id\-on\-SmtpUTF8Mailbox SAN entry, in the certificate. .PP \&\fBX509_VERIFY_PARAM_get0_email()\fR returns a previously configured expected email address from \fIparam\fR, or NULL if neither an RFC 822 nor an SMTPUTF8 address has been set. When both have been configured, the first RFC 822 address is returned in preference to any SMTPUTF8 address. The returned string is owned by the library and remains valid until \fIparam\fR is modified or freed; the caller must not free it. .SS "IP address matching" .IX Subsection "IP address matching" \&\fBX509_VERIFY_PARAM_set1_ip()\fR sets the expected IP address to \fIip\fR for matching against \fBiPAddress\fR SAN entries in the peer\*(Aqs certificate, clearing any previously specified IP address. The \fIip\fR argument must be in binary format, in network byte order, and \fIiplen\fR must be 4 for IPv4 or 16 for IPv6. A NULL \fIip\fR clears the IP list, disables IP matching, and returns success. .PP \&\fBX509_VERIFY_PARAM_add1_ip()\fR adds \fIip\fR as an additional reference identifier that can match an \fBiPAddress\fR SAN entry in the peer\*(Aqs certificate. Any previous addresses set via \fBX509_VERIFY_PARAM_set1_ip()\fR, \&\fBX509_VERIFY_PARAM_add1_ip()\fR, \fBX509_VERIFY_PARAM_set1_ip_asc()\fR, or \&\fBX509_VERIFY_PARAM_add1_ip_asc()\fR are retained on success; no change is made on failure. It is a failure if \fIip\fR is NULL or \fIiplen\fR is neither 4 nor 16. .PP \&\fBX509_VERIFY_PARAM_set1_ip_asc()\fR sets the expected IP address to \fIip_asc\fR for matching against \fBiPAddress\fR SAN entries in the peer\*(Aqs certificate, clearing any previously specified IP address. The \fIip_asc\fR argument must be a NUL\-terminated ASCII string: dotted decimal quad for IPv4 and colon\-separated hexadecimal for IPv6. The condensed "::" notation is supported for IPv6 addresses. A NULL \fIip_asc\fR clears the IP list and returns success; a string that cannot be parsed as an IP address, including the empty string, returns failure and leaves the list unchanged. .PP \&\fBX509_VERIFY_PARAM_add1_ip_asc()\fR adds \fIip_asc\fR as an additional reference identifier that can match an \fBiPAddress\fR SAN entry in the peer\*(Aqs certificate. The format requirements on \fIip_asc\fR are the same as for \&\fBX509_VERIFY_PARAM_set1_ip_asc()\fR. Any previous addresses set via \&\fBX509_VERIFY_PARAM_set1_ip()\fR, \fBX509_VERIFY_PARAM_add1_ip()\fR, \&\fBX509_VERIFY_PARAM_set1_ip_asc()\fR, or \fBX509_VERIFY_PARAM_add1_ip_asc()\fR are retained on success; no change is made on failure. \fIip_asc\fR must not be NULL; a string that cannot be parsed as an IP address, including the empty string, is a failure. .PP When any IP address is configured, certificate verification automatically invokes \fBX509_check_ip\fR\|(3) to match against \fBiPAddress\fR SAN entries. .PP \&\fBX509_VERIFY_PARAM_get1_ip_asc()\fR returns a previously configured expected IP address from \fIparam\fR as a freshly allocated ASCII string (dotted decimal quad for IPv4, colon\-separated hexadecimal for IPv6), or NULL if no IP address has been set. The caller is responsible for freeing the returned string with \fBOPENSSL_free\fR\|(3). .SS "Input validation" .IX Subsection "Input validation" \&\fBX509_VERIFY_PARAM_set1_host_input_validation()\fR, \&\fBX509_VERIFY_PARAM_set1_rfc822_input_validation()\fR, \&\fBX509_VERIFY_PARAM_set1_smtputf8_input_validation()\fR and \&\fBX509_VERIFY_PARAM_set1_ip_input_validation()\fR install a caller\-supplied callback that validates a reference\-identifier value at the point it is configured via the corresponding \f(CW\*(C`set1_\*(C'\fR or \f(CW\*(C`add1_\*(C'\fR function. The callback receives the value and its length, and returns a nonzero value to accept the input or zero to reject it; on rejection the \f(CW\*(C`set1_\*(C'\fR/\f(CW\*(C`add1_\*(C'\fR call fails and no value is stored. .PP These callbacks override OpenSSL\*(Aqs built\-in input validation for the corresponding name type. They affect only the validation performed when reference identifiers are installed on the verification parameters; they do not affect the actual matching performed during certificate verification. .SH "RETURN VALUES" .IX Header "RETURN VALUES" The \f(CW\*(C`set1_\*(C'\fR and \f(CW\*(C`add1_\*(C'\fR functions return 1 for success and 0 for failure. .PP \&\fBX509_VERIFY_PARAM_get0_host()\fR and \fBX509_VERIFY_PARAM_get0_email()\fR return a pointer to a library\-owned string, or NULL if no such configured value exists (\fBX509_VERIFY_PARAM_get0_host()\fR also returns NULL when its index argument is out of range). Callers must not free the returned pointer. .PP \&\fBX509_VERIFY_PARAM_get1_ip_asc()\fR returns a freshly allocated string that the caller must free with \fBOPENSSL_free\fR\|(3), or NULL if no IP address has been configured. .PP The \f(CW\*(C`set1_*_input_validation()\*(C'\fR functions do not return a value. .SH NOTES .IX Header "NOTES" The reference identifier lists configured by these functions are consulted by \fBX509_verify_cert\fR\|(3) when the corresponding \fBX509_check_*\fR checks are performed. Configuring a list for a given name type implicitly enables the corresponding check; clearing it (by passing NULL or the empty string to the \f(CW\*(C`set1_\*(C'\fR form) disables it. .PP By default only the subject alternative name extension is consulted. When \&\fBX509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT\fR is set, the configured hostnames are also matched against the \fBcommonName\fR attribute of the certificate\*(Aqs subject distinguished name, and the configured RFC 822 email addresses against the subject \fBemailAddress\fR attribute. SMTPUTF8 email and IP addresses have no subject distinguished name counterpart and are always matched only against the subject alternative name extension. See \&\fBX509_VERIFY_PARAM_set_hostflags\fR\|(3) and \fBX509_check_host\fR\|(3). .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBX509_verify_cert\fR\|(3), \&\fBX509_VERIFY_PARAM_set_flags\fR\|(3), \&\fBX509_VERIFY_PARAM_set_hostflags\fR\|(3), \&\fBX509_check_host\fR\|(3), \&\fBX509_check_email\fR\|(3), \&\fBX509_check_ip\fR\|(3), \&\fBNAME_CONSTRAINTS_check\fR\|(3), \&\fBSSL_set1_host\fR\|(3), \&\fBSSL_add1_host\fR\|(3) .SH HISTORY .IX Header "HISTORY" \&\fBX509_VERIFY_PARAM_set1_host()\fR, \fBX509_VERIFY_PARAM_add1_host()\fR, \&\fBX509_VERIFY_PARAM_set1_email()\fR, \fBX509_VERIFY_PARAM_set1_ip()\fR, and \&\fBX509_VERIFY_PARAM_set1_ip_asc()\fR were added in OpenSSL 1.0.2. .PP \&\fBX509_VERIFY_PARAM_get0_host()\fR, \fBX509_VERIFY_PARAM_get0_email()\fR, and \&\fBX509_VERIFY_PARAM_get1_ip_asc()\fR were added in OpenSSL 3.0. .PP \&\fBX509_VERIFY_PARAM_add1_ip_asc()\fR was added in OpenSSL 1.1.0. .PP \&\fBX509_VERIFY_PARAM_set1_rfc822()\fR, \fBX509_VERIFY_PARAM_add1_rfc822()\fR, \&\fBX509_VERIFY_PARAM_set1_smtputf8()\fR, \fBX509_VERIFY_PARAM_add1_smtputf8()\fR, \&\fBX509_VERIFY_PARAM_add1_ip()\fR, \&\fBX509_VERIFY_PARAM_set1_host_input_validation()\fR, \&\fBX509_VERIFY_PARAM_set1_rfc822_input_validation()\fR, \&\fBX509_VERIFY_PARAM_set1_smtputf8_input_validation()\fR, and \&\fBX509_VERIFY_PARAM_set1_ip_input_validation()\fR were added in OpenSSL 4.0. .SH COPYRIGHT .IX Header "COPYRIGHT" Copyright 2026 The OpenSSL Project Authors. All Rights Reserved. .PP 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 .