1=pod 2 3=head1 NAME 4 5X509_build_chain, 6X509_verify_cert, 7X509_STORE_CTX_verify - build and verify X509 certificate chain 8 9=head1 SYNOPSIS 10 11 #include <openssl/x509_vfy.h> 12 13 STACK_OF(X509) *X509_build_chain(X509 *target, STACK_OF(X509) *certs, 14 X509_STORE *store, int with_self_signed, 15 OSSL_LIB_CTX *libctx, const char *propq); 16 int X509_verify_cert(X509_STORE_CTX *ctx); 17 int X509_STORE_CTX_verify(X509_STORE_CTX *ctx); 18 19=head1 DESCRIPTION 20 21X509_build_chain() builds a certificate chain starting from I<target> 22using the optional list of intermediate CA certificates I<certs>. 23If I<store> is NULL it builds the chain as far down as possible, ignoring errors. 24Else the chain must reach a trust anchor contained in I<store>. 25It internally uses a B<X509_STORE_CTX> structure associated with the library 26context I<libctx> and property query string I<propq>, both of which may be NULL. 27In case there is more than one possibility for the chain, only one is taken. 28 29On success it returns a pointer to a new stack of (up_ref'ed) certificates 30starting with I<target> and followed by all available intermediate certificates. 31A self-signed trust anchor is included only if I<target> is the trust anchor 32of I<with_self_signed> is 1. 33If a non-NULL stack is returned the caller is responsible for freeing it. 34 35The X509_verify_cert() function attempts to discover and validate a 36certificate chain based on parameters in I<ctx>. 37The verification context, of type B<X509_STORE_CTX>, can be constructed 38using L<X509_STORE_CTX_new(3)> and L<X509_STORE_CTX_init(3)>. 39It usually includes a target certificate to be verified, 40a set of certificates serving as trust anchors, 41a list of non-trusted certificates that may be helpful for chain construction, 42flags such as X509_V_FLAG_X509_STRICT, and various other optional components 43such as a callback function that allows customizing the verification outcome. 44A complete description of the certificate verification process is contained in 45the L<openssl-verification-options(1)> manual page. 46 47Applications rarely call this function directly but it is used by 48OpenSSL internally for certificate validation, in both the S/MIME and 49SSL/TLS code. 50 51A negative return value from X509_verify_cert() can occur if it is invoked 52incorrectly, such as with no certificate set in I<ctx>, or when it is called 53twice in succession without reinitialising I<ctx> for the second call. 54A negative return value can also happen due to internal resource problems 55or because an internal inconsistency has been detected. 56Applications must interpret any return value <= 0 as an error. 57 58The X509_STORE_CTX_verify() behaves like X509_verify_cert() except that its 59target certificate is the first element of the list of untrusted certificates 60in I<ctx> unless a target certificate is set explicitly. 61 62When the verification target is a raw public key, rather than a certificate, 63both functions validate the target raw public key. 64In that case the number of possible checks is significantly reduced. 65The raw public key can be authenticated only via DANE TLSA records, either 66locally synthesised or obtained by the application from DNS. 67Raw public key DANE TLSA records may be added via L<SSL_add_expected_rpk(3)> or 68L<SSL_dane_tlsa_add(3)>. 69 70=head1 RETURN VALUES 71 72X509_build_chain() returns NULL on error, else a stack of certificates. 73 74Both X509_verify_cert() and X509_STORE_CTX_verify() 75return 1 if a complete chain can be built and validated, 76otherwise they return 0, and in exceptional circumstances (such as malloc 77failure and internal errors) they can also return a negative code. 78 79If a complete chain can be built and validated both functions return 1. 80If the certificate must be rejected on the basis of the data available 81or any required certificate status data is not available they return 0. 82If no definite answer possible they usually return a negative code. 83 84On error or failure additional error information can be obtained by 85examining I<ctx> using, for example, L<X509_STORE_CTX_get_error(3)>. Even if 86verification indicated success, the stored error code may be different from 87X509_V_OK, likely because a verification callback function has waived the error. 88 89=head1 SEE ALSO 90 91L<SSL_add_expected_rpk(3)>, 92L<SSL_CTX_dane_enable(3)>, 93L<SSL_dane_tlsa_add(3)>, 94L<X509_STORE_CTX_new(3)>, 95L<X509_STORE_CTX_init(3)>, 96L<X509_STORE_CTX_init_rpk(3)>, 97L<X509_STORE_CTX_get_error(3)> 98 99=head1 HISTORY 100 101X509_build_chain() and X509_STORE_CTX_verify() were added in OpenSSL 3.0. 102 103=head1 COPYRIGHT 104 105Copyright 2009-2023 The OpenSSL Project Authors. All Rights Reserved. 106 107Licensed under the Apache License 2.0 (the "License"). You may not use 108this file except in compliance with the License. You can obtain a copy 109in the file LICENSE in the source distribution or at 110L<https://www.openssl.org/source/license.html>. 111 112=cut 113
