.\"	$NetBSD: SSL_get_shared_sigalgs.3,v 1.6 2023/05/31 19:42:44 christos Exp $
.\"
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "SSL_get_shared_sigalgs 3"
.TH SSL_get_shared_sigalgs 3 "2023-05-07" "3.0.9" "OpenSSL"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
SSL_get_shared_sigalgs, SSL_get_sigalgs \- get supported signature algorithms
.SH "LIBRARY"
libcrypto, -lcrypto
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/ssl.h>
\&
\& int SSL_get_shared_sigalgs(SSL *s, int idx,
\&                            int *psign, int *phash, int *psignhash,
\&                            unsigned char *rsig, unsigned char *rhash);
\&
\& int SSL_get_sigalgs(SSL *s, int idx,
\&                     int *psign, int *phash, int *psignhash,
\&                     unsigned char *rsig, unsigned char *rhash);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBSSL_get_shared_sigalgs()\fR returns information about the shared signature
algorithms supported by peer \fBs\fR. The parameter \fBidx\fR indicates the index
of the shared signature algorithm to return starting from zero. The signature
algorithm \s-1NID\s0 is written to \fB*psign\fR, the hash \s-1NID\s0 to \fB*phash\fR and the
sign and hash \s-1NID\s0 to \fB*psignhash\fR. The raw signature and hash values
are written to \fB*rsig\fR and \fB*rhash\fR.
.PP
\&\fBSSL_get_sigalgs()\fR is similar to \fBSSL_get_shared_sigalgs()\fR except it returns
information about all signature algorithms supported by \fBs\fR in the order
they were sent by the peer.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBSSL_get_shared_sigalgs()\fR and \fBSSL_get_sigalgs()\fR return the number of
signature algorithms or \fB0\fR if the \fBidx\fR parameter is out of range.
.SH "NOTES"
.IX Header "NOTES"
These functions are typically called for debugging purposes (to report
the peer's preferences) or where an application wants finer control over
certificate selection. Most applications will rely on internal handling
and will not need to call them.
.PP
If an application is only interested in the highest preference shared
signature algorithm it can just set \fBidx\fR to zero.
.PP
Any or all of the parameters \fBpsign\fR, \fBphash\fR, \fBpsignhash\fR, \fBrsig\fR or
\&\fBrhash\fR can be set to \fB\s-1NULL\s0\fR if the value is not required. By setting
them all to \fB\s-1NULL\s0\fR and setting \fBidx\fR to zero the total number of
signature algorithms can be determined: which can be zero.
.PP
These functions must be called after the peer has sent a list of supported
signature algorithms: after a client hello (for servers) or a certificate
request (for clients). They can (for example) be called in the certificate
callback.
.PP
Only \s-1TLS 1.2, TLS 1.3\s0 and \s-1DTLS 1.2\s0 currently support signature algorithms.
If these
functions are called on an earlier version of \s-1TLS\s0 or \s-1DTLS\s0 zero is returned.
.PP
The shared signature algorithms returned by \fBSSL_get_shared_sigalgs()\fR are
ordered according to configuration and peer preferences.
.PP
The raw values correspond to the on the wire form as defined by \s-1RFC5246\s0 et al.
The NIDs are OpenSSL equivalents. For example if the peer sent \fBsha256\fR\|(4) and
\&\fBrsa\fR\|(1) then \fB*rhash\fR would be 4, \fB*rsign\fR 1, \fB*phash\fR NID_sha256, \fB*psig\fR
NID_rsaEncryption and \fB*psighash\fR NID_sha256WithRSAEncryption.
.PP
If a signature algorithm is not recognised the corresponding NIDs
will be set to \fBNID_undef\fR. This may be because the value is not supported,
is not an appropriate combination (for example \s-1MD5\s0 and \s-1DSA\s0) or the
signature algorithm does not use a hash (for example Ed25519).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBSSL_CTX_set_cert_cb\fR\|(3),
\&\fBssl\fR\|(7)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2015\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (the \*(L"License\*(R").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.