Document SSL_CIPHER_get_handshake_digest()

Reviewed-by: Rich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3670)

diff --git a/doc/man3/SSL_CIPHER_get_name.pod b/doc/man3/SSL_CIPHER_get_name.pod
index e19bf2132ee0bd35a5cb28c0aae34d63a9e13c10..157c162c85e7d0c85fbe63f5494d5e03eadf2aae 100644 (file)
--- a/doc/man3/SSL_CIPHER_get_name.pod
+++ b/doc/man3/SSL_CIPHER_get_name.pod
@@ -2,10 +2,16 @@
 
 =head1 NAME
 
 
 =head1 NAME
 

-SSL_CIPHER_get_cipher_nid, SSL_CIPHER_get_digest_nid, SSL_CIPHER_get_kx_nid,
-SSL_CIPHER_get_auth_nid, SSL_CIPHER_is_aead,
-SSL_CIPHER_get_name, SSL_CIPHER_get_bits,
-SSL_CIPHER_get_version, SSL_CIPHER_description
+SSL_CIPHER_get_name,
+SSL_CIPHER_get_bits,
+SSL_CIPHER_get_version,
+SSL_CIPHER_description,
+SSL_CIPHER_get_cipher_nid,
+SSL_CIPHER_get_digest_nid,
+SSL_CIPHER_get_handshake_digest,
+SSL_CIPHER_get_kx_nid,
+SSL_CIPHER_get_auth_nid,
+SSL_CIPHER_is_aead

 - get SSL_CIPHER properties
 
 =head1 SYNOPSIS
 - get SSL_CIPHER properties
 
 =head1 SYNOPSIS


@@ -18,6 +24,7 @@ SSL_CIPHER_get_version, SSL_CIPHER_description
  char *SSL_CIPHER_description(const SSL_CIPHER *cipher, char *buf, int size);
  int SSL_CIPHER_get_cipher_nid(const SSL_CIPHER *c);
  int SSL_CIPHER_get_digest_nid(const SSL_CIPHER *c);
  char *SSL_CIPHER_description(const SSL_CIPHER *cipher, char *buf, int size);
  int SSL_CIPHER_get_cipher_nid(const SSL_CIPHER *c);
  int SSL_CIPHER_get_digest_nid(const SSL_CIPHER *c);

+ const EVP_MD *SSL_CIPHER_get_handshake_digest(const SSL_CIPHER *c);

  int SSL_CIPHER_get_kx_nid(const SSL_CIPHER *c);
  int SSL_CIPHER_get_auth_nid(const SSL_CIPHER *c);
  int SSL_CIPHER_is_aead(const SSL_CIPHER *c);
  int SSL_CIPHER_get_kx_nid(const SSL_CIPHER *c);
  int SSL_CIPHER_get_auth_nid(const SSL_CIPHER *c);
  int SSL_CIPHER_is_aead(const SSL_CIPHER *c);


@@ -38,8 +45,12 @@ If there is no cipher (e.g. for cipher suites with no encryption) then
 B<NID_undef> is returned.
 
 SSL_CIPHER_get_digest_nid() returns the digest NID corresponding to the MAC
 B<NID_undef> is returned.
 
 SSL_CIPHER_get_digest_nid() returns the digest NID corresponding to the MAC

-used by B<c>. If there is no digest (e.g. for AEAD cipher suites) then
-B<NID_undef> is returned.
+used by B<c> during record encryption/decryption. If there is no digest (e.g.
+for AEAD cipher suites) then B<NID_undef> is returned.
+
+SSL_CIPHER_get_handshake_digest() returns an EVP_MD for the digest used during
+the SSL/TLS handshake when using the SSL_CIPHER B<c>. Note that this may be
+different to the digest used to calculate the MAC for encrypted records.

 
 SSL_CIPHER_get_kx_nid() returns the key exchange NID corresponding to the method
 used by B<c>. If there is no key exchange, then B<NID_undef> is returned.
 
 SSL_CIPHER_get_kx_nid() returns the key exchange NID corresponding to the method
 used by B<c>. If there is no key exchange, then B<NID_undef> is returned.


@@ -109,10 +120,12 @@ Some examples for the output of SSL_CIPHER_description():
 =head1 HISTORY
 
 SSL_CIPHER_get_version() was updated to always return the correct protocol
 =head1 HISTORY
 
 SSL_CIPHER_get_version() was updated to always return the correct protocol

-string in OpenSSL 1.1.
+string in OpenSSL 1.1.0.

 
 SSL_CIPHER_description() was changed to return B<NULL> on error,
 
 SSL_CIPHER_description() was changed to return B<NULL> on error,

-rather than a fixed string, in OpenSSL 1.1
+rather than a fixed string, in OpenSSL 1.1.0.
+
+SSL_CIPHER_get_handshake_digest() was added in OpenSSL 1.1.1.

 
 =head1 SEE ALSO
 
 
 =head1 SEE ALSO
 


@@ -121,7 +134,7 @@ L<SSL_get_ciphers(3)>, L<ciphers(1)>
 
 =head1 COPYRIGHT
 
 
 =head1 COPYRIGHT
 

-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-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
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy