libnacl - Man Page

libnacl — libnacl Documentation

Contents:

Unlike traditional means for public key asymmetric encryption, the nacl encryption systems are very high speed. The CurveCP network protocol for instance only uses public key encryption for all transport.

Public key encryption is very simple, as is evidenced with this communication between Alice and Bob:

import libnacl.public

# Define a message to send
msg = b'You\'ve got two empty halves of coconut and you\'re bangin\' \'em together.'

# Generate the key pairs for Alice and bob, if secret keys already exist
# they can be passed in, otherwise new keys will be automatically generated
bob = libnacl.public.SecretKey()
alice = libnacl.public.SecretKey()

# Create the boxes, this is an object which represents the combination of the
# sender's secret key and the receiver's public key
bob_box = libnacl.public.Box(bob.sk, alice.pk)
alice_box = libnacl.public.Box(alice.sk, bob.pk)

# Bob's box encrypts messages for Alice
bob_ctxt = bob_box.encrypt(msg)
# Alice's box decrypts messages from Bob
bclear = alice_box.decrypt(bob_ctxt)
# Alice can send encrypted messages which only Bob can decrypt
alice_ctxt = alice_box.encrypt(msg)
aclear = bob_box.decrypt(alice_ctxt)

NOTE:

Every encryption routine requires a nonce. The nonce is a 24 char string that must never be used twice with the same keypair. If no nonce is passed in then a nonce is generated based on random data. If it is desired to generate a nonce manually this can be done by passing it into the encrypt method.

import libnacl.public

fred = libnacl.public.SecretKey()

raw_sk = fred.sk
hex_sk = fred.hex_sk()

raw_pk = fred.pk
hex_pk = fred.hex_pk()

import libnacl.public

tom_secret = libnacl.public.SecretKey()

tom = libnacl.public.PublicKey(tom_secret.pk)

raw_pk = tom.pk
hex_pk = tom.hex_pk()

import libnacl.public

fred = libnacl.public.SecretKey()
fred.save('/etc/nacl/fred.key')

Sealed box is a variant of public key encryption scheme which only the receiver's public key is required. As such, the sender of the message cannot be cryptographically authenticated.

import libnacl.sealed
import libnacl.public

# Define a message to send
msg = b'You\'ve got two empty halves of coconut and you\'re bangin\' \'em together.'

# Generate the key pair
keypair = libnacl.public.SecretKey()

# Create the box
box = libnacl.sealed.SealedBox(keypair)

# Encrypt messages
ctxt = box.encrypt(msg)
# Decrypt messages
bclear = box.decrypt(ctxt)

Secret key encryption is the method of using a single key for both encryption and decryption of messages. One of the classic examples from history of secret key, or symmetric, encryption is the Enigma machine.

The SecretBoxEasy class in libnacl.secret_easy makes this type of encryption very easy to execute:

import libnacl.secret_easy

msg = b'But then of course African swallows are not migratory.'
# Create a SecretBox object, if not passed in the secret key is
# Generated purely from random data
box = libnacl.secret_easy.SecretBoxEasy()
# Messages can now be safely encrypted
ctxt = box.encrypt(msg)
# An additional box can be created from the original box secret key
box2 = libnacl.secret_easy.SecretBoxEasy(box.sk)
# Messages can now be easily encrypted and decrypted
clear1 = box.decrypt(ctxt)
clear2 = box2.decrypt(ctxt)
ctxt2 = box2.encrypt(msg)
clear3 = box.decrypt(ctxt2)

NOTE:

Every encryption routine requires a nonce. The nonce is a 24 char string that must never be used twice with the same keypair. If no nonce is passed in then a nonce is generated based on random data. If it is desired to generate a nonce manually this can be done by passing it into the encrypt method.

The nacl libs have the capability to sign and verify messages. Please be advised that public key encrypted messages do not need to be signed, the nacl box construct verifies the validity of the sender.

To sign and verify messages use the Signer and Verifier classes:

import libnacl.sign

msg = (b'Well, that\'s no ordinary rabbit.  That\'s the most foul, '
       b'cruel, and bad-tempered rodent you ever set eyes on.')
# Create a Signer Object, if the key seed value is not passed in the
# signing keys will be automatically generated
signer = libnacl.sign.Signer()
# Sign the message, the signed string is the message itself plus the
# signature
signed = signer.sign(msg)
# If only the signature is desired without the message:
signature = signer.signature(msg)
# To create a verifier pass in the verify key:
veri = libnacl.sign.Verifier(signer.hex_vk())
# Verify the message!
verified = veri.verify(signed)
verified2 = veri.verify(signature + msg)

import libnacl.sign

signer = libnacl.sign.Signer()
signer.save('/etc/nacl/signer.key')

The libnacl library abstracts a "Dual Key" model. The Dual Key creates a single key management object that can be used for both signing and encrypting, it generates and maintains a Curve25519 encryption key pair and an ED25519 signing keypair. All methods for encryption and signing work with and from Dual Keys.

