Skip to content

Commit e9f4150

Browse files
andreyfe1ipl_ci
andreyfe1
authored and
ipl_ci
committed
[SB][Documentation][Feature] Added documentation for ML-DSA (#839)
1 parent 33683de commit e9f4150

16 files changed

Lines changed: 630 additions & 11 deletions

‎CHANGELOG.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,7 @@ This is a list of notable changes to Intel® Cryptography Primitives Library, in
1111
- Cleaned-up the library from the outdated macOS specific code.
1212
- Added RSA partial key setting functions to enable incremental construction of RSA keys by setting individual components separately.
1313
- Extended ippsRSAVerify_PKCS1v15_rmf function to support pre-hashed message verification.
14-
- Add new pkcs5-pbkdf2 key derivation function as part of PKCS-5, RFC-8018
15-
- Cleaned-up the library from the outdated macOS specific code
14+
- Added a new pkcs5-pbkdf2 key derivation function as part of PKCS-5, RFC-8018
1615
- Added support for ML-DSA scheme with Key Generation, Signing and Verification functionality implemented according to the FIPS 204.
1716

1817
## Intel(R) Cryptography Primitives Library 1.3.0

‎doc/source/developer-reference.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ Intel® Cryptography Primitives Library API Reference
1414
public-key-cryptography-functions
1515
finite-field-arithmetic
1616
mitigation-for-frequency-throttling
17+
post-quantum-functions
1718
multi-buffer-cryptography-functions
1819
support-functions-and-classes
1920
deprecated-functions

‎doc/source/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -115,3 +115,4 @@ available documentation downloads by product version, see these pages:
115115
preview-features
116116
developer-reference
117117
notices-and-disclaimers
118+

‎doc/source/ml_dsa/buffers-get-size.rst‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
.. _ml-dsa-buffers-get-size:
2+
3+
API to query working buffers size
4+
=================================
5+
6+
Query the size of the working buffers.
7+
8+
Syntax
9+
------
10+
.. code:: cpp
11+
12+
IppStatus ippsMLDSA_KeyGenBufferGetSize(int* pSize, const IppsMLDSAState* pMLDSAState);
13+
IppStatus ippsMLDSA_SignBufferGetSize(int* pSize, const IppsMLDSAState* pMLDSAState);
14+
IppStatus ippsMLDSA_VerifyBufferGetSize(int* pSize, const IppsMLDSAState* pMLDSAState);
15+
16+
Include Files
17+
-------------
18+
19+
``ippcp.h``
20+
21+
Parameters
22+
----------
23+
24+
.. list-table::
25+
:header-rows: 0
26+
27+
* - pSize
28+
- Pointer to the buffers size.
29+
* - pMLDSAState
30+
- Pointer to the initialized ML-DSA context
31+
32+
Description
33+
-----------
34+
35+
``ippsMLDSA_KeyGenBufferGetSize`` queries the size for working buffer required for the
36+
``ippsMLDSA_KeyGen`` function.
37+
38+
``ippsMLDSA_SignBufferGetSize`` queries the size for working buffer required for the
39+
``ippsMLDSA_Sign`` function.
40+
41+
``ippsMLDSA_VerifyBufferGetSize`` queries the size for working buffer required for the
42+
``ippsMLDSA_Verify`` function.
43+
44+
Allocated memory should be passed directly to the processing API.
45+
46+
.. note::
47+
48+
.. rubric:: Important
49+
:class: NoteTipHead
50+
51+
The API family is supported in experimental mode. To use the functions, users need to define
52+
the ``IPPCP_PREVIEW_ML_DSA`` macro before including the ``ippcp.h`` header file. See
53+
:ref:`Preview Features <experimental>` for more details.
54+
55+
Return Values
56+
-------------
57+
58+
.. list-table::
59+
:header-rows: 0
60+
61+
* - ippStsNoErr
62+
- Indicates no error. Any other value indicates an error or warning.
63+
* - ippStsNullPtrErr
64+
- ``pSize`` or ``pMLDSAState`` are ``NULL`` pointers.
65+
* - ippStsContextMatchErr
66+
- ``pMLDSAState`` was not initialized.

‎doc/source/ml_dsa/get-info.rst‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
.. _ml-dsa-get-info:
2+
3+
ippsMLDSA_GetInfo
4+
=================
5+
6+
Fills ``IppsMLDSAInfo`` structure with the sizes corresponding to the given scheme type.
7+
8+
Syntax
9+
------
10+
.. code:: cpp
11+
12+
IppStatus ippsMLDSA_GetInfo(IppsMLDSAInfo* pInfo, IppsMLDSAParamSet schemeType);
13+
14+
Include Files
15+
-------------
16+
17+
``ippcp.h``
18+
19+
Parameters
20+
----------
21+
22+
.. list-table::
23+
:header-rows: 0
24+
25+
* - pInfo
26+
- Pointer to the ML-DSA ``pInfo`` structure.
27+
* - schemeType
28+
- Parameter specifying the scheme type. See
29+
:ref:`Supported ML-DSA parameters <ml-dsa-params>` for more information.
30+
31+
Description
32+
-----------
33+
34+
The function fills ``IppsMLDSAInfo`` structure with the sizes corresponding to the given scheme
35+
type. The sizes are used to allocate memory for the public key, private key, and signature.
36+
37+
``IppsMLDSAInfo`` is the public data type and has the following structure:
38+
39+
.. code:: cpp
40+
41+
typedef struct {
42+
int publicKeySize;
43+
int privateKeySize;
44+
int signatureSize;
45+
} IppsMLDSAInfo;
46+
47+
.. note::
48+
49+
.. rubric:: Important
50+
:class: NoteTipHead
51+
52+
The API family is supported in experimental mode. To use the functions, users need to define
53+
the ``IPPCP_PREVIEW_ML_DSA`` macro before including the ``ippcp.h`` header file. See
54+
:ref:`Preview Features <experimental>` for more details.
55+
56+
Return Values
57+
-------------
58+
59+
.. list-table::
60+
:header-rows: 0
61+
62+
* - ippStsNoErr
63+
- Indicates no error. Any other value indicates an error or warning.
64+
* - ippStsNullPtrErr
65+
- ``pInfo`` is a ``NULL`` pointer.
66+
* - ippStsBadArgErr
67+
- ``schemeType`` is not supported.

‎doc/source/ml_dsa/get-size.rst‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
.. _ml-dsa-get-size:
2+
3+
ippsMLDSA_GetSize
4+
=================
5+
6+
Queries the size of ``IppsMLDSAState``.
7+
8+
Syntax
9+
------
10+
.. code:: cpp
11+
12+
IppStatus ippsMLDSA_GetSize(int* pSize);
13+
14+
Include Files
15+
-------------
16+
17+
``ippcp.h``
18+
19+
Parameters
20+
----------
21+
22+
.. list-table::
23+
:header-rows: 0
24+
25+
* - pSize
26+
- Pointer to the state size.
27+
28+
Description
29+
-----------
30+
31+
The function queries the size of ``IppsMLDSAState``. Allocated memory will be used as the context
32+
required for ML-DSA computations.
33+
34+
.. note::
35+
36+
.. rubric:: Important
37+
:class: NoteTipHead
38+
39+
The API family is supported in experimental mode. To use the functions, users need to define
40+
the ``IPPCP_PREVIEW_ML_DSA`` macro before including the ``ippcp.h`` header file. See
41+
:ref:`Preview Features <experimental>` for more details.
42+
43+
Return Values
44+
-------------
45+
46+
.. list-table::
47+
:header-rows: 0
48+
49+
* - ippStsNoErr
50+
- Indicates no error. Any other value indicates an error or warning.
51+
* - ippStsNullPtrErr
52+
- ``pSize`` is a ``NULL`` pointer.

‎doc/source/ml_dsa/index.rst‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
.. _ml-dsa-index:
2+
3+
ML-DSA
4+
======
5+
6+
The **Module-Lattice-Based Digital Signature Algorithm (ML-DSA)** is a set of
7+
algorithms that can be used to generate and verify digital signatures. ML-DSA
8+
is designed to be secure even against adversaries in possession of a
9+
large-scale quantum computer.
10+
11+
The implementation is based on the
12+
`FIPS 204 standard <https://csrc.nist.gov/pubs/fips/204/final>`__
13+
and provides three main primitives:
14+
15+
- Key Generation
16+
- Signing
17+
- Verification
18+
19+
Using a product containing these algorithms does not guarantee the security
20+
of the overall system in which the product is used.
21+
The security of the system depends on the secure use of the product in the
22+
overall system, including proper key management.
23+
24+
The signature generation implementation does not incorporate
25+
additional constant-time techniques. It performs honest acceptance-rejection
26+
sampling as specified in the FIPS 204 standard to achieve optimal performance.
27+
28+
.. note::
29+
30+
.. rubric:: API usage
31+
:class: NoteTipHead
32+
33+
The API family is supported in experimental mode. To use the functions, users need to define
34+
the ``IPPCP_PREVIEW_ML_DSA`` macro before including the ``ippcp.h`` header file. See
35+
:ref:`Preview Features <experimental>` for more details.
36+
37+
.. _ml-dsa-params:
38+
39+
Supported ML-DSA Parameter Sets
40+
--------------------------------
41+
42+
.. code:: cpp
43+
44+
typedef enum {
45+
ML_DSA_44 = 1,
46+
ML_DSA_65 = 2,
47+
ML_DSA_87 = 3
48+
} IppsMLDSAParamSet;
49+
50+
Example: Key Generation, Signing, and Verification
51+
---------------------------------------------------
52+
53+
.. literalinclude:: ../../../examples/post-quantum/ml_dsa_87_keygen_sign_verify.cpp
54+
:language: cpp
55+
56+
Related Functionality
57+
---------------------
58+
59+
.. toctree::
60+
:maxdepth: 1
61+
62+
get-size
63+
get-info
64+
init
65+
buffers-get-size
66+
key-gen
67+
sign
68+
verify

‎doc/source/ml_dsa/init.rst‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
.. _ml-dsa-init:
2+
3+
ippsMLDSA_Init
4+
=================
5+
6+
Initializes ``IppsMLDSAState`` for the further ML-DSA computations.
7+
8+
Syntax
9+
------
10+
.. code:: cpp
11+
12+
IppStatus ippsMLDSA_Init(IppsMLDSAState* pMLDSACtx,
13+
Ipp32s maxMessageLength,
14+
IppsMLDSAParamSet schemeType);
15+
16+
Include Files
17+
-------------
18+
19+
``ippcp.h``
20+
21+
Parameters
22+
----------
23+
24+
.. list-table::
25+
:header-rows: 0
26+
27+
* - pMLDSACtx
28+
- Pointer to the ML-DSA state.
29+
* - maxMessageLength
30+
- Maximum message length in bytes. The parameter is used to calculate the size of the internal
31+
buffers. The maximum message length should be less than 2^32 bytes - number
32+
of bytes required for temporary buffers. Size of such buffers can be obtained using
33+
:ref:`API to query working buffers size <ml-dsa-buffers-get-size>`.
34+
* - schemeType
35+
- Parameter specifying the scheme type. See
36+
:ref:`Supported ML-DSA parameters <ml-dsa-params>` for more information.
37+
38+
Description
39+
-----------
40+
41+
The function initializes ``IppsMLDSAState`` for the further ML-DSA computations.
42+
43+
.. note::
44+
45+
.. rubric:: Important
46+
:class: NoteTipHead
47+
48+
The API family is supported in experimental mode. To use the functions, users need to define
49+
the ``IPPCP_PREVIEW_ML_DSA`` macro before including the ``ippcp.h`` header file. See
50+
:ref:`Preview Features <experimental>` for more details.
51+
52+
Return Values
53+
-------------
54+
55+
.. list-table::
56+
:header-rows: 0
57+
58+
* - ippStsNoErr
59+
- Indicates no error. Any other value indicates an error or warning.
60+
* - ippStsNullPtrErr
61+
- ``pMLDSACtx`` is a ``NULL`` pointer.
62+
* - ippStsBadArgErr
63+
- ``schemeType`` is not supported.
64+
* - ippStsLengthErr
65+
- ``maxMessageLength`` is less than 1 or greater than the allowed maximum.

0 commit comments

Comments
 (0)