Skip to content

Commit 2740b9e

Browse files
egrabovskayaipl_ci
egrabovskaya
authored and
ipl_ci
committed
[SB][Documentation][Feature] Added documentation for Hash DRBG (#795)
1 parent 1880dc0 commit 2740b9e

14 files changed

Lines changed: 1059 additions & 0 deletions

‎doc/source/drbg/hash-drbg-entr-input-get-size.rst‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
.. _hash-drbg-entr-input-get-size:
2+
3+
ippsHashDRBG_EntropyInputCtxGetSize
4+
====================================
5+
6+
Gets the size (in bytes) for the Entropy input context.
7+
8+
Syntax
9+
------
10+
11+
.. code:: cpp
12+
13+
IppStatus ippsHashDRBG_EntropyInputCtxGetSize(int* pEntrInputSize,
14+
const int entrInputBufBitsLen,
15+
const IppsHashMethod* pHashMethod);
16+
17+
Include Files
18+
-------------
19+
20+
``ippcp.h``
21+
22+
Parameters
23+
----------
24+
25+
.. list-table::
26+
:header-rows: 0
27+
28+
* - pEntrInputSize
29+
- Pointer to the Entropy input context size.
30+
* - entrInputBufBitsLen
31+
- The length of the buffer containing the entropy input and the nonce.
32+
``entrInputBufBitsLen`` must be at least equal to the minimum entropy input length
33+
specified in :ref:`Minimum and maximum values for the Hash DRBG <hash-drbg-min-and-max-values>` to accommodate both
34+
the entropy input and the nonce during instantiation.
35+
* - pHashMethod
36+
- Pointer to the hash method (may be NULL).
37+
38+
Description
39+
------------
40+
41+
Gets the size for the ``IppsHashDRBG_EntropyInputCtx``.
42+
43+
The result is stored to ``*pEntrInputSize``.
44+
45+
.. note::
46+
47+
If the hash method is not specified (NULL pointer is passed), SHA-256 is used by default.
48+
49+
Return Values
50+
-------------
51+
52+
.. list-table::
53+
:header-rows: 0
54+
55+
* - ippStsNoErr
56+
- Indicates no error. All single operations executed without errors.
57+
Any other value indicates an error.
58+
* - ippStsNullPtrErr
59+
- ``pEntrInputSize`` is a NULL pointer.
60+
* - ippStsOutOfRangeErr
61+
- ``entrInputBufBitsLen < 1``.
62+
* - ippStsNotSupportedModeErr
63+
- The hash algorithm is not supported.
64+
* - ippStsLengthErr
65+
- The length of the Entropy input buffer is less than the minimum entropy input length (see :ref:`Minimum and maximum values for the Hash DRBG <hash-drbg-min-and-max-values>`).

‎doc/source/drbg/hash-drbg-entr-input-init.rst‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
.. _hash-drbg-entr-input-init:
2+
3+
ippsHashDRBG_EntropyInputCtxInit
4+
=================================
5+
6+
Initializes the Entropy input context.
7+
8+
Syntax
9+
------
10+
11+
.. code:: cpp
12+
13+
IppStatus ippsHashDRBG_EntropyInputCtxInit(IppsHashDRBG_EntropyInputCtx* pEntrInputCtx,
14+
const int entrInputBufBitsLen,
15+
IppEntropyInputSupplier getEntropyInput);
16+
17+
Include Files
18+
-------------
19+
20+
``ippcp.h``
21+
22+
Parameters
23+
----------
24+
25+
.. list-table::
26+
:header-rows: 0
27+
28+
* - pEntrInputCtx
29+
- Pointer to the Entropy input context.
30+
* - entrInputBufBitsLen
31+
- The length of the buffer containing the entropy input and the nonce.
32+
* - getEntropyInput
33+
- Callback function for supplying the entropy input, providing both an entropy input
34+
and a nonce during instantiation, and an entropy input during reseeding or whenever
35+
prediction resistance is requested.
36+
37+
The callback function must have the following signature:
38+
39+
``IppStatus _STDCALL getEntropyInput(Ipp8u* pEntropyInput, int* pEntropyInputBitsLen, const int minEntropyInBits, const int maxBitsLen, const int predictionResistanceRequest)``.
40+
41+
- ``pEntropyInput`` is a pointer to a byte string containing at least ``minEntropyInBits`` bits of entropy.
42+
- ``pEntropyInputBitsLen`` is the entropy input buffer length in bits.
43+
- ``minEntropyInBits`` and ``maxBitsLen`` is the minimum and maximum number bits of the entropy input.
44+
- ``predictionResistanceRequest`` parameter indicates whether or not prediction resistance is to be provided during the request.
45+
46+
Refer to the `NIST SP 800-90C <https://csrc.nist.gov/pubs/sp/800/90/c/final>`__ to figure out more about Sources of Randomness.
47+
48+
Description
49+
-----------
50+
51+
The function initializes the ``IppsHashDRBG_EntropyInputCtx`` which encapsulates objects necessary
52+
for entropy input and nonce generation during the Hash DRBG operations.
53+
54+
Return Values
55+
-------------
56+
57+
.. list-table::
58+
:header-rows: 0
59+
60+
* - ippStsNoErr
61+
- Indicates no error. All single operations executed without errors.
62+
Any other value indicates an error.
63+
* - ippStsNullPtrErr
64+
- ``pEntrInputCtx`` is a NULL pointer.
65+
* - ippStsOutOfRangeErr
66+
- ``entrInputBufBitsLen < 1``.

‎doc/source/drbg/hash-drbg-gen-bn.rst‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
.. _hash-drbg-gen-bn:
2+
3+
ippsHashDRBG_GenBN
4+
===================
5+
6+
Generates a pseudorandom positive Big Number of the specified bit length.
7+
8+
Syntax
9+
------
10+
11+
.. code:: cpp
12+
13+
IppStatus ippsHashDRBG_GenBN(IppsBigNumState* pRand,
14+
int nBits,
15+
const int requestedSecurityStrength,
16+
const int predictionResistanceRequest,
17+
const Ipp8u* addlInput,
18+
const int addlInputBitsLen,
19+
IppsHashDRBG_EntropyInputCtx* pEntrInputCtx,
20+
IppsHashDRBGState* pDrbgCtx);
21+
22+
Include Files
23+
-------------
24+
25+
``ippcp.h``
26+
27+
Parameters
28+
----------
29+
30+
.. list-table::
31+
:header-rows: 0
32+
33+
* - pRand
34+
- Pointer to the output pseudorandom Big Number.
35+
* - nBits
36+
- Requested number of bits to be generated.
37+
* - requestedSecurityStrength
38+
- The security strength to be associated with the requested pseudorandom bits.
39+
* - predictionResistanceRequest
40+
- Indicates whether or not prediction resistance is to be provided during the request
41+
(whether or not fresh entropy bits are required).
42+
* - addlInput
43+
- Pointer to the array containing additional input (optional).
44+
* - addlInputBitsLen
45+
- Length of the ``addlInput`` in bits (may be zero).
46+
* - pEntrInputCtx
47+
- Pointer to the Entropy input context.
48+
The size is equal to the value returned by ``ippsHashDRBG_EntropyInputCtxGetSize``.
49+
* - pDrbgCtx
50+
- Pointer to the ``IppsHashDRBGState`` context.
51+
Size equals to the value returned by ``ippsHashDRBG_GetSize``.
52+
53+
Description
54+
-----------
55+
56+
The ``ippsHashDRBG_GenBN`` function:
57+
58+
- Calls the reseed function to incorporate fresh entropy when prediction resistance is requested or
59+
the Hash DRBG has reached the end of its reseed interval.
60+
61+
- Generates a pseudorandom Big Number of the specified ``nBits`` length and updates the working state.
62+
63+
Return Values
64+
-------------
65+
66+
.. list-table::
67+
:header-rows: 0
68+
69+
* - ippStsNoErr
70+
- Indicates no error. All single operations executed without errors.
71+
Any other value indicates an error.
72+
* - ippStsNullPtrErr
73+
- ``pRand``, ``pDrbgCtx`` or ``pEntrInputCtx`` is a NULL pointer.
74+
* - ippStsContextMatchErr
75+
- If the Big Number identifier doesn't match.
76+
If the Hash DRBG identifier doesn't match.
77+
If the Entropy input context identifier doesn't match.
78+
* - ippStsBadArgErr
79+
- Prediction resistance is requested but ``predictionResistanceFlag`` has been set to 0 during the initialization of `pDrbgCtx` state.
80+
The ``nBits`` exceeds the maximum possible number of bits per request or the maximum possible value.
81+
The ``addlInput`` is NULL with non-zero ``addlInputBitsLen``, or the ``addlInput`` is not NULL, but ``addlInputBitsLen`` is 0.
82+
* - ippStsOutOfRangeErr
83+
- The length of ``addlInput`` exceeds the maximum possible value.
84+
The length for the entropy input, passed to the getEntropyInput callback function, is less than the *security strength*
85+
or exceeds the length of the entropy input buffer.
86+
* - ippStsNotSupportedModeErr
87+
- The CPU does not support the ``RDSEED`` and/or ``RDRAND`` instructions.
88+
* - ippStsHashOperationErr
89+
- An error status code was returned during hashing operations.

‎doc/source/drbg/hash-drbg-gen-test.rst‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
.. _hash-drbg-gen-test:
2+
3+
ippsHashDRBG_GenTest
4+
=====================
5+
6+
Tests the ``ippsHashDRBG_Gen`` function on demand.
7+
8+
Syntax
9+
------
10+
11+
.. code:: cpp
12+
13+
IppStatus ippsHashDRBG_GenTest(Ipp32u* pRandBuf,
14+
int nBits,
15+
IppsHashDRBG_EntropyInputCtx* pEntrInputCtxTempBuf,
16+
IppsHashDRBGState* pDrbgCtxTempBuf);
17+
18+
Include Files
19+
-------------
20+
21+
``ippcp.h``
22+
23+
Parameters
24+
----------
25+
26+
.. list-table::
27+
:header-rows: 0
28+
29+
* - pRandBuf
30+
- Pointer to a buffer used to store the output generated during ``ippsHashDRBG_Gen`` testing.
31+
* - nBits
32+
- Number of bits to be generated to test ``ippsHashDRBG_Gen``.
33+
* - pEntrInputCtxTempBuf
34+
- Pointer to a temporarily allocated buffer used to store the Entropy input context.
35+
* - pDrbgCtxTempBuf
36+
- Pointer to a temporarily allocated buffer used to store the Hash DRBG state.
37+
38+
.. note::
39+
40+
.. rubric:: Important
41+
:class: NoteTipHead
42+
43+
- The ``pRandBuf`` buffer size must be at least 128 bytes (or 1024 bits) in size to
44+
accommodate the pseudorandom data that will be generated. However, ``nBits`` must be
45+
equal to or less than 1024 bits, which is the maximum number of bits that can be generated.
46+
- Separate buffers must be allocated for the Entropy input context and the Hash DRBG state
47+
and passed to the ``ippsHashDRBG_GenTest`` function. Otherwise, the working buffers' current
48+
state will be corrupted, leading to incorrect pseudorandom number sequences.
49+
50+
Description
51+
-----------
52+
53+
This function tests the ``ippsHashDRBG_Gen`` function using the minimum security strength, representative
54+
values for the entropy input, nonce and personalization string, and the requested prediction resistance.
55+
56+
Return Values
57+
-------------
58+
59+
.. list-table::
60+
:header-rows: 0
61+
62+
* - ippStsNoErr
63+
- Indicates no error. All single operations executed without errors.
64+
The values used during the test produce the expected results.
65+
* - ippStsNullPtrErr
66+
- ``pRandBuf``, ``pEntrInputCtxTempBuf``, or ``pDrbgCtxTempBuf`` is a NULL pointer.
67+
The pointer to the buffer that contains the entropy input is NULL.
68+
* - ippStsContextMatchErr
69+
- If the Entropy input context identifier or the Hash DRBG identifier doesn't match.
70+
* - ippStsOutOfRangeErr
71+
- ``entrInputBufBitsLen < 1``.
72+
* - ippStsNotSupportedModeErr
73+
- The CPU does not support the ``RDSEED`` and/or ``RDRAND`` instructions.
74+
* - ippStsHashOperationErr
75+
- An error status code was returned during hashing operations.

‎doc/source/drbg/hash-drbg-gen.rst‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
.. _hash-drbg-gen:
2+
3+
ippsHashDRBG_Gen
4+
=================
5+
6+
Generates a pseudorandom unsigned 32-bit integer buffer of the specified bit length.
7+
8+
Syntax
9+
------
10+
11+
.. code:: cpp
12+
13+
IppStatus ippsHashDRBG_Gen(Ipp32u* pRand,
14+
int nBits,
15+
const int requestedSecurityStrength,
16+
const int predictionResistanceRequest,
17+
const Ipp8u* addlInput,
18+
const int addlInputBitsLen,
19+
IppsHashDRBG_EntropyInputCtx* pEntrInputCtx,
20+
IppsHashDRBGState* pDrbgCtx);
21+
22+
Include Files
23+
-------------
24+
25+
``ippcp.h``
26+
27+
Parameters
28+
----------
29+
30+
.. list-table::
31+
:header-rows: 0
32+
33+
* - pRand
34+
- Pointer to the output pseudorandom unsigned integer buffer.
35+
* - nBits
36+
- Requested number of bits to be generated.
37+
* - requestedSecurityStrength
38+
- The security strength to be associated with the requested pseudorandom bits.
39+
* - predictionResistanceRequest
40+
- Indicates whether or not prediction resistance is to be provided during the request
41+
(whether or not fresh entropy bits are required).
42+
* - addlInput
43+
- Pointer to the array containing additional input (optional).
44+
* - addlInputBitsLen
45+
- Length of the ``addlInput`` in bits (may be zero).
46+
* - pEntrInputCtx
47+
- Pointer to the Entropy input context.
48+
The size is equal to the value returned by ``ippsHashDRBG_EntropyInputCtxGetSize``.
49+
* - pDrbgCtx
50+
- Pointer to the ``IppsHashDRBGState`` context.
51+
Size equals to the value returned by ``ippsHashDRBG_GetSize``.
52+
53+
Description
54+
-----------
55+
56+
The ``ippsHashDRBG_Gen`` function:
57+
58+
- Calls the reseed function to incorporate fresh entropy when prediction resistance is requested or
59+
the Hash DRBG has reached the end of its reseed interval.
60+
61+
- Generates a pseudorandom unsigned integer big number of the specified ``nBits`` length and updates the working state.
62+
63+
Return Values
64+
-------------
65+
66+
.. list-table::
67+
:header-rows: 0
68+
69+
* - ippStsNoErr
70+
- Indicates no error. All single operations executed without errors.
71+
Any other value indicates an error.
72+
* - ippStsNullPtrErr
73+
- ``pRand``, ``pDrbgCtx`` or ``pEntrInputCtx`` is a NULL pointer.
74+
The pointer to the buffer that contains the entropy input is NULL.
75+
* - ippStsContextMatchErr
76+
- If the Hash DRBG identifier doesn't match.
77+
If the Entropy input context identifier doesn't match.
78+
* - ippStsBadArgErr
79+
- Prediction resistance is requested, but ``predictionResistanceFlag`` has been set to 0 during the initialization of `pDrbgCtx` state.
80+
The ``nBits`` exceeds the maximum possible number of bits per request or the maximum possible value.
81+
The ``addlInput`` is NULL with non-zero ``addlInputBitsLen``, or the ``addlInput`` is not NULL, but ``addlInputBitsLen`` is 0.
82+
* - ippStsOutOfRangeErr
83+
- The length of the ``addlInput`` exceeds the maximum possible value.
84+
The length for the entropy input, passed to the getEntropyInput callback function, is less than the *security strength*
85+
or exceeds the length of the entropy input buffer.
86+
* - ippStsNotSupportedModeErr
87+
- The CPU does not support the ``RDSEED`` and/or ``RDRAND`` instructions.
88+
* - ippStsHashOperationErr
89+
- An error status code was returned during hashing operations.

0 commit comments

Comments
 (0)