To encrypt messages using Dual Keys:

import libnacl.dual

# Define a message to send
msg = b"You've got two empty halves of coconut and you're bangin' 'em together."

# Generate the key pairs for Alice and bob, if secret keys already exist
# they can be passed in, otherwise new keys will be automatically generated
bob = libnacl.dual.DualSecret()
alice = libnacl.dual.DualSecret()

# Create the boxes, this is an object which represents the combination of the
# sender's secret key and the receiver's public key
bob_box = libnacl.public.Box(bob.sk, alice.pk)
alice_box = libnacl.public.Box(alice.sk, bob.pk)

# Bob's box encrypts messages for Alice
bob_ctxt = bob_box.encrypt(msg)
# Alice's box decrypts messages from Bob
bclear = alice_box.decrypt(bob_ctxt)
# Alice can send encrypted messages which only Bob can decrypt
alice_ctxt = alice_box.encrypt(msg)
aclear = alice_box.decrypt(alice_ctxt)

NOTE:

Every encryption routine requires a nonce. The nonce is a 24 char string that must never be used twice with the same keypair. If no nonce is passed in then a nonce is generated based on random data. If it is desired to generate a nonce manually this can be done by passing it into the encrypt method.

import libnacl.dual

fred = libnacl.dual.DualSecret()

raw_sk = fred.sk
hex_sk = fred.hex_sk()

raw_pk = fred.pk
hex_pk = fred.hex_pk()

import libnacl.dual

fred = libnacl.dual.DualSecret()
fred.save('/etc/nacl/fred.key')

One of the most powerful symmetric encryption models available i s known as AEAD. The libsodium library enables four models of AEAD encryption. As of libnacl 2.0 we expose 3 of them.

Using AEAD with libnacl is very easy and can be executed following the same models as the rest of libnacl.

The recommended algorithm to use is XChaCha20-Poly1305-IETF. Some organizations require the use of AES, in these cases please use AESGCM.

For more information on AEAD please see the libsodium documentation

Using the AEAD system is very easy.

import libnacl.aead

msg = b"Our King? Well i didn't vote for you!!"
aad = b'\x00\x11\x22\x33'
box = libnacl.aead.AEAD_XCHACHA()
ctxt = box.encrypt(msg, aad)

box2 = libnacl.aead.AEAD_XCHACHA(box.sk)
clear1 = box.decrypt(ctxt, len(aad))

ctxt2 = box2.encrypt(msg, aad)
clear3 = box.decrypt(ctxt2, len(aad))

The libnacl system comes with a number of utility functions, these functions are made available to make some of the aspects of encryption and key management easier. These range from nonce generation to loading saved keys.

import libnacl.utils

key_obj = libnacl.utils.load_key('/etc/keys/bob.key')

import libnacl.utils

key = libnacl.utils.salsa_key()

NOTE:

While these routines are perfectly safe, higher level convenience wrappers are under development to make these routines easier.

Public key encryption inside the nacl library has been constructed to ensure that all cryptographic routines are executed correctly and safely.

The public key encryption is executed via the functions which begin with crypto_box and can be easily executed.

First generate a public key and secret key keypair for the two communicating parties, who for tradition's sake, will be referred to as Alice and Bob:

import libnacl

alice_pk, alice_sk = libnacl.crypto_box_keypair()
bob_pk, bob_sk = libnacl.crypto_box_keypair()

Once the keys have been generated a cryptographic box needs to be created. The cryptographic box takes the party's secret key and the receiving party's public key. These are used to create a message which is both signed and encrypted.

Before creating the box a nonce is required. The nonce is a 24 character string which should only be used for this message, the nonce should never be reused. This means that the nonce needs to be generated in such a way that the probability of reusing the nonce string with the same keypair is very low. The libnacl wrapper ships with a convenience function which generates a nonce from random bytes:

import libnacl.utils
nonce = libnacl.utils.rand_nonce()

Now, with a nonce a cryptographic box can be created, Alice will send a message:

msg = 'Quiet, quiet.  Quiet!  There are ways of telling whether she is a witch.'
box = libnacl.crypto_box(msg, nonce, bob_pk, alice_sk)

Now with a box in hand it can be decrypted by Bob:

clear_msg = libnacl.crypto_box_open(box, nonce, alice_pk, bob_sk)

The trick here is that the box AND the nonce need to be sent to Bob, so he can decrypt the message. The nonce can be safely sent to Bob in the clear.

To bring it all together:

import libnacl
import libnacl.utils

alice_pk, alice_sk = libnacl.crypto_box_keypair()
bob_pk, bob_sk = libnacl.crypto_box_keypair()

nonce = libnacl.utils.rand_nonce()

msg = 'Quiet, quiet.  Quiet!  There are ways of telling whether she is a witch.'
box = libnacl.crypto_box(msg, nonce, bob_pk, alice_sk)

