doc/man3/X509_verify_cert.pod

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