pqclean NIF

Post-Quantum Cryptography NIF based on PQClean for Erlang and Elixir.

See documentation for the pqclean_nif module for the full list of types and functions provided.

Installation

Add pqclean to your project's dependencies in mix.exs

defp deps do
  [
    {:pqclean, "~> 0.0.3"}
  ]
end

Add pqclean to your project's dependencies in your Makefile for erlang.mk or the following to your rebar.config

{deps, [
    {pqclean, "0.0.3"}
]}.

Examples

Key Encapsulation Mechanism (KEM) Algorithm Example

{PK, SK} = pqclean_nif:kyber768_keypair(),
{CT, SS} = pqclean_nif:kyber768_encapsulate(PK),
     SS  = pqclean_nif:kyber768_decapsulate(CT, SK).

KEM with Encryption Example

% Alice and Bob want to exchange an encrypted messages.
% Alice wants to send Bob the message "a2b".
% Bob wants to send Alice the message "b2a".

% Helper functions (encrypt/decrypt with AES-256-GCM):
Encrypt = fun(K, N, PTxt) ->
    crypto:crypto_one_time_aead(aes_256_gcm, K, <<N:96>>, PTxt, <<>>, true)
end,
Decrypt = fun(K, N, CTxt, CTag) ->
    crypto:crypto_one_time_aead(aes_256_gcm, K, <<N:96>>, CTxt, <<>>, CTag, false)
end.

% Alice generates a new ephemeral keypair using Kyber-768:
{PKa, SKa} = pqclean_nif:kyber768_keypair().

% Alice sends `PKa&#39; to Bob.

% Bob generates a new ephemeral keypair using Kyber-768:
{PKb, SKb} = pqclean_nif:kyber768_keypair(),
% Bob encapsulates a shared-secret `SSb2a&#39; against Alice&#39;s `PKa&#39; with
% an ephemeral KEM cipher-text `CTb2a&#39; using Kyber-768:
{CTb2a, SSb2a} = pqclean_nif:kyber768_encapsulate(PKa),
% Bob encrypts plain-text `PKb&#39; with shared-secret `SSb2a&#39; and nonce `0&#39;
% into cipher-text `CTxt_PKb&#39; and cipher-tag `CTag_PKb&#39;:
{CTxt_PKb, CTag_PKb} = Encrypt(SSb2a, 0, PKb),
% Bob encrypts plain-text "b2a" with shared-secret `SSb2a&#39; and nonce `1&#39;
% into cipher-text `CTxt_PKb&#39; and cipher-tag `CTag_PKb&#39;:
{CTxt_Mb, CTag_Mb} = Encrypt(SSb2a, 1, <<"b2a">>).

% Bob sends `CTb2a&#39;, `CTxt_PKb&#39;, `CTag_PKb&#39;, `CTxt_Mb&#39;, and `CTag_Mb&#39; to Alice.

% Alice decapsulates Bob&#39;s `CTb2a&#39; using secret-key `SKa&#39; which
% results in shared-secret `SSb2a&#39; using Kyber-768:
SSb2a = pqclean_nif:kyber768_decapsulate(CTb2a, SKa),
% Alice decrypts `PKb&#39; with shared-secret `SSb2a&#39;:
PKb = Decrypt(SSb2a, 0, CTxt_PKb, CTag_PKb),
% Alice decrypts Bob&#39;s message "b2a" using shared-secret `SSb2a&#39;:
<<"b2a">> = Decrypt(SSb2a, 1, CTxt_Mb, CTag_Mb),
% Alice encapsulates a shared-secret `SSa2b&#39; against Bob&#39;s `PKb&#39; with
% an ephemeral KEM cipher-text `CTa2b&#39; using Kyber-768:
{CTa2b, SSa2b} = pqclean_nif:kyber768_encapsulate(PKb),
% Alice encrypts plain-text "a2b" with shared-secret `SSa2b&#39; and nonce `0&#39;
% into cipher-text `CTxt_Ma&#39; and cipher-tag `CTag_Ma&#39;:
{CTxt_Ma, CTag_Ma} = Encrypt(SSa2b, 0, <<"a2b">>).

% Alice sends `CTa2b&#39;, `CTxt_Ma&#39;, and `CTag_Ma&#39; to Bob.

% Bob decapsulates Alice&#39;s `CTa2b&#39; using secret-key `SKb&#39; which
% results in shared-secret `SSa2b&#39; using Kyber-768:
SSa2b = pqclean_nif:kyber768_decapsulate(CTa2b, SKb),
% Bob decrypts Alice&#39;s message "a2b" using shared-secret `SSa2b&#39;:
<<"a2b">> = Decrypt(SSa2b, 0, CTxt_Ma, CTag_Ma).

% Alice sends Bob a total of 2,291-bytes.
% Bob sends Alice a total of 2,307-bytes.

See PQNoise for more in-depth examples.

Signature Algorithm Example

{PK, SK} = pqclean_nif:falcon512_keypair(),
Msg = <<"message">>,
Sig = pqclean_nif:falcon512_sign(Msg, SK),
true = pqclean_nif:falcon512_verify(Sig, Msg, PK).

KEM Algorithm Support

WARNING: Algorithms marked with a dagger (†) require a large stack for key generation. See below for more information.

Large Stack Support

When generating keys for "large stack" algorithms, an exception will be raised if the detected stack size is below 8MB:

1> try pqclean_nif:mceliece348864_keypair() catch error:{badarg, {_File, _Line}, Reason} -> Reason end.
"Key generation for Classic McEliece 348864 requires a large stack (>= 8MB): "
"please restart the BEAM with `erl +sssdcpu 1024` on 64-bit machines "
"(or `erl +sssdcpu 2048` on 32-bit machines); current setting is `erl +sssdcpu 41`"

Restarting the BEAM with erl +sssdcpu 1024 on 64-bit systems will allow key generation for these algorithms to be supported.

NOTE: If using an escript, rebar3, elixir, etc: it may be simpler to use the environment variable ERL_AFLAGS="+sssdcpu 1024" instead.

$ erl +sssdcpu 1024

1> {PK, SK} = pqclean_nif:mceliece348864_keypair().
{<<38,72,183,62,48,9,8,23,83,149,228,233,255,143,120,71,
   113,143,14,95,28,157,43,73,51,99,6,79,...>>,
 <<116,53,239,220,26,165,236,199,7,246,124,172,167,182,
   154,60,152,213,9,243,206,191,24,129,129,73,132,...>>}

Signature Algorithm Support