clear_msg = libnacl.crypto_box_open(box, nonce, alice_pk, bob_sk)

Sealed box is a variant of public key encryption scheme where the sender is not authenticated. This is done by generating an ephemeral key pair, which the public key is prefixed to the cipher text.

First, generate a keypair for the receiver. The sender doesn't need a keypair.

import libnacl

pk, sk = libnacl.crypto_box_keypair()

Then a sealed box is created by the sender, using the receiver's public key

msg = 'Quiet, quiet.  Quiet!  There are ways of telling whether she is a witch.'
box = libnacl.crypto_box_seal(msg, pk)

The receiver then can decrypt the box using their keypair.

clear_msg = libnacl.crypto_box_seal_open(box, pk, sk)

To bring it all together:

import libnacl

pk, sk = libnacl.crypto_box_keypair()

msg = 'Quiet, quiet.  Quiet!  There are ways of telling whether she is a witch.'
box = libnacl.crypto_box_seal(msg, pk)

clear_msg = libnacl.crypto_box_seal_open(box, pk, sk)

NOTE:

While these routines are perfectly safe, higher level convenience wrappers are under development to make these routines easier.

Secret key encryption is high speed encryption based on a shared secret key.

NOTE:

The means of encryption assumes that the two sides of the conversation both have access to the same shared secret key. First generate a secret key, libnacl provides a convenience function for the generation of this key called libnacl.utils.salsa_key, then generate a nonce, a new nonce should be used every time a new message is encrypted. A convenience function to create a unique nonce based on random bytes:

import libnacl
import libnacl.utils

key = libnacl.utils.salsa_key()
nonce = libnacl.utils.rand_nonce()

With the key and nonce in hand, the cryptographic secret box can now be generated:

msg = 'Who are you who are so wise in the ways of science?'
box = libnacl.crypto_secretbox(msg, nonce, key)

Now the message can be decrypted on the other end. The nonce and the key are both required to decrypt:

clear_msg = libnacl.crypto_secretbox_open(box, nonce, key)

When placed all together the sequence looks like this:

import libnacl
import libnacl.utils

key = libnacl.utils.salsa_key()
nonce = libnacl.utils.rand_nonce()

msg = 'Who are you who are so wise in the ways of science?'
box = libnacl.crypto_secretbox(msg, nonce, key)

clear_msg = libnacl.crypto_secretbox_open(box, nonce, key)

NOTE:

While these routines are perfectly safe, higher level convenience wrappers are under development to make these routines easier.

Signing messages ensures that the message itself has not been tampered with. The application of a signature to a message is something that is is automatically applied when using the public key encryption and is not a required step when sending encrypted messages. This document however is intended to illustrate how to sign plain text messages.

The nacl libs use a separate keypair for signing then is used for public key encryption, it is a high performance key signing algorithm called ed25519, more information on ed25519 can be found here: http://ed25519.cr.yp.to/

The sign messages first generate a signing keypair, this constitutes the signing key which needs to be kept secret, and the verify key which is made available to message recipients.

import libnacl

vk, sk = libnacl.crypto_sign_keypair()

With the signing keypair in hand a message can be signed:

msg = 'And that, my liege, is how we know the Earth to be banana-shaped.'
signed = libnacl.crypto_sign(msg, sk)

The signed message is really just the plain text of the message prepended with the signature. The crypto_sign_open function will read the signed message and return the original message without the signature:

orig = libnacl.crypto_sign_open(signed, vk)

Put all together:

import libnacl

vk, sk = libnacl.crypto_sign_keypair()

msg = 'And that, my liege, is how we know the Earth to be banana-shaped.'
signed = libnacl.crypto_sign(msg, sk)

orig = libnacl.crypto_sign_open(signed, vk)

The nacl library comes with sha256 and sha512 hashing libraries. They do not seem to offer any benefit over python's hashlib, but for completeness they are included. Creating a hash of a message is very simple:

import libnacl

msg = 'Is there someone else up there we could talk to?'
h_msg = libnacl.crypto_hash(msg)

crypto_hash defaults to sha256, sha512 is also available:

import libnacl

msg = 'Is there someone else up there we could talk to?'
h_msg = libnacl.crypto_hash_sha512(msg)

The nacl library comes with blake hashing libraries.

More information on Blake can be found here: https://blake2.net

The blake2b hashing algorithm is a keyed hashing algorithm, which allows for a key to be associated with a hash. Blake can be executed with or without a key.

With a key (they key can should be between 16 and 64 bytes):

import libnacl

msg = 'Is there someone else up there we could talk to?'
key = libnacl.randombytes(32)
h_msg = libnacl.crypto_generichash(msg, key)

Without a key:

import libnacl

msg = 'Is there someone else up there we could talk to?'
h_msg = libnacl.crypto_generichash(msg)

Thomas S Hatch

2024, Thomas S Hatch