Skip to content

X509_VERIFY_PARAM_set_hostflags

NAME

X509_VERIFY_PARAM_set_hostflags, X509_VERIFY_PARAM_get_hostflags - X509 hostname verification flags

SYNOPSIS

#include <openssl/x509_vfy.h>

void X509_VERIFY_PARAM_set_hostflags(X509_VERIFY_PARAM *param,
                                     unsigned int flags);
unsigned int X509_VERIFY_PARAM_get_hostflags(const X509_VERIFY_PARAM *param);

DESCRIPTION

Host flags control how hostname matching is performed during certificate verification: which wildcard forms are permitted in the certificate's subject alternative name (SAN) entries, and whether the certificate's subject distinguished name is consulted in addition to the SAN.

X509_VERIFY_PARAM_set_hostflags() sets the host flags on param to flags, for use during subsequent calls to X509_verify_cert(3).

X509_VERIFY_PARAM_get_hostflags() returns any host flags previously set via a call to X509_VERIFY_PARAM_set_hostflags().

The flags default to 0. They may be set to a bitwise OR of the following:

  • X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT
  • X509_CHECK_FLAG_NEVER_CHECK_SUBJECT
  • X509_CHECK_FLAG_NO_WILDCARDS
  • X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS
  • X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS
  • X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS

By default the subject distinguished name is not consulted; matching is performed only against the subject alternative name extension.

The X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT flag causes the function to also match against the subject DN (the commonName attribute for DNS names, the emailAddress attribute for email addresses), whether or not the certificate contains a subject alternative name of the corresponding type. During certificate chain verification this flag additionally causes DNS name constraints to be applied to the subject commonName of the leaf certificate, since the commonName may then be used as a DNS identity; see NAME_CONSTRAINTS_check(3).

The X509_CHECK_FLAG_NEVER_CHECK_SUBJECT flag suppresses matching against the subject DN. As that is already the default, this flag has an effect only in combination with X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT, over which it takes precedence.

If set, X509_CHECK_FLAG_NO_WILDCARDS disables wildcard expansion.

If set, X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS suppresses support for "*" as wildcard pattern in labels that have a prefix or suffix, such as: "www*" or "*www".

If set, X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS allows a "*" that constitutes the complete label of a DNS name (e.g. "*.example.com") to match more than one label in the configured reference identifier.

If set, X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS restricts reference identifiers which start with ".", that would otherwise match any sub-domain in the peer certificate, to only match direct child sub-domains. Thus, for instance, with this flag set a reference identifier of ".example.com" would match a peer certificate with a DNS name of "www.example.com", but would not match a peer certificate with a DNS name of "www.sub.example.com".

RETURN VALUES

X509_VERIFY_PARAM_get_hostflags() returns the flag values.

SEE ALSO

X509_verify_cert(3), SSL_get_verify_result(3), X509_VERIFY_PARAM_set1_host(3), X509_VERIFY_PARAM_add1_host(3), X509_VERIFY_PARAM_set1_email(3), X509_VERIFY_PARAM_set1_ip(3)

HISTORY

X509_VERIFY_PARAM_set_hostflags() was added in OpenSSL 1.0.2.

X509_VERIFY_PARAM_get_hostflags() was added in OpenSSL 1.1.0i.

Copyright 2026 The OpenSSL Project Authors. All Rights Reserved.

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 https://www.openssl.org/source/license.html.