Commit a593cffe authored by Dr. Stephen Henson's avatar Dr. Stephen Henson
Browse files

Update documentation 



Add details of the use of PSS for signature algorithms.

Document SSL_get_peer_signature_nid() and SSL_get_peer_signature_type_nid().

Reviewed-by: default avatarRichard Levitte <levitte@openssl.org>
Reviewed-by: default avatarMatt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/2301)
parent 377c5e98

doc/man3/SSL_CTX_set1_sigalgs.pod

+5 −2
Original line number Diff line number Diff line
@@ -70,11 +70,14 @@ prohibits them (for example SHA1 if the security level is 4 or more). 


Currently the NID_md5, NID_sha1, NID_sha224, NID_sha256, NID_sha384 and

NID_sha512 digest NIDs are supported and the public key algorithm NIDs

EVP_PKEY_RSA, EVP_PKEY_DSA and EVP_PKEY_EC.

EVP_PKEY_RSA, EVP_PKEY_RSA_PSS, EVP_PKEY_DSA and EVP_PKEY_EC.



The short or long name values for digests can be used in a string (for

example "MD5", "SHA1", "SHA224", "SHA256", "SHA384", "SHA512") and

the public key algorithm strings "RSA", "DSA" or "ECDSA".

the public key algorithm strings "RSA", "RSA-PSS", "DSA" or "ECDSA".



The TLS 1.3 signature scheme names (such as "rsa_pss_sha256") can also

be used.



The use of MD5 as a digest is strongly discouraged due to security weaknesses.

doc/man3/SSL_get_peer_signature_nid.pod

0 → 100644
+45 −0
Original line number Diff line number Diff line 
=pod



=head1 NAME



SSL_get_peer_signature_nid, SSL_get_peer_signature_type_nid - get TLS

message signing types



=head1 SYNOPSIS



 #include <openssl/ssl.h>



 int SSL_get_peer_signature_nid(SSL *ssl, int *psig_nid);

 int SSL_get_peer_signature_type_nid(const SSL *ssl, int *psigtype_nid);



=head1 DESCRIPTION



SSL_get_peer_signature_nid() sets B<*psig_nid> to the NID of the digest used

by the peer to sign TLS messages. It is implemented as a macro.



SSL_get_peer_signature_type_nid() sets B<*psigtype_nid> to the signature

type used by the peer to sign TLS messages. Currently the signature type

is the NID of the public key type used for signing except for PSS signing

where it is B<EVP_PKEY_RSA_PSS>.



=head1 RETURN VALUES



These functions return 1 for success and 0 for failure. There are several

possible reasons for failure: the ciphersuite has no signature (e.g. it

uses RSA key exchange or is anonymous), the TLS version is below 1.2 or

the functions were called before the peer signed a message.



=head1 SEE ALSO



L<ssl(7)>, L<SSL_get_peer_certificate(3)>,



=head1 COPYRIGHT



Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.



Licensed under the OpenSSL license (the "License").  You may not use

this file except in compliance with the License.  You can obtain a copy

in the file LICENSE in the source distribution or at

L<https://www.openssl.org/source/license.html>.



=cut