jedisct1 / libsodium-doc

Gitbook documentation for libsodium

The Sodium crypto library (libsodium)

Sodium is a modern, easy-to-use software library for encryption, decryption, signatures, password hashing, and more.

It is a portable, cross-compilable, installable, and packageable fork of NaCl, with a compatible but extended API to improve usability even further.

Its goal is to provide all of the core operations needed to build higher-level cryptographic tools.

Sodium is cross-platform and cross-language. It runs on many compilers and operating systems, including Windows (with MinGW or Visual Studio, x86 and x86_64), iOS, and Android. JavaScript and WebAssembly versions are also available and fully supported. Furthermore, bindings for all common programming languages are available and well-supported.

The design choices emphasize security and ease of use. But despite the emphasis on high security, primitives are faster across-the-board than most implementations.

Downloading libsodium

libsodium 1.0.20-stable is the latest version.

• Tarballs and pre-compiled binaries
• GitHub repository
• Documentation

Mailing list

A mailing list is available to discuss libsodium.

To join, just send a random email to sodium-subscribe {at} pureftpd{dot}org.

License

ISC license.

See the LICENSE file for details.

Thanks!

Sodium is developed by volunteers. We would like to especially thank the following companies and organizations for their contribution:

• Paragonie Initiative Enterprise, who donated a Raspberry Pi to ensure that the library works perfectly on this hardware. Thanks!
• Private Internet Access, who sponsored a complete security audit. This is amazing, thanks!
• Maximilian Blochberger and Joshua Small, who both generously donated $100. This will help cover the infrastructure costs a lot. Thanks again, Max and Joshua!

People who designed the primitives and wrote implementations the library is based on can be found in the AUTHORS file. This project wouldn’t exist without them.

Also, a huge “thank you” to people and companies who contributed bindings for their favorite programming languages. A list can be found in the THANKS file.

Another huge “thank you” to package maintainers who have been doing an amazing job at building packages for many distributions and operating systems.

Finally, thanks to you for reading this documentation and for the awesome projects you are going to build with this library!

libsodium-doc's Issues

what does 'nm' in '_beforenm / __afternm standand for?

https://download.libsodium.org/doc/public-key_cryptography/authenticated_encryption.html

Update TFC URL and description

Thanks for listing the project! The currently listed URL and description are as follows:

https://github.com/maqp/tfc-nacl

Tinfoil Chat NaCl: TFC-NaCl is a high
assurance encryption plugin for the Pidgin IM client.

---

Stuff has changed since then and TFC is now more or less standalone, the current URL and description are:

https://github.com/maqp/tfc
Tinfoil Chat - Onion-routed, endpoint secure messaging system

Comparison of different hash functions and authentication codes

Great docs! One thing that I think could be clarified:

There are 4 functions that I am having trouble figuring out the difference between:

• crypto_auth / crypto_auth_verify
• crypto_generichash
• crypto_shorthash
• crypto_onetimeauth / crypto_onetimeauth_verify

I can see 3 potential uses for this set of functions:

• hash tables / bloom filters
  • Here, I think it's clear that crypto_shorthash is the winner, because it is no worse than any of the other options, and is the most performant of the group.
• creating unique identifiers for arbitrarily long data
  • Here, crypto_shorthash and crypto_onetimeauth are ineligible due to collisions, and crypto_auth has worse performance
• message authentication
  • This is where I get confused. In the docs, there are 4 use cases that I don't know how to tell apart:
    • integrity checking in interactive protocols (described as use case for crypto_shorthash)
    • file integrity checking (described as use case for crypto_generichash)
    • one-time authentication (as per crypto_onetimeauth)
    • secret-key authentication (as per crypto_auth)

I don't see the difference between the different use cases I've categorized as "message authentication." I guess the one place I see a comparison drawn in the docs is where crypto_onetimeauth is described as ineligible for large messages. Otherwise, I don't see why I shouldn't (for example) use crypto_auth for file integrity checking, or crypto_generichash for secret-key authentication.

I'd love to see either a dedicated section comparing these 4 types of "message authentication," or to have the doc section for each function include a brief comparison to each of the other 3. Example questions to answer:

• Are there performance tradeoffs?
• Security tradeoffs?
• Why is one ok for one application but not for others?

I think having these sort of comparisons in the documentation would be in line with the overall awesomeness that is libsodium: here are the dozen crypto primitives you need to care about, and here's how you know which one to use.

Terminology

It is my understanding that the accepted terminology for a key pair in public key (asymmetric) cryptography is public key and private key. It seems that you instead used public key and secret key. This will be confusing to users because your section on symmetric cryptography is called "secret key cryptography". Your docs also conflate the two kinds of keys, e.g.

This high-level API encrypts a sequence of messages, or a single message split into an arbitrary number of chunks, using a secret key

in a reference to a symmetric key and

Using Alice's public key and his secret key, Bob can compute the exact same shared secret key.

in reference to an asymmetric private key.

This is very unfortunate. It seems to have seeped into constants as well, e.g. crypto_box_SECRETKEYBYTES. Thus it is probably too late to change.

pwhash_str_verify: Is `passwd` really required to be null-terminated?

For now, the documentation on crypto_pwhash_str_verify() states that the
password string argument passwd must be zero-terminated:

int crypto_pwhash_str_verify(const char str[crypto_pwhash_STRBYTES],
                             const char * const passwd,
                             unsigned long long passwdlen);
...
str and passwd have to be zero-terminated.

But why do we need to zero-terminate passwd?

Since crypto_pwhash_str_verify knows the exact length of passwd (we
pass it as the third argument), it makes little sense to require it. In fact,
as far as I inspected the code, it just works fine without any null-termination.

My current opinion is that the manual is somewhat confused and misdescribing
the parameter, thus we would better update it. But what do you think about it?

Note

The description in question is introduced by 47e5915.

download.libsodium.org website bug

I've been experiencing an issue with this content displayed at download.libsodium.org. The first page loads fine, and the first link in the side navigation also loads fine. From that point on clicking the links in the side navigation does not do anything, and refreshing the browser results in a 404 page.

The same content displayed at https://jedisct1.gitbooks.io/libsodium/content/ does not have this problem. This link was found by "John Q NotSoPublic" on the GRC SQRL newsgroups, who has confirmed the same issue.

Sodium is a very well structured and thought out library, but having an issue like this on the main website could put people off using it. To begin with I thought the 404 pages meant that most of the sites pages where missing, which is not actually the case.

Suggestion: Specify values of constants

Since the constants for functions are listed in the documentation, I think it would be beneficial if the values of the constants were listed there as well, so the information is centralised in one place. For example:

Constants

• crypto_aead_xchacha20poly1305_ietf_KEYBYTES = 32
• crypto_aead_xchacha20poly1305_ietf_NPUBBYTES = 24
• crypto_aead_xchacha20poly1305_ietf_ABYTES = 16

I appreciate that this would be annoying to update if you had to change anything, but surely these values never get amended for most functions.

Key commitment approach could be simplified?

@jackloomen wrote:

https://github.com/jedisct1/libsodium-doc/blob/master/secret-key_cryptography/aead.md#robustness

Prepend H(key, nonce || ciphertext_tag) to the ciphertext

By including ciphertext_tag in the equation it may give a false sense of security in the approach, H(key, nonce) is sufficient to > commit to the key. ciphertext_tag adds nothing. Bypassing it would require changing the prepended segment regardless.

It is also wasteful compared to:

Prepend 128 or 256 zero-bits to payload prior to encryption, verify their presence on decryption.
Which achieves the same objective.

Typo in the description of "Authenticated encryption"

In the description of "Authenticated encryption" is the following sentence:

"A single key is used both to encrypt/sign and verify/decrypt messages. For this reason, it is critical to keep the key confidential."

sign implies non-repudiation, which is not the case with authenticated encryption, it should be replaced by authenticate in the description.

crypto_box_easy return value undocumented

Hi, here is a simple one,

The function crypto_box_open_easy() has the following documentation:
The function returns -1 if the verification fails, and 0 on success. On success, the decrypted message is stored into m.

But there is no specific mention of crypto_box_easy()'s return value.

It is implied it returns an error number in the example at the top, but it would also be nice to know what could go wrong during crypto_box_easy() (and it's sibling functions).
I do like that the compiler warned me that I didn't check the result of crypto_box_detached() - I would like to see warnings attached to all of the functions that return error messages!

This lack of this kind of specific documentation is in a few places throughout,
for example, on the same page,
crypto_box_keypair() returns an int, but it is not documented anywhere whether the caller should check the result.
And in this case, the example code does not check the return result.
crypto_box_keypair(alice_publickey, alice_secretkey);

So in this case, I can't tell whether I should be checking the result or not.

It would be good to do an audit to ensure all functions that return a value have that return value documented.

Thanks for the great library and documentation!

Key rotation on secretbox

Hi! I have been looking at how to do key rotation on PRF based symmetric constructs like thesecretbox, without revealing the plaintext.

You would verify the auth tag, use a new key and nonce to calculate a new subkey, encrypt the old ciphertext with the new subkey and then decrypt the new ciphertext with the old subkey (due to XOR being associative), and have the resulting ciphertext be encrypted with the new subkey. After the message has been "rekeyed" a new auth tag can be calculated.

One thing I'm unsure of is if there are some subtle issues with the above and what merits never revealing the plaintext has, if any? Is there a threat model where it is okay to have the keys in memory, but not the plaintext (even mprotected memory)

Explanation of the bin_len parameter in sodium_hex2bin?

I was wondering if an explanation of the bin_len parameter of sodium_hex2bin could be added to the Helpers page as we're left in the dark as to why there's both a bin_maxlen as well as a bin_len parameter without any explanation of the difference thereof.

randombytes_keygen reference

Hi,

I cannot seem to find any reference in the code to the randombytes_keygen function even though its listed here in the docs. Am I missing something?

Thanks!

AEAD robustness implementation examples

From the Robustness section for AEAD constructions:

If that turns out to be a concern, this can be solved in different ways:

• By incorporating a key identifier in the nonce
• By including a key identifier in the additional data
• By including a 128-bit fixed string in the message and verifying it during the decryption process

The third bullet point is very clear. However, it's less clear how to create a key identifier for the first and second bullet point implementations. The papers on the subject are rather confusing if you're not used to the notation. Please could you explain a suitable method of generating a key identifier in the documentation. Thank you.

Clarifying secretstream robustness

Libsodium's secretstream construction always authenticates an extra all-zero (minus 8 bits for the tag) block to ensure robustness.

I'd like to ask how large the secretstream all-zero block is for ensuring robustness (as mentioned here).

By including a 128-bit fixed string in the message and verifying it during the decryption process

Furthermore, where has the 128-bit fixed string figure come from? I had a glance at this paper and that seemed to suggest the padding fix could vary depending on the encryption algorithm, but I may be reading that incorrectly.

Many thanks!

Do crypto_pwhash_str* functions have password length requirements like crypto_pwhash?

Hi there, I'm going through the documentation for crypto_pwhash_str and crypto_pwhash_str_verify.

I noticed that crypto_pwhash requires passwdlen to be between PASSWD_MIN and PASSWD_MAX. crypto_pwhash_str and crypto_pwhash_str_verify don't mention if there's a minimum/maximum length for passwdlen, I just wanted to check on that.

Happy to update the docs and open a PR

Question

Hello,

I am trying to link Sodium static using in visual studio.
I have add the lib and the sodium.h but when i run the the test :

int main()
{

if (sodium_init() == -1) {
	return 1;
}
std::cout << "Hello World!\n"; 

}

I have a message from linker unsolved extern. I have updated the path to the lib in my config.

any help on that ?

Thank you

Clarifying the new AEAD robustness solution

In the AEAD Robustness section, the interactive protocol explanation is a lot better now, but the new non-interactive protocol solution isn't very clear. In this commit you wrote H(k, nonce || ciphertext_tag) and mentioned using HMAC. However, I saw that you then changed the example to H(key || nonce || ciphertext_tag) and now mention BLAKE2. This raises two questions:

1. Is this meant to be a MAC? I presume the answer is yes considering that HMAC is still listed, but that format suggests that it's just an unkeyed hash.
2. If so, where does the key for the MAC come from? Unless the suggestion is to use the same key for the MAC and the AEAD, but then why would the key have to be concatenated with the nonce and ciphertext_tag as well? Plus implementing it in that way would probably get some criticism due to the key reuse.

I believe it would be beneficial to answer these questions in the documentation. There's a lot of confusion about this topic, and that's not surprising when it seems to be underdocumented and not explained in layman's terms anywhere, which seems to be a common problem in the field of cryptography. This page has to be the best summary currently available, but there's still some room for improvement.

Finally, just out of curiosity, what was the reasoning behind removing the padding fix suggestion? Was it due to potential timing attacks? It seems to be the most discussed fix in papers on the topic, and it's also easy to implement.

Missing documentation for crypto_secretbox_*

The commit c09f468 doesn't include the file secretbox.md. The documentation of method crypto_secretbox_* isn't available in https://download.libsodium.org/doc/secret-key_cryptography/authenticated-encryption.

Can you commit the missing file ?

Status of the roadmap

Yo!

How up-to-date is the roadmap rendered here? I check it from time to time while waiting for XEdDSA support and noticed that the last update was four months ago. Are you having a development pause or are you focussing on other issues rather than new features?

what does 'nm' in _beforenm / __afternm means?

https://download.libsodium.org/doc/public-key_cryptography/authenticated_encryption.html

it looks like crypto_box_curve25519xsalsa20poly1305_beforenm() is doing a curve25519 ECDH key exchange/scalarmult, but what does 'nm' means ? it looks confusing.