Revision 4252ec2ec4cf03034d2e68a916c6c0668db32399 authored by Marina Polubelova on 29 April 2020, 18:28:18 UTC, committed by Marina Polubelova on 29 April 2020, 18:28:18 UTC
1 parent e220af5
HaclNaCl.rst
.. _hacl-nacl:
NaCl API: Box and SecretBox
---------------------------
HACL* implements the Box and SecretBox API of `NaCl <http://nacl.cr.yp.to/>`_
in a way that is compatible with `libsodium <https://github.com/jedisct1/libsodium>`_.
The functions of this API are in ``Hacl_NaCl.h``.
Public-Key Encryption: Box
^^^^^^^^^^^^^^^^^^^^^^^^^^
The simplest API for Box encryption and decryption is as follows:
.. literalinclude:: ../dist/portable-gcc-compatible/Hacl_NaCl.h
:language: c
:start-after: SNIPPET_START: Hacl_NaCl_crypto_box_easy
:end-before: SNIPPET_END: Hacl_NaCl_crypto_box_easy
The encryption function ``Hacl_NaCl_crypto_box_easy`` takes as its arguments
an output array ``c`` of length ``mlen+16`` bytes, an input array
``m`` of length ``mlen`` bytes, a nonce ``n1`` of length 24 bytes,
the Curve25519 private key ``sk`` of the sender (32 bytes), and the
Curve25519 public key ``pk`` of the recipient (32 bytes).
The function returns 0 on success and -1 (i.e. ``0xffffffff``) on failure.
.. literalinclude:: ../dist/portable-gcc-compatible/Hacl_NaCl.h
:language: c
:start-after: SNIPPET_START: Hacl_NaCl_crypto_box_open_easy
:end-before: SNIPPET_END: Hacl_NaCl_crypto_box_open_easy
The corresponding decryption function ``Hacl_NaCl_crypto_box_open_easy`` takes the
dual arguments: an input array ``c`` of length ``clen>16`` bytes, an output array
``m`` of length ``clen-16`` bytes, a nonce ``n1`` of length 24 bytes,
the Curve25519 public key ``pk`` of the sender (32 bytes), and the
Curve25519 private key ``sk`` of the recipient (32 bytes).
The function retuens 0 on success and -1 (i.e. ``0xffffffff``) on failure.
``Hacl_NaCl.h`` also contains two other APIs for Box:
- ``Hacl_NaCl_crypto_box_detached`` and ``Hacl_NaCl_crypto_box_open_detached`` store the
16-byte authentication tag in in a separate buffer called ``tag``
- To share the expensive X25519 ECDH computation across multiple invocations between
the same sender and recipient keys, callers can first call ``Hacl_NaCl_crypto_box_beforenm``
and then use the result to call ``Hacl_NaCl_crypto_box_detached_afternm`` or ``Hacl_NaCl_crypto_box_easy_afternm``
multiple times.
Symmetric Encryption: SecretBox
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The NaCl API also provides a symmetric encryption primive with the following "easy" API:
.. literalinclude:: ../dist/portable-gcc-compatible/Hacl_NaCl.h
:language: c
:start-after: SNIPPET_START: Hacl_NaCl_crypto_secretbox_easy
:end-before: SNIPPET_END: Hacl_NaCl_crypto_secretbox_easy
.. literalinclude:: ../dist/portable-gcc-compatible/Hacl_NaCl.h
:language: c
:start-after: SNIPPET_START: Hacl_NaCl_crypto_secretbox_open_easy
:end-before: SNIPPET_END: Hacl_NaCl_crypto_secretbox_open_easy
The main difference from the Box API is that these functions take a shared symmetric key ``k`` as
input (instead of Curve25519 keys for the sender and recipient.)
As with Box, there is a separate ``detached`` version of this API.
![swh spinner](/static/img/swh-spinner.gif)
Computing file changes ...