Commit 9f087f08 authored by Dmitry Baryshkov's avatar Dmitry Baryshkov Committed by Niels Möller

Add documentation for GOSTDSA and GOST curves.

Signed-off-by: Dmitry Baryshkov's avatarDmitry Baryshkov <dbaryshkov@gmail.com>
parent 407b0120
...@@ -115,6 +115,7 @@ Public-key algorithms ...@@ -115,6 +115,7 @@ Public-key algorithms
* Side-channel silence:: * Side-channel silence::
* ECDSA:: * ECDSA::
* GOSTDSA::
* Curve 25519 and Curve 448:: * Curve 25519 and Curve 448::
@end detailmenu @end detailmenu
...@@ -4916,6 +4917,7 @@ curve'' is used as a shorthand for the bitsize of the curve's prime ...@@ -4916,6 +4917,7 @@ curve'' is used as a shorthand for the bitsize of the curve's prime
@menu @menu
* Side-channel silence:: * Side-channel silence::
* ECDSA:: * ECDSA::
* GOSTDSA::
* Curve 25519 and Curve 448:: * Curve 25519 and Curve 448::
@end menu @end menu
...@@ -4950,7 +4952,7 @@ accesses depend only on the size of the input data and its location in ...@@ -4950,7 +4952,7 @@ accesses depend only on the size of the input data and its location in
memory, not on the actual data bits. This implies a performance penalty memory, not on the actual data bits. This implies a performance penalty
in several of the building blocks. in several of the building blocks.
@node ECDSA, Curve 25519 and Curve 448, Side-channel silence, Elliptic curves @node ECDSA, GOSTDSA, Side-channel silence, Elliptic curves
@comment node-name, next, previous, up @comment node-name, next, previous, up
@subsubsection ECDSA @subsubsection ECDSA
...@@ -5054,6 +5056,67 @@ random octets and store them at @code{dst}. For advice, see ...@@ -5054,6 +5056,67 @@ random octets and store them at @code{dst}. For advice, see
@xref{Randomness}. @xref{Randomness}.
@end deftypefun @end deftypefun
@node GOSTDSA, Curve 25519 and Curve 448, ECDSA, Elliptic curves
@comment node-name, next, previous, up
@subsubsection GOSTDSA
GOSTDSA (GOST R 34.10-2001, GOST R 34.10-2012) is a variant of the DSA
(@pxref{DSA}) and ECDSA (@pxref{ECDSA}) digital signature schemes, which works
over an elliptic curve group. Original documents are written in Russian.
English translations are provided in @cite{RFC 5832} and @cite{RFC 7091}.
While technically nothing stops one from using GOSTDSA over any curve, it
is defined only over several 256 and 512-bit curves. Like DSA and ECDSA,
creating a signature requires a unique random nonce (repeating the nonce
with two different messages reveals the private key, and any leak or bias
in the generation of the nonce also leaks information about the key).
GOST R 34.10-2001 was defined to use GOST R 34.11-94 hash function
(GOSTHASH94 and GOSTHASH94CP, @cite{RFC 5831}). GOST R 34.10-2012 is
defined to use GOST R 34.11-2012 hash function (Streebog, @cite{RFC
6986}) of corresponding size (256 or 512) depending on curve size.
Nettle defines GOSTDSA in @file{<nettle/gostdsa.h>}. GOSTDSA reuses ECDSA
data types (@code{struct ecc_point}, @code{struct ecc_scalar}) to
represent public and private keys. Also to generate a new GOSTDSA key
pair one has to use @code{ecdsa_generate_keypair()} function.
To create and verify GOSTDSA signatures, the following functions are used.
@deftypefun void gostdsa_sign (const struct ecc_scalar *@var{key}, void *@var{random_ctx}, nettle_random_func *@var{random}, size_t @var{digest_length}, const uint8_t *@var{digest}, struct dsa_signature *@var{signature})
Uses the private key @var{key} to create a signature on @var{digest}.
@var{random_ctx} and @var{random} is a randomness generator.
@code{random(random_ctx, length, dst)} should generate @code{length}
random octets and store them at @code{dst}. The signature is stored in
@var{signature}, in the same was as for plain DSA.
@end deftypefun
@deftypefun int gostdsa_verify (const struct ecc_point *@var{pub}, size_t @var{length}, const uint8_t *@var{digest}, const struct dsa_signature *@var{signature})
Uses the public key @var{pub} to verify that @var{signature} is a valid
signature for the message digest @var{digest} (of @var{length} octets).
Returns 1 if the signature is valid, otherwise 0.
@end deftypefun
For historical reason several curve IDs (OIDs) may correspond to a single
curve/generator combination. Following list defines correspondence
between nettle's view on curves and actual identifiers defined in @cite{RFC
4357} and @cite{RFC 7836}.
@deftypefun {const struct ecc_curve} nettle_get_gost_gc256b(void)
Returns curve corresponding to following identifiers:
@itemize
@item id-GostR3410-2001-CryptoPro-A-ParamSet (@cite{RFC 4357})
@item id-GostR3410-2001-CryptoPro-XchA-ParamSet (@cite{RFC 4357})
@item id-tc26-gost-3410-12-256-paramSetB
@end itemize
@end deftypefun
@deftypefun {const struct ecc_curve} nettle_get_gost_gc512a(void)
Returns curve corresponding to following identifiers:
@itemize
@item id-tc26-gost-3410-12-512-paramSetA (@cite{RFC 7836})
@end itemize
@end deftypefun
@node Curve 25519 and Curve 448, , ECDSA, Elliptic curves @node Curve 25519 and Curve 448, , ECDSA, Elliptic curves
@comment node-name, next, previous, up @comment node-name, next, previous, up
@subsubsection Curve25519 and Curve448 @subsubsection Curve25519 and Curve448
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment