]>
Commit | Line | Data |
---|---|---|
6d5f8265 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | SSL_check_chain - check certificate chain suitability | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/ssl.h> | |
10 | ||
11 | int SSL_check_chain(SSL *s, X509 *x, EVP_PKEY *pk, STACK_OF(X509) *chain); | |
12 | ||
13 | =head1 DESCRIPTION | |
14 | ||
15 | SSL_check_chain() checks whether certificate B<x>, private key B<pk> and | |
16 | certificate chain B<chain> is suitable for use with the current session | |
17 | B<s>. | |
18 | ||
19 | =head1 RETURN VALUES | |
20 | ||
21 | SSL_check_chain() returns a bitmap of flags indicating the validity of the | |
22 | chain. | |
23 | ||
24 | B<CERT_PKEY_VALID>: the chain can be used with the current session. | |
25 | If this flag is B<not> set then the certificate will never be used even | |
26 | if the application tries to set it because it is inconsistent with the | |
27 | peer preferences. | |
28 | ||
29 | B<CERT_PKEY_SIGN>: the EE key can be used for signing. | |
30 | ||
31 | B<CERT_PKEY_EE_SIGNATURE>: the signature algorithm of the EE certificate is | |
32 | acceptable. | |
33 | ||
34 | B<CERT_PKEY_CA_SIGNATURE>: the signature algorithms of all CA certificates | |
35 | are acceptable. | |
36 | ||
37 | B<CERT_PKEY_EE_PARAM>: the parameters of the end entity certificate are | |
38 | acceptable (e.g. it is a supported curve). | |
39 | ||
40 | B<CERT_PKEY_CA_PARAM>: the parameters of all CA certificates are acceptable. | |
41 | ||
42 | B<CERT_PKEY_EXPLICIT_SIGN>: the end entity certificate algorithm | |
43 | can be used explicitly for signing (i.e. it is mentioned in the signature | |
44 | algorithms extension). | |
45 | ||
46 | B<CERT_PKEY_ISSUER_NAME>: the issuer name is acceptable. This is only | |
47 | meaningful for client authentication. | |
48 | ||
49 | B<CERT_PKEY_CERT_TYPE>: the certificate type is acceptable. Only meaningful | |
50 | for client authentication. | |
51 | ||
52 | B<CERT_PKEY_SUITEB>: chain is suitable for Suite B use. | |
53 | ||
54 | =head1 NOTES | |
55 | ||
56 | SSL_check_chain() must be called in servers after a client hello message or in | |
57 | clients after a certificate request message. It will typically be called | |
58 | in the certificate callback. | |
59 | ||
60 | An application wishing to support multiple certificate chains may call this | |
61 | function on each chain in turn: starting with the one it considers the | |
62 | most secure. It could then use the chain of the first set which returns | |
63 | suitable flags. | |
64 | ||
65 | As a minimum the flag B<CERT_PKEY_VALID> must be set for a chain to be | |
66 | usable. An application supporting multiple chains with different CA signature | |
67 | algorithms may also wish to check B<CERT_PKEY_CA_SIGNATURE> too. If no | |
68 | chain is suitable a server should fall back to the most secure chain which | |
69 | sets B<CERT_PKEY_VALID>. | |
70 | ||
71 | The validity of a chain is determined by checking if it matches a supported | |
72 | signature algorithm, supported curves and in the case of client authentication | |
73 | certificate types and issuer names. | |
74 | ||
75 | Since the supported signature algorithms extension is only used in TLS 1.2 | |
76 | and DTLS 1.2 the results for earlier versions of TLS and DTLS may not be | |
77 | very useful. Applications may wish to specify a different "legacy" chain | |
78 | for earlier versions of TLS or DTLS. | |
79 | ||
80 | =head1 SEE ALSO | |
81 | ||
9b86974e RS |
82 | L<SSL_CTX_set_cert_cb(3)>, |
83 | L<ssl(3)> | |
6d5f8265 DSH |
84 | |
85 | =cut |