DEV Community: Smoen

Secure and easy use of Cryptography in NodeJS with FluentCrypto

Smoen — Fri, 15 Nov 2019 10:47:34 +0000

In the previous article we discussed the challenges that developers encounter while working with cryptography APIs, using an example. We have shown that getting the code running is a non-trivial task and neither is making it secure. FluentCrypto aims to mitigate these problems by providing a wrapper for the Node Crypto API.

Let us revisit the example from the last article. In the end, Matt's code looked like this:

Rewritten with FluentCrypto, the code now looks like this:

This code has the same functionality as the original code, but is a lot shorter and more secure!

1- Easy key generation

On line 3 the FluentCrypto module has created a key of the correct length for the chosen algorithm from our environment variable.

2- Automatic creation of the initialization vector

Over the next lines, an encryption object is created (line 5) which is then told to use a cipher with a certain algorithm (line 6) and then provided with the configurations and data in a straightforward way. In the background, an initialization vector of correct length for our chosen algorithm is created. Since you will want to store the initialization vector for long term usage, FluentCrypto provides getters for every configuration as can be seen below.

//retrieve iv from encrypter for storage
const iv = encrypter.getIV();
storeIV(iv);

3 - Simple decryption

To decrypt with FluentCrypto, the encryption object itself can be used. The module creates the decryption object with the matching attributes (line 14). This feature is meant to be used with objects that are still available in memory. Of course, if the encryption object would not be available anymore or if you want to perform the decryption on another machine, then you would want to set the key, algorithm and iv similarly to the encryption object.

4- Throwing errors on insecure usage

If we run this code, it will result in an exception, but that’s actually a good thing. As mentioned in the last article, the algorithm we chose is not considered secure. Therefore, FluentCrypto will throw the following error: “AlgorithmNotAllowed: des is not allowed here. Use one of aes-128-cbc, aes-128-gcm, aes-192-cbc, aes-192-gcm, aes-256-cbc, aes-256-gcm”. The error message explains what the problem is and how it can be solved.
After following the instruction, the code looks like this:

No more error is thrown. Compared with the Node Crypto API example, we didn't have to do any concatenation or set any encodings to make it work. FluentCrypto did this work for us. It also provided us with some quality of life improvements, such as setting the key and initialization vector on the decryption object from the encryption object. Additionally, we can feel safe that this code is actually considered secure. Otherwise, an error would have been thrown.

How does FluentCrypto work?

FluentCrypto is a wrapper around the Node Crypto API based on the Fluent Interface pattern. This pattern is based on method chaining with methods named so that a chain of method calls reads like normal language. Well known examples for this are jQuery or the visualisation library D3. Using this pattern gives the users a better understanding on what they are doing and what they should do next.

For the structure of the API, small possible cryptographic tasks, such as “Set a key” and “Select an algorithm” were identified. For each of these tasks, an API call was then created that solves the task. FluentCrypto users can identify the calls they want to make from the tasks they want to solve, making it easier to solve cryptographic tasks.

The other main part of FluentCrypto is making sure that what the user wants to do is secure and notifying the user if it is not. A key point is the error message being helpful. An error message should give the user a clear understanding of what went wrong, where it went wrong, why it went wrong and possibly how he could fix it. To achieve this, FluentCrypto uses CryRule files. CryRule is a small, domain-specific language that has been developed for the FluentCrypto project and is basically a rulefile. It states which cryptographic concepts/methods (Hash, Cipher, etc.) can use which algorithms, it can forbid certain algorithms or put further constraints on certain algorithm choices.

CryRule follows a whitelisting approach, meaning that every configuration that is not listed is considered insecure. The CryRule file used for the example earlier looks like this:

In this example, the algorithm choice for ciphers is constrained to the list on line 3. Furthermore, some constraints concerning the iv and key are defined for certain algorithms.

These rule files are read and parsed at runtime by a parser developed with the Chevrotain library. Chevrotain allows one to easily define grammars and parsers for domain-specific languages such as CryRule.

Revisiting our example, Matt wanted to use the algorithm “des”. As can be seen on line 3, this algorithm is not whitelisted, therefore an error is thrown. This error uses the whitelisted list to also suggest the user a different algorithm.

Another usage of the rule file are defaults. Since every listed configuration is considered secure, a default taken from such a file is a secure and sensible choice. Again revisiting our example, we do not provide a configuration for an initialization vector. FluentCrypto then uses a default value taken from the rules, where length 16 (bytes) is listed for our chosen algorithm (aes-128-cbc).

A big advantage of these rule files is that security experts can read and write them without needing any knowledge about JavaScript. Even knowledge about the Node Crypto API itself is rather optional for the experts.
This also relieves the developers and maintainers of a project such as FluentCrypto, since they do not need to worry about their cryptography knowledge.

In conclusion, this prototype allows us to solve the same tasks as the Node Crypto API while providing us with some quality of life improvements, making our code easier to read and understand while also making it more secure.

Limitations and future work

FluentCrypto is only a prototype, a proof of concept. The rule files are currently not written by an expert and the API covers only a small part of the whole Node Crypto API. FluentCrypto also only covers local development and does not support developers in network tasks such as key exchanges in its current state. Future resources should be invested in covering more of the API and making sure that the rule files are written by experts. The CryRule language already satisfies most futures needs of cryptographic rules and is open to future extensions. The same holds for the FluentCrypto API itself. But first, the concept needs to prove itself. Evaluation is currently running (see the next section if you are interested in participating) and has not yet concluded, but the first feedback is promising.

Evaluation

To evaluate the prototype, we are carrying out a survey. During this survey, the developers are asked several questions about their background to test their background knowledge about cryptography and NodeJS. Then they are asked to solve three basic tasks with both the Node Crypto API and the FluentCrypto prototype. Their subjective feedback as well as their written code will then serve to evaluate the usage and usefulness of FluentCrypto. If you are interested in participating, please follow one of the following links:

Survey with File Upload (Google Account required)

Survey without File Upload (No Account required)

Once the evaluation has concluded, a follow-up article will be posted with the result.

A glimpse into the challenges of working with Cryptography APIs in NodeJS

Smoen — Fri, 15 Nov 2019 10:42:41 +0000

One of the main reasons that lead to insecure NodeJS applications is insecure or bad usage of cryptography APIs. Developers who are not very familiar with such APIs and the underlying crypto concepts often struggle to choose secure configuration options or to even get their code up and running.

This article assumes readers are familiar with the following concepts:

(Cryptographic) key: A key is a piece of information that is used to encrypt and decrypt data and can either be stand-alone (for symmetric encryption, meaning both the encryption and decryption are performed with the same key) or part of a key-pair where the private key is used to encrypt data and the corresponding public key is used to decrypt this data (Read more).
Initialization vector: (Ideally) A random number that prevents repetition in data encryption (Read more in this blog post or on the stackoverflow website).
Salt: A salt is a random piece of data that is used during encryption to ensure that the same input does not always result in the same output. Read more about what a cryptographic salt is and what the difference from an iv is.
Cipher: An algorithm that encrypts and decrypts data following a certain protocol.

Let's start with an example:

Matt is a developer for a mid-sized company and has not yet gained much experience with cryptography. He has learned some concepts and read about the pros and cons of certain algorithms for cryptography, but when it comes to applying them, he is still a beginner. Now his project leader has assigned him a task that requires encryption. The task is something like this: "We should keep every text message in the system confidential. Encrypt them for storage so we can decrypt them later when needed. We need this cryptography feature asap".

Matt starts with a Google search and reads some Stack Overflow posts that point him towards the Cipher object in the Crypto module.
Most cipher algorithms use two pieces of information, namely a secret key and an initialization vector (iv). Matt opens his editor and starts writing the following JS code:

In the first few lines, the key is retrieved from an environment variable, a buffer is created to serve as iv and the cipher algorithm is chosen. Next, the cipher object is created and then updated with data that should be encrypted. The call on line 12 finalizes the encryption and stores the result in a variable. To decrypt this data, a decipher object is created using the same algorithm, key and iv. This decipher object is then updated with the encrypted data and again the decryption is finalized with the (once again) unencrypted data stored in a variable.

This will most certainly not run without error, but result in an 'invalid key length error'. Cipher algorithms that use a key to encrypt data require a key of a certain length, depending on which cipher algorithm was chosen. After a bit of research, Matt finds out that the key must have the same length as the block length of the algorithm. Sometime later, he finds the scryptSync function that derives a key of a specific length from a password and a random salt. He then adjusts his key and gets to this:


const key = crypto.scryptSync(process.env.PRIVATE_KEY, 'salt', 16);

Now the cipher will work. Matt stores the encrypted result and tests the decryption, which yields the following error:
'error:06065064:digital envelope routines:EVP_DecryptFinal_ex:bad decrypt'
An experienced user knows that the error occurs because he did not concatenate the results from the update calls. This led to the data being of a wrong length to be decrypted correctly. However, to the inexperienced Matt, this looks like gibberish and will give him a headache for some time.
Finally, Matt will find out that he has to concatenate all results from the update and the final call and adjusts his code accordingly:

Unfortunately, Matt receives a new error:
' error:0606506D:digital envelope routines:EVP_DecryptFinal_ex:wrong final block length'.
After doing some research he finds that by default the input on the update function gets treated as a buffer, but Matt is using strings. He then also realizes that he can set the encoding of the input and the desired output to tell NodeJS to both treat the input as a string and return a string with the given encoding. After adjusting, the code finally works and looks like this:

On line 3, the key is derived from an environment variable, a salt and the desired length. Then a buffer of length 16 bytes is allocated to be used as iv and the algorithm to be used for the encryption is specified. The cipher is then created and updated with the data that should be created. Since the encodings are set, the data inputs are treated as strings before and after the encryption. After the final call Matt receives the encrypted data stored in a variable. Later, the decipher object is created and updated with the encrypted data. The encodings are then set again to ensure that the data is treated correctly. After the final call, Matt retrieves the decrypted data stored in a variable.

Finally, the cryptography feature seems to work, but is it secure?
The short answer is NO: the salt is in plain text and not random, the initalization vector is not random either, there are more secure algorithms than des, and so on. However, Matt has already spent too much time on solving the challenges that come with getting cryptographic code to work.

It would have been much easier if he could have just told the API that he wants to encrypt data and then decrypt it later, without having to search for a (secure) algorithm, without having to understand how long the key and the iv have to be, and with more useful error messages when something goes wrong.
In the next article we discuss how FluentCrypto will make this possible.