1*4724848cSchristos=pod 2*4724848cSchristos 3*4724848cSchristos=head1 NAME 4*4724848cSchristos 5*4724848cSchristosSSL_check_chain - check certificate chain suitability 6*4724848cSchristos 7*4724848cSchristos=head1 SYNOPSIS 8*4724848cSchristos 9*4724848cSchristos #include <openssl/ssl.h> 10*4724848cSchristos 11*4724848cSchristos int SSL_check_chain(SSL *s, X509 *x, EVP_PKEY *pk, STACK_OF(X509) *chain); 12*4724848cSchristos 13*4724848cSchristos=head1 DESCRIPTION 14*4724848cSchristos 15*4724848cSchristosSSL_check_chain() checks whether certificate B<x>, private key B<pk> and 16*4724848cSchristoscertificate chain B<chain> is suitable for use with the current session 17*4724848cSchristosB<s>. 18*4724848cSchristos 19*4724848cSchristos=head1 RETURN VALUES 20*4724848cSchristos 21*4724848cSchristosSSL_check_chain() returns a bitmap of flags indicating the validity of the 22*4724848cSchristoschain. 23*4724848cSchristos 24*4724848cSchristosB<CERT_PKEY_VALID>: the chain can be used with the current session. 25*4724848cSchristosIf this flag is B<not> set then the certificate will never be used even 26*4724848cSchristosif the application tries to set it because it is inconsistent with the 27*4724848cSchristospeer preferences. 28*4724848cSchristos 29*4724848cSchristosB<CERT_PKEY_SIGN>: the EE key can be used for signing. 30*4724848cSchristos 31*4724848cSchristosB<CERT_PKEY_EE_SIGNATURE>: the signature algorithm of the EE certificate is 32*4724848cSchristosacceptable. 33*4724848cSchristos 34*4724848cSchristosB<CERT_PKEY_CA_SIGNATURE>: the signature algorithms of all CA certificates 35*4724848cSchristosare acceptable. 36*4724848cSchristos 37*4724848cSchristosB<CERT_PKEY_EE_PARAM>: the parameters of the end entity certificate are 38*4724848cSchristosacceptable (e.g. it is a supported curve). 39*4724848cSchristos 40*4724848cSchristosB<CERT_PKEY_CA_PARAM>: the parameters of all CA certificates are acceptable. 41*4724848cSchristos 42*4724848cSchristosB<CERT_PKEY_EXPLICIT_SIGN>: the end entity certificate algorithm 43*4724848cSchristoscan be used explicitly for signing (i.e. it is mentioned in the signature 44*4724848cSchristosalgorithms extension). 45*4724848cSchristos 46*4724848cSchristosB<CERT_PKEY_ISSUER_NAME>: the issuer name is acceptable. This is only 47*4724848cSchristosmeaningful for client authentication. 48*4724848cSchristos 49*4724848cSchristosB<CERT_PKEY_CERT_TYPE>: the certificate type is acceptable. Only meaningful 50*4724848cSchristosfor client authentication. 51*4724848cSchristos 52*4724848cSchristosB<CERT_PKEY_SUITEB>: chain is suitable for Suite B use. 53*4724848cSchristos 54*4724848cSchristos=head1 NOTES 55*4724848cSchristos 56*4724848cSchristosSSL_check_chain() must be called in servers after a client hello message or in 57*4724848cSchristosclients after a certificate request message. It will typically be called 58*4724848cSchristosin the certificate callback. 59*4724848cSchristos 60*4724848cSchristosAn application wishing to support multiple certificate chains may call this 61*4724848cSchristosfunction on each chain in turn: starting with the one it considers the 62*4724848cSchristosmost secure. It could then use the chain of the first set which returns 63*4724848cSchristossuitable flags. 64*4724848cSchristos 65*4724848cSchristosAs a minimum the flag B<CERT_PKEY_VALID> must be set for a chain to be 66*4724848cSchristosusable. An application supporting multiple chains with different CA signature 67*4724848cSchristosalgorithms may also wish to check B<CERT_PKEY_CA_SIGNATURE> too. If no 68*4724848cSchristoschain is suitable a server should fall back to the most secure chain which 69*4724848cSchristossets B<CERT_PKEY_VALID>. 70*4724848cSchristos 71*4724848cSchristosThe validity of a chain is determined by checking if it matches a supported 72*4724848cSchristossignature algorithm, supported curves and in the case of client authentication 73*4724848cSchristoscertificate types and issuer names. 74*4724848cSchristos 75*4724848cSchristosSince the supported signature algorithms extension is only used in TLS 1.2, 76*4724848cSchristosTLS 1.3 and DTLS 1.2 the results for earlier versions of TLS and DTLS may not 77*4724848cSchristosbe very useful. Applications may wish to specify a different "legacy" chain 78*4724848cSchristosfor earlier versions of TLS or DTLS. 79*4724848cSchristos 80*4724848cSchristos=head1 SEE ALSO 81*4724848cSchristos 82*4724848cSchristosL<SSL_CTX_set_cert_cb(3)>, 83*4724848cSchristosL<ssl(7)> 84*4724848cSchristos 85*4724848cSchristos=head1 COPYRIGHT 86*4724848cSchristos 87*4724848cSchristosCopyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved. 88*4724848cSchristos 89*4724848cSchristosLicensed under the OpenSSL license (the "License"). You may not use 90*4724848cSchristosthis file except in compliance with the License. You can obtain a copy 91*4724848cSchristosin the file LICENSE in the source distribution or at 92*4724848cSchristosL<https://www.openssl.org/source/license.html>. 93*4724848cSchristos 94*4724848cSchristos=cut 95