libnacl - Man Page

Name

libnacl ā€” libnacl Documentation

Contents:

Public Key Encryption

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.

SecretKey Object

The SecretKey object is used to manage both public and secret keys, this object contains a number of methods for both convenience and utility. The key data is also available.

Keys

The raw public key is available as SecretKey.sk, to generate a hex encoded version of the key the sk_hex method is available. The same items are available for the public keys:

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()

By saving only the binary keys in memory libnacl ensures that the minimal memory footprint is needed.

PublicKey Object

To manage only the public key end, a public key object exists:

import libnacl.public

tom_secret = libnacl.public.SecretKey()

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

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

Saving Keys to Disk

All libnacl key objects can be safely saved to disk via the save method. This method changes the umask before saving the key file to ensure that the saved file can only be read by the user creating it and cannot be written to.

import libnacl.public

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

Sealed Box

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)

Creating Box

SealedBox instances can be created by supplying a public and private key. The private key is only required when decrypting.

The public key can be supplied as:

  • Instance of SecretKey, which supply both the public and private key.
  • Instance of PublicKey
  • Raw binary representation

Secret Key Encryption

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.

Signing and Verifying Messages

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)

Saving Keys to Disk

All libnacl key objects can be safely saved to disk via the save method. This method changes the umask before saving the key file to ensure that the saved file can only be read by the user creating it and cannot be written to.

import libnacl.sign

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

Dual Key Management

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.

DualKey Object

The DualKey object is used to manage both public and secret keys, this object contains a number of methods for both convenience and utility. The key data is also available.

Keys

The raw public key is available as DualKey.pk, to generate a hex encoded version of the key the pk_hex method is available:

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()

By saving only the binary keys in memory libnacl ensures that the minimal memory footprint is needed.

Saving Keys to Disk

All libnacl key objects can be safely saved to disk via the save method. This method changes the umask before saving the key file to ensure that the saved file can only be read by the user creating it and cannot be written to. When using dual keys the encrypting and signing keys will be saved togather in a single file.

import libnacl.dual

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

Authenticated Encryption with Associated Data

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))

Utility Functions

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.

Loading Saved Keys

After keys are saved using the key save method reloading the keys is easy. The libnacl.utils.load_key function will detect what type of key object saved said key and then create the object from the key and return it.

import libnacl.utils

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

The load_key and save routines also support inline key serialization. The default is json but msgpack is also supported.

Salsa Key

A simple function that will return a random byte string suitable for use in SecretKey encryption.

import libnacl.utils

key = libnacl.utils.salsa_key()

This routine is only required with the raw encryption functions, as the libnacl.secret.SecretBox will generate the key automatically.

Nonce Routines

A few functions are available to help with creating nonce values, these routines are available because there is some debate about what the best approach is.

We recommend a pure random string for the nonce which is returned from rand_nonce, but some have expressed a desire to create nonces which are designed to avoid re-use by more than simply random data and therefore the time_nonce function is also available.

Raw Public Key Encryption

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)

Raw Sealed Box Encryption

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)

Raw Secret Key Encryption

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 nacl library uses the salsa20 stream encryption cipher for secret key encryption, more information about the salsa20 cipher can be found here: http://cr.yp.to/salsa20.html

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)

Raw Message Signatures

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)

Raw Hash Functions

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)

Raw Generic Hash (Blake2b) Functions

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)

Release Notes

libnacl 1.0.0 Release Notes

This is the first stable release of libnacl, the python bindings for Daniel J. Bernstein's nacl library via libsodium.

NaCl Base Functions

This release features direct access to the underlying functions from nacl exposed via importing libnacl. These functions are fully documented and can be safely used directly.

libnacl 1.1.0 Release Notes

This release introduces the addition of high level classes that make using NaCl even easier.

High level NaCl

The addition of the high level classes give a more pythonic abstraction to using the underlying NaCl cryptography.

These classes can be found in libnacl.public, libnacl.sign and libnacl.secret.

Easy Nonce Generation

The new classes will automatically generate a nonce value per encrypted message. The default nonce which is generated can be found in libnacl.utils.time_nonce.

libnacl 1.2.0 Release Notes

This release introduces the DualKey class, secure key saving and loading, as well as enhancements to the time_nonce function.

Dual Key Class

Dual Keys are classes which can encrypt and sign data. These classes generate and maintain both Curve25519 and Ed25519 keys, as well as all methods for both encryption and signing.

Time Nonce Improvements

The original time nonce routine used the first 20 chars of the 24 char nonce for the microsecond timestamp (based on salt's jid), leaving 4 chars for random data. This new nonce uses far fewer chars for the timestamp by hex encoding the float of microseconds into just 13 chars, leaving 11 chars of random data. This makes the default nonce safer and more secure.

libnacl 1.3.0 Release Notes

This release removes the time_nonce function and replaces it with the rand_nonce function.

libnacl 1.3.1 Release Notes

Bring back a safe time_nonce function.

libnacl 1.3.2 Release Notes

Add detection of the libsodium.so.10 lib created by libsodium 0.6

libnacl 1.3.3 Release Notes

Fix issue and add tests for bug where saving and loading a signing key caused a stack trace, se issue #18

libnacl 1.3.4 Release Notes

  • Change the default ctype values to be more accurate and efficient
  • Update soname detection on Linux for libsodium 0.7.0
  • Make soname detection a little more future proof

libnacl 1.4.0 Release Notes

Blake Hash Support

Initial support has been added for the blake2b hash algorithm

Misc Fixes

  • Fix issue with keyfile saves on windows
  • Fix libsodium detection for Ubuntu manual installs and Windows dll detection

libnacl 1.4.1 Release Notes

Misc Fixes

  • Fix for crypto_auth_verify and crypto_auth_onetimeverify
  • Lint fixes and updates

libnacl 1.4.2 Release Notes

SecretBox key save and load

  • Add support to save and load SecretBox keys

libnacl 1.4.3 Release Notes

crypto_onetimeauth_verify fixes

  • Fix a call to the crypto_onetimeauth_verify routine into the right libsodium system
  • Add tests for crypto_onetimeauth_verify

Improved support for MacOSX

  • Improved the lookup procedure for finding libsodium on MacOSX

Add support for reading file streams for key loading

libnacl 1.4.4 Release Notes

Add pack_nonce options to secretbox

  • libnacl secretbox has been packing the nonce in each message, the new pack_nonce option allows for the nonce to be omitted which allows for more flexible options

Add soversion 17 detection

  • Added explicit soversion support for libsodium 17

Fix crypto_onetimeauth tests

  • The crypto onetimeauth test issues have been resolved

Remove tweetnacl Support

  • The tweetnacl support was never really tested, and since the tweetnacl api is not complete we have removed support for it

Add sodium_init calls

  • Added calls to sodium_init when the lib is loaded

libnacl 1.4.5 Release Notes

Set low end libsodium version to 0.5

  • libnacl will only function with libsodium 0.5 and above

Add soversion 18 detection

  • Added explicit soversion support for libsodium 18

libnacl 1.5.0 Release Notes

Add Built In libsodium.so Support

Added the ability to place a libsodium.so file in the libnacl python directory as a last resort fallback. To use this feature just copy your libsodium.so file to the same directory as the libnacl __init__.py file.

This was added to make total portability of the library easier.

Add bytes_eq

Added the bytes_eq function to allow better byte comparison

libnacl 1.5.1 Release Notes

Add Sealed Box Support

A big thanks to Manatsawin Hanmongkolchai for adding in support for libsodium Sealed Boxes!

Change Exception on Encrypt/Decrypt Failure

If encryption or decryption fails, CryptError is raised instead of ValueError. This might be a breaking change for your application. See #91 and #74.

libnacl 1.5.2 Release Notes

Add Support for AEAD AES and chacha20poly1305

Big thanks to Nicholas O'Brien for adding support for libsodium's AEAD encryption systems. The raw functions are all available to access libsodium directly along with the high level AEAD class that cleanly follows libnacl's key management model.

libnacl 1.6.0 Release Notes

Add Bindings for More Libsodium Function

Add bindings for crypto_box_seed_keypair() and crypto_scalarmult_base() Add bindings for crypto_box_easy() and crypto_box_open_easy() Add bindings for crypto_box_easy_afternm() and crypto_box_open_easy_afternm() Add bindings for crypto_sign_ed25519_keypair(), crypto_sign_ed25519_sk_to_pk() and crypto_sign_ed25519_sk_to_seed() Add bindings for crypto_sign_detached() and crypto_sign_verify_detached() Add bindings for crypto_sign_ed25519_pk_to_curve25519() and crypto_sign_ed25519_sk_to_curve25519()

Please Note The Exception Change From the 1.5.1 Release

If encryption or decryption fails, CryptError is raised instead of ValueError. This might be a breaking change for your application. See #91 and #74.

libnacl 1.6.1 Release Notes

Add support for libsodium 1.0.15

Make sure that libnacl runs correctly on the 1.0.15 release of libsodium

libnacl 1.7 Release Notes

Bindings for kdf in libsodium

Thanks to Michael Mendoza, PR #109

Added extra key validation

Thanks to Kent Ross, PR #106

Add Crypto_box_easy

Thanks to jheling PR #114

libnacl 1.7.1 Release Notes

This release fixes a few minor bugs, primarily in tests, and restores functionality with older versions of libsodium.

Compatibility With Older libsodium

PR #118 fixes compatibility with Debian 8.

Test Fixes

Some unreliability in tests were found by the Debian team. These issues were fixed in PRs #115 and #116.

Travis no longer supports the same pypy tests on all platforms, these were removed in PR #119.

libnacl 1.9.0 Release Notes

This release is a little overdue, it fixes a number of documentation issues and adds a few convenience features. It also migrates the build system to poetry and fixes the documentation build on readthedocs

libnacl 2.0.0 Release Notes

Add Support for AEAD and AEAD Classes

Added classes to the libnacl.aead module allowing for the use of XChaCha20-Poly1305-IETF, ChaCha20-Poly1305-IETF, and AES256-GCM.

libnacl 2.1.0 Release Notes

Add Support for the Key Exchange System

Added the libnacl.kx module. This module contains the ExchangeKey class.

The ExchangeKey class makes it easy to use AEAD encryption with an exchange key setup. The class works much like a sealed box but allows for the creation of the exchange keys.

This makes it very easy to set up a system using AEAD and exchange keys.

Fix issues with pyproject.toml

The 2.0.0 release introduced the use of poetry into libnacl, unfortunately I made a mistake in the pyproject.toml file. Thanks for @mgorny for catching the issue and getting a PR in.

  • Index
  • Module Index
  • Search Page

Author

Thomas S Hatch

Info

Jul 19, 2024 2.1.0