doc/man3/X509_verify_cert.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 X509_verify_cert,
   6 X509_STORE_CTX_verify - discover and verify X509 certificate chain
   7
   8 =head1 SYNOPSIS
   9
  10  #include <openssl/x509_vfy.h>
  11
  12  int X509_verify_cert(X509_STORE_CTX *ctx);
  13  int X509_STORE_CTX_verify(X509_STORE_CTX *ctx);
  14
  15 =head1 DESCRIPTION
  16
  17 The X509_verify_cert() function attempts to discover and validate a
  18 certificate chain based on parameters in I<ctx>.
  19 The verification context, of type B<X509_STORE_CTX>, can be constructed
  20 using L<X509_STORE_CTX_new(3)> and L<X509_STORE_CTX_init(3)>.
  21 It usually includes a target certificate to be verified,
  22 a set of certificates serving as trust anchors,
  23 a list of non-trusted certificates that may be helpful for chain construction,
  24 flags such as X509_V_FLAG_X509_STRICT, and various other optional components
  25 such as a callback function that allows customizing the verification outcome.
  26 A complete description of the certificate verification process is contained in
  27 the L<openssl-verification-options(1)> manual page.
  28
  29 Applications rarely call this function directly but it is used by
  30 OpenSSL internally for certificate validation, in both the S/MIME and
  31 SSL/TLS code.
  32
  33 A negative return value from X509_verify_cert() can occur if it is invoked
  34 incorrectly, such as with no certificate set in I<ctx>, or when it is called
  35 twice in succession without reinitialising I<ctx> for the second call.
  36 A negative return value can also happen due to internal resource problems or if
  37 a retry operation is requested during internal lookups (which never happens
  38 with standard lookup methods).
  39 Applications must check for <= 0 return value on error.
  40
  41 The X509_STORE_CTX_verify() behaves like X509_verify_cert() except that its
  42 target certificate is the first element of the list of untrusted certificates
  43 in I<ctx> unless a target certificate is set explicitly.
  44
  45 =head1 RETURN VALUES
  46
  47 Both functions return 1 if a complete chain can be built and validated,
  48 otherwise they return 0, and in exceptional circumstances (such as malloc
  49 failure and internal errors) they can also return a negative code.
  50
  51 On error or failure additional error information can be obtained by
  52 examining I<ctx> using, for example, L<X509_STORE_CTX_get_error(3)>.  Even if
  53 verification indicated success, the stored error code may be different from
  54 X509_V_OK, likely because a verification callback function has waived the error.
  55
  56 =head1 SEE ALSO
  57
  58 L<X509_STORE_CTX_new(3)>, L<X509_STORE_CTX_init(3)>,
  59 L<X509_STORE_CTX_get_error(3)>
  60
  61 =head1 HISTORY
  62
  63 X509_STORE_CTX_verify() was added in OpenSSL 3.0.
  64
  65 =head1 COPYRIGHT
  66
  67 Copyright 2009-2021 The OpenSSL Project Authors. All Rights Reserved.
  68
  69 Licensed under the Apache License 2.0 (the "License").  You may not use
  70 this file except in compliance with the License.  You can obtain a copy
  71 in the file LICENSE in the source distribution or at
  72 L<https://www.openssl.org/source/license.html>.
  73
  74 =cut