doc: document EVP_PKEY_get_security_category function

Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
(Merged from https://github.com/openssl/openssl/pull/27571)

diff --git a/doc/man3/EVP_PKEY_get_size.pod b/doc/man3/EVP_PKEY_get_size.pod
index 44b91cb00eb542d43165395729769ad78558270d..4da9063aaa71d0c88086f57a51223f0e2233958e 100644 (file)
--- a/doc/man3/EVP_PKEY_get_size.pod
+++ b/doc/man3/EVP_PKEY_get_size.pod
@@ -3,7 +3,8 @@
 =head1 NAME
 
 EVP_PKEY_get_size, EVP_PKEY_get_bits, EVP_PKEY_get_security_bits,
-EVP_PKEY_bits, EVP_PKEY_security_bits, EVP_PKEY_size
+EVP_PKEY_bits, EVP_PKEY_security_bits, EVP_PKEY_get_security_category,
+EVP_PKEY_size
 - EVP_PKEY information functions
 
 =head1 SYNOPSIS
@@ -13,6 +14,7 @@ EVP_PKEY_bits, EVP_PKEY_security_bits, EVP_PKEY_size
  int EVP_PKEY_get_size(const EVP_PKEY *pkey);
  int EVP_PKEY_get_bits(const EVP_PKEY *pkey);
  int EVP_PKEY_get_security_bits(const EVP_PKEY *pkey);
+ int EVP_PKEY_get_security_category(const EVP_PKEY *pkey);
 
  #define EVP_PKEY_bits EVP_PKEY_get_bits
  #define EVP_PKEY_security_bits EVP_PKEY_get_security_bits
@@ -45,11 +47,52 @@ EVP_PKEY_get_security_bits() returns the number of security bits of the given
 I<pkey>, bits of security is defined in NIST SP800-57.
 This corresponds to the provider parameter B<OSSL_PKEY_PARAM_SECURITY_BITS>.
 
+EVP_PKEY_get_security_category() returns the
+L<post-quantum security category|https://nvlpubs.nist.gov/nistpubs/ir/2024/NIST.IR.8547.ipd.pdf>
+as defined by NIST.
+The post-quantum security category is an integer value from 0 to 5 that
+is based on an algorithm's classification on the range of security strengths
+offered by the existing standards in symmetric cryptography:
+
+=begin text
+
+ Security       Attack
+ Category       Type
+ ==============================================================
+    0           Weak
+    1           Key search on a block cipher with a 128-bit key
+    2           Collision search on a 256-bit hash function
+    3           Key search on a block cipher with a 192-bit key
+    4           Collision search on a 384-bit hash function
+    5           Key search on a block cipher with a 256-bit key
+
+=end text
+
+=begin html
+
+<table>
+<tr><th>Security Category</th><th>Attack Type</th>></tr>
+<tr><td>0</td><td>Weak</td></tr>
+<tr><td>1</td><td>Key search on a block cipher with a 128-bit key</td></tr>
+<tr><td>2</td><td>Collision search on a 256-bit hash function</td></tr>
+<tr><td>3</td><td>Key search on a block cipher with a 192-bit key</td></tr>
+<tr><td>4</td><td>Collision search on a 384-bit hash function</td></tr>
+<tr><td>5</td><td>Key search on a block cipher with a 256-bit key</td></tr>
+</table>
+
+=end html
+
 =head1 RETURN VALUES
 
 EVP_PKEY_get_size(), EVP_PKEY_get_bits() and EVP_PKEY_get_security_bits()
 return a positive number, or 0 if this size isn't available.
 
+EVP_PKEY_get_security_category() returns the post-quantum security category
+which is an integer in the range zero to five inclusive.  It returns -1 if
+the security category information isn't available.
+For all classical algorithms, 0 is returned meaning that they are not
+considered to be quantum safe.
+
 =head1 NOTES
 
 Most functions that have an output buffer and are mentioned with
@@ -83,6 +126,8 @@ The EVP_PKEY_bits(), EVP_PKEY_security_bits(), and EVP_PKEY_size() functions
 were renamed to include C<get> in their names in OpenSSL 3.0, respectively.
 The old names are kept as non-deprecated alias macros.
 
+EVP_PKEY_get_security_category() was added in OpenSSL 3.6.
+
 =head1 COPYRIGHT
 
 Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.