]>
Commit | Line | Data |
---|---|---|
8a00dbd8 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | SSL_get_shared_sigalgs, SSL_get_sigalgs - get supported signature algorithms | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/ssl.h> | |
10 | ||
11 | int SSL_get_shared_sigalgs(SSL *s, int idx, | |
12 | int *psign, int *phash, int *psignhash, | |
13 | unsigned char *rsig, unsigned char *rhash); | |
14 | ||
15 | int SSL_get_sigalgs(SSL *s, int idx, | |
16 | int *psign, int *phash, int *psignhash, | |
17 | unsigned char *rsig, unsigned char *rhash); | |
18 | ||
19 | =head1 DESCRIPTION | |
20 | ||
21 | SSL_get_shared_sigalgs() returns information about the shared signature | |
22 | algorithms supported by peer B<s>. The parameter B<idx> indicates the index | |
23 | of the shared signature algorithm to return starting from zero. The signature | |
24 | algorithm NID is written to B<*psign>, the hash NID to B<*phash> and the | |
25 | sign and hash NID to B<*psignhash>. The raw signature and hash values | |
26 | are written to B<*rsig> and B<*rhash>. | |
27 | ||
28 | SSL_get_sigalgs() is similar to SSL_get_shared_sigalgs() except it returns | |
29 | information about all signature algorithms supported by B<s> in the order | |
30 | they were sent by the peer. | |
31 | ||
32 | =head1 RETURN VALUES | |
33 | ||
34 | SSL_get_shared_sigalgs() and SSL_get_sigalgs() return the number of | |
35 | signature algorithms or B<0> if the B<idx> parameter is out of range. | |
36 | ||
37 | =head1 NOTES | |
38 | ||
39 | These functions are typically called for debugging purposes (to report | |
40 | the peer's preferences) or where an application wants finer control over | |
41 | certificate selection. Most applications will rely on internal handling | |
42 | and will not need to call them. | |
43 | ||
44 | If an application is only interested in the highest preference shared | |
45 | signature algorithm it can just set B<idx> to zero. | |
46 | ||
47 | Any or all of the parameters B<psign>, B<phash>, B<psignhash>, B<rsig> or | |
48 | B<rhash> can be set to B<NULL> if the value is not required. By setting | |
49 | them all to B<NULL> and setting B<idx> to zero the total number of | |
50 | signature algorithms can be determined: which can be zero. | |
51 | ||
52 | These functions must be called after the peer has sent a list of supported | |
53 | signature algorithms: after a client hello (for servers) or a certificate | |
54 | request (for clients). They can (for example) be called in the certificate | |
55 | callback. | |
56 | ||
57 | Only TLS 1.2 and DTLS 1.2 currently support signature algorithms. If these | |
58 | functions are called on an earlier version of TLS or DTLS zero is returned. | |
59 | ||
60 | The shared signature algorithms returned by SSL_get_shared_sigalgs() are | |
61 | ordered according to configuration and peer preferences. | |
62 | ||
63 | The raw values correspond to the on the wire form as defined by RFC5246 et al. | |
64 | The NIDs are OpenSSL equivalents. For example if the peer sent sha256(4) and | |
65 | rsa(1) then B<*rhash> would be 4, B<*rsign> 1, B<*phash> NID_sha256, B<*psig> | |
66 | NID_rsaEncryption and B<*psighash> NID_sha256WithRSAEncryption. | |
67 | ||
24c2cd39 | 68 | If a signature algorithm is not recognised the corresponding NIDs |
8a00dbd8 DSH |
69 | will be set to B<NID_undef>. This may be because the value is not supported |
70 | or is not an appropriate combination (for example MD5 and DSA). | |
71 | ||
72 | =head1 SEE ALSO | |
73 | ||
9b86974e RS |
74 | L<SSL_CTX_set_cert_cb(3)>, |
75 | L<ssl(3)> | |
8a00dbd8 DSH |
76 | |
77 | =cut | |
e2f92610 RS |
78 | |
79 | =head1 COPYRIGHT | |
80 | ||
81 | Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. | |
82 | ||
83 | Licensed under the OpenSSL license (the "License"). You may not use | |
84 | this file except in compliance with the License. You can obtain a copy | |
85 | in the file LICENSE in the source distribution or at | |
86 | L<https://www.openssl.org/source/license.html>. | |
87 | ||
88 | =cut |