Revision 5b2fbf3c4989a9b0587a00578f69f3041df3f957 authored by Jonathan Protzenko on 08 April 2020, 18:59:46 UTC, committed by Jonathan Protzenko on 08 April 2020, 18:59:46 UTC
1 parent d4ca892
HaclSig.rst
.. _hacl-ed25519:
Signatures: Ed25519
-------------------
HACL* implements the Edwards-Curve Digital Signature Algorithm (EdDSA)
construction for the Ed25519 elliptic curve as specified in `IETF RFC 8032 <https://tools.ietf.org/html/rfc8032>`_.
The API for this signature algorithm is in ``Hacl_Ed25519.h``.
Key Generation
^^^^^^^^^^^^^^
Any 32 byte array can be used as an Ed25519 private key. In
practice, private keys should be generated using a cryptographically
strong pseudo-random number generator (CSPRNG). In some cases, the
private key may be derived as the result of a key derivation function
such as HKDF.
Given a private key, the corresponding public key can be computed
using the ``secret_to_public`` function:
.. literalinclude:: ../dist/portable-gcc-compatible/Hacl_Ed25519.h
:language: c
:start-after: SNIPPET_START: Hacl_Ed25519_secret_to_public
:end-before: SNIPPET_END: Hacl_Ed25519_secret_to_public
The first argument is a pointer to the output public key ``pub`` (64 bytes);
the second argument is a pointer to the input private key ``priv`` (32 bytes).
EdDSA Signing
^^^^^^^^^^^^^
The signature operation is implemented by the following function:
.. literalinclude:: ../dist/portable-gcc-compatible/Hacl_Ed25519.h
:language: c
:start-after: SNIPPET_START: Hacl_Ed25519_sign
:end-before: SNIPPET_END: Hacl_Ed25519_sign
The first argument is a pointer to the output signature ``signature``;
the second argument is the private key of the signer ``priv``;
the third argument is the length ``len`` of the message to be signed ``msg``.
The size of ``signature`` must be (at least) 64 bytes; the size of the private
key is 32 bytes.
EdDSA Verify
^^^^^^^^^^^^^
To verify an Ed25519 signature, one may call the following function:
.. literalinclude:: ../dist/portable-gcc-compatible/Hacl_Ed25519.h
:language: c
:start-after: SNIPPET_START: Hacl_Ed25519_verify
:end-before: SNIPPET_END: Hacl_Ed25519_verify
The first argument is a pointer to the public key ``pub`` (64 bytes);
the second argument is the length ``len`` of the message to be signed ``msg``;
the last argument is the input signature ``signature``.
If the signature verification succeeds the function returns the boolean ``true``,
otherwise it returns ``false``.
EdDSA Sign Expanded
^^^^^^^^^^^^^^^^^^^
In situations where a signer needs to sign many times with the same
signature key, a part of the signature computation can be shared
between these invocations for efficiency. The caller first calls
``Hacl_Ed25519_expand_keys`` to compute an expanded signing key ``ks``,
and then can use ``ks`` to call ``Hacl_Ed25519_sign_expanded`` multiple
times with different arguments.
.. literalinclude:: ../dist/portable-gcc-compatible/Hacl_Ed25519.h
:language: c
:start-after: SNIPPET_START: Hacl_Ed25519_expand_keys
:end-before: SNIPPET_END: Hacl_Ed25519_expand_keys
.. literalinclude:: ../dist/portable-gcc-compatible/Hacl_Ed25519.h
:language: c
:start-after: SNIPPET_START: Hacl_Ed25519_sign_expanded
:end-before: SNIPPET_END: Hacl_Ed25519_sign_expanded
Other Signature Algorithms: ECDSA with P-256
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A development branch includes a verified implementation of ECDSA
signatures with the P-256 elliptic curve, which has not yet been
merged to master. Contact the HACL* maintainers if you wish to use
this code.
![swh spinner](/static/img/swh-spinner.gif)
Computing file changes ...