From: Pauli <ppzgs1@gmail.com>
Date: Wed, 7 May 2025 02:10:48 +0000 (+1000)
Subject: doc: document EVP_PKEY_get_security_category function
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=73188a01bd99325d63fb4387a9766338845b6d1e;p=thirdparty%2Fopenssl.git

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 44b91cb00eb..4da9063aaa7 100644
--- 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.