Debian Codegraph @

upstream/debian-unstable/man3/SSL_get_shared_sigalgs.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "SSL_GET_SHARED_SIGALGS 3SSL"
58 .TH SSL_GET_SHARED_SIGALGS 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 SSL_get_shared_sigalgs, SSL_get_sigalgs \- get supported signature algorithms
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& #include <openssl/ssl.h>
69 \&
70 \& int SSL_get_shared_sigalgs(SSL *s, int idx,
71 \& int *psign, int *phash, int *psignhash,
72 \& unsigned char *rsig, unsigned char *rhash);
73 \&
74 \& int SSL_get_sigalgs(SSL *s, int idx,
75 \& int *psign, int *phash, int *psignhash,
76 \& unsigned char *rsig, unsigned char *rhash);
77 .Ve
78 .SH DESCRIPTION
79 .IX Header "DESCRIPTION"
80 \&\fBSSL_get_shared_sigalgs()\fR returns information about the shared signature
81 algorithms supported by peer \fBs\fR. The parameter \fBidx\fR indicates the index
82 of the shared signature algorithm to return starting from zero. The signature
83 algorithm NID is written to \fB*psign\fR, the hash NID to \fB*phash\fR and the
84 sign and hash NID to \fB*psignhash\fR. The raw signature and hash values
85 are written to \fB*rsig\fR and \fB*rhash\fR.
86 .PP
87 \&\fBSSL_get_sigalgs()\fR is similar to \fBSSL_get_shared_sigalgs()\fR except it returns
88 information about all signature algorithms supported by \fBs\fR in the order
89 they were sent by the peer.
90 .SH "RETURN VALUES"
91 .IX Header "RETURN VALUES"
92 \&\fBSSL_get_shared_sigalgs()\fR and \fBSSL_get_sigalgs()\fR return the number of
93 signature algorithms or \fB0\fR if the \fBidx\fR parameter is out of range.
94 .SH NOTES
95 .IX Header "NOTES"
96 These functions are typically called for debugging purposes (to report
97 the peer's preferences) or where an application wants finer control over
98 certificate selection. Most applications will rely on internal handling
99 and will not need to call them.
100 .PP
101 If an application is only interested in the highest preference shared
102 signature algorithm it can just set \fBidx\fR to zero.
103 .PP
104 Any or all of the parameters \fBpsign\fR, \fBphash\fR, \fBpsignhash\fR, \fBrsig\fR or
105 \&\fBrhash\fR can be set to \fBNULL\fR if the value is not required. By setting
106 them all to \fBNULL\fR and setting \fBidx\fR to zero the total number of
107 signature algorithms can be determined: which can be zero.
108 .PP
109 These functions must be called after the peer has sent a list of supported
110 signature algorithms: after a client hello (for servers) or a certificate
111 request (for clients). They can (for example) be called in the certificate
112 callback.
113 .PP
114 Only TLS 1.2, TLS 1.3 and DTLS 1.2 currently support signature algorithms.
115 If these
116 functions are called on an earlier version of TLS or DTLS zero is returned.
117 .PP
118 The shared signature algorithms returned by \fBSSL_get_shared_sigalgs()\fR are
119 ordered according to configuration and peer preferences.
120 .PP
121 The raw values correspond to the on the wire form as defined by RFC5246 et al.
122 The NIDs are OpenSSL equivalents. For example if the peer sent \fBsha256\fR\|(4) and
123 \&\fBrsa\fR\|(1) then \fB*rhash\fR would be 4, \fB*rsign\fR 1, \fB*phash\fR NID_sha256, \fB*psig\fR
124 NID_rsaEncryption and \fB*psignhash\fR NID_sha256WithRSAEncryption.
125 .PP
126 If a signature algorithm is not recognised the corresponding NIDs
127 will be set to \fBNID_undef\fR. This may be because the value is not supported,
128 is not an appropriate combination (for example MD5 and DSA) or the
129 signature algorithm does not use a hash (for example Ed25519).
130 .SH "SEE ALSO"
131 .IX Header "SEE ALSO"
132 \&\fBSSL_CTX_set_cert_cb\fR\|(3),
133 \&\fBssl\fR\|(7)
134 .SH COPYRIGHT
135 .IX Header "COPYRIGHT"
136 Copyright 2015\-2018 The OpenSSL Project Authors. All Rights Reserved.
137 .PP
138 Licensed under the Apache License 2.0 (the "License"). You may not use
139 this file except in compliance with the License. You can obtain a copy
140 in the file LICENSE in the source distribution or at
141 <https://www.openssl.org/source/license.html>.