Paragon Initiative Enterprises Blog

The latest information from the team that develops cryptographically secure PHP software.

How to Safely Implement Cryptography Features in Any Application

Use libsodium. Use libsodium. Use libsodium. Use libsodium. Use libsodium. Use libsodium. Use libsodium.

Why not {Mcrypt, OpenSSL, Bouncy Castle, KeyCzar, etc.}?

These cryptography libraries are really building blocks that by and large must be used, with expert care, to build the interfaces you want developers to use. In most cases, libsodium is the interface you want developers to use.

I couldn't tell you how many projects I've found that are riddled with poor implementation choices (RSA/ECB/PKCS1, Rijndael256-ECB, plain AES-CBC without any message authentication, message corruption issues introduced by mcrypt's zero byte padding, timing attacks on the MAC validation that allow message forgery, etc.) that could have easily been avoided had developers only known they could just use libsodium and move on with their lives.

By default, these libraries don't provide authenticated encryption. Most of them force developers to use RSA (or ECDSA but certainly not EdDSA), which is hard to get right and for which index calculus attacks are improving each year.

Why not NaCl?

NaCl is fine, really. It's very secure and I don't want to take away from this fact at all, but I still don't recommend most people use it for one simple reason: Unless you're developing in C/C++ and only need to target a few Unix platforms, or you're developing in Python, NaCl isn't an option for you.

It might be tempting to fork NaCl and tweak it to work on your platform or expose bindings for NaCl in your programming language, at which point you're better off using libsodium which already did the work for you.

Libsodium is an NaCl fork with a 100% compatible API, extra features, and portability. If you're using libsodium, you're using NaCl too. If you're a PHP, Node.js, Ruby, C#, Java, iOS, Android, or Perl developer, libsodium is readily available while the original NaCl is not.

If NaCl is an option for you, by all means use NaCl.

What Makes Libsodium so Great?

As I said before, libsodium was forked from NaCl. NaCl is a library written by a team of cryptographers known for innovative research into elliptic curve cryptography and side-channel cryptanalysis (Dan Bernstein, Tanja Lange, and Peter Schwabe).

Libsodium, like NaCl before it, offers simple interfaces for strong and concise cryptography features. Every operation is carried out in constant-time; no branches or array index lookups are controlled by secret information (i.e. your encryption keys).

Unlike WebCrypto, which is a potluck of popular cryptography standards, chosen by committee, libsodium's cryptographic primitives and constructions were carefully selected with a clear statement of their security properties for real-world software applications. Despite its emphasis on security, libsodium out-performs the NIST standards.

Want to encrypt a message to your friend using a shared secret key? Just use crypto_secretbox().

Don't have a shared secret but have your friend's public key? You want crypto_box().

Reasons Not to Use Libsodium

  1. FIPS compliance prevents you from using it. (Our condolences.) Update: Libsodium now has AES-256-GCM (as of 1.0.4), which is one step closer to FIPS compliance.
  2. The bindings for libsodium do not yet exist in your language.
  3. Strong cryptography is illegal in your country.
  4. Stringent requirements to maintain interoperability with weak cryptography.

How do I get started with Libsodium?

For PHP developers, we maintain the libsodium PHP extension documentation, which should help developers understand how to use these features in detail.

For developers in other languages, check out the libsodium documentation to see if bindings exist for your language, then consult the documentation for your specific language (if it exists).


Just use libsodium.

Quick note about elliptic curve public key cryptography: In general, ECDSA is harder to get right than EdDSA. EdDSA requires no random elements and is easier to implement without side-channels. Many standardized ECDSA curves are not twist-secure. If you'd like to know more, the team behind NaCl did a great talk at the 31st annual Chaos Communications Congress titled, A Gentle Introduction to Elliptic Curve Cryptography.

About the Author

Scott Arciszewski

Chief Development Officer

With 15 years of software development, application security, and system administration experience, Scott aspires to help others attain a happier work-life balance by solving difficult problems and automating trivial tasks. He is mostly known in the community for his open source software security research and strong progressive positions on providing tools and frameworks that are secure by default. @CiPHPerCoder

Need Technology Consultants?

Will tomorrow bring costly and embarrassing data breaches? Or will it bring growth, success, and peace of mind?

Our team of technology consultants have extensive knowledge and experience with application security and web/application development.

We specialize in cryptography and secure PHP development.

Let's Work Together Towards Success

Our Security Newsletters

Want the latest from Paragon Initiative Enterprises delivered straight to your inbox? We have two newsletters to choose from.

The first mails quarterly and often showcases our behind-the-scenes projects.

The other is unscheduled and gives you a direct feed into the findings of our open source security research initiatives.

Quarterly Newsletter   Security Announcements