SSL_get_shared_sigalgs.pod 3.3 KB

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