Skip to content

Latest commit

 

History

History
120 lines (99 loc) · 6.86 KB

README.md

File metadata and controls

120 lines (99 loc) · 6.86 KB
Raw

Secure Compatible Encryption Examples

This repository was created to address the ever-growing number of poor encryption code examples that float about the internet. This repository will expand over time to include examples in more languages.

As of April 2021, there are 18 different compatible examples for 15 different languages across 5 different platforms.

Algorithms

  • Encryption: AES-128-GCM
  • Key Deriviation: PBKDF2
  • PBKDF2 Underlying Hash: SHA-256

AES with a 128-bit key was chosen due to the Java Unlimited Strength Policy that requires key sizes of no more than 128-bits due to cryptography export laws. While the examples are shown using AES-128, they can be trivially changed to 256-bit AES by changing the ALGORITHM_KEY_SIZE (and in some cases, ALGORITHM_NAME) parameter.

Compatibility

Every example shown here is compatible across platforms and/or languages. The result of encryptString in any language can be decrypted by decryptString in any language. Please do not submit pull requests for examples that are not compatible with the existing examples.

Methods

Each example exposes 4 methods with signatures that are roughly equivalent to the following:

  • string encryptString(plaintext: string, password: string)
  • string decryptString(ciphertext: string, password: string)
  • byte[] encrypt(plaintext: byte[], key: byte[])
  • byte[] decrypt(ciphertext: byte[], key: byte[])

As is expected, the encrypt and decrypt methods operate on and return raw binary data. The *string methods, however, take string parameters and return base64 encoded strings. The password parameter is fed through PBKDF2 first. password can be of any length but key must be 128-bits in length. You can change the AES key size by adjusting the ALGORITHM_KEY_SIZE parameter, and in some examples, the ALGORITHM_NAME parameter too.

NOTE: Because of the use of PBKDF2, the binary vs string methods are not compatible.

Dependencies

Language Version Tested Dependencies Notes
Java Java 8 JRE
Kotlin Java 8 JRE
JavaScript (Node) NodeJS 8.4.0 Tested on 8.4.0, but supported in versions as early as 4.0.0
JavaScript (Browser) Requires base64-js Uses the WebCrypto API, ensure browser support before using this example.
JavaScript (SJCL) Requires the Stanford JavaScript Crypto Library Doesn't run asynchronously.
Go Go 1.9 golang.org/x/crypto/pbkdf2 Tested on 1.9 but supported in earlier versions.
Python v3.6.4 Requires PyCryptodome No support for Python 2.
Ruby v2.4.4 Uses the OpenSSL Gem
Visual Basic .NET .NET 4.5 Requires BouncyCastle.
C# .NET 4.5 Requires BouncyCastle.
C Requires OpenSSL libssl-dev Uses SCEE.h header file.
C++ Requires C++11 Compiler Requires OpenSSL libssl-dev Wrapper for the C example. Requires SCEE.h and SCEE_cpp.h
Objective-C Requires OpenSSL libssl-dev Wrapper for the C example. Requires SCEE.h and SCEE_objc.h
Rust v1.30.0 Requires the ring v0.13.2 and base64 v0.9.3 crates
Swift Swift 4.0 Requires SwiftGCM. Must use a bridge for CommonCrypto.
PHP Requires PHP 7 Uses random_bytes which requires PHP 7.
Perl Perl 5 Requires CryptX

Test Vectors

The following ciphertexts are the results of encryptString using the given password. If your implementation can encryptString and decryptString using the code you've written, and can also decryptString the ciphertexts below to the same given result, then it is suitable for inclusion in this repository. Recall that, due to a randomly generated salt and nonce, the following are not expected outputs for encryptString, they are for testing decryptString only.

Ciphertext Password Plaintext
CqjxsXq6Y5ebtW6w98UQfgwdOpaCCkCy0l1qK5gJfhZnKVhp4+OuvxoiigHi8mO1R8CAyl5t DTY62mV2Cv XCbJbjd72q
VtHh3Z6jqJpIDK0yLe4+/UNpxqBqcmaiJWmaecb7qfCyOlAcVJ973zBNM51VCup5UTuVlu3H Pl4WODjq4k SOJHSCm4qR
SNQHdWnlcmJELLKewNTxBhzmJ1U+ChqKK5Kdvd/FSKssHW5b8y8SOrNVHdm78JUAYpGKlEUD BZO8PUEysY NYzd53moLT
5EmCwwSWj6YYgxBlld6DFW8I+QXCWxz5g/laEwUYV/DuoCGvxbW4ZlMd1Tsj4N07WbBOhIJU OziaxPFGYh vW1Qjb30mt
7miUNuhjJPAlbIHYKA2v/iBH3aplFF0pGw6HQAD5tKluh/1M69MLQ9xIkVcGfTr0CycsTFLU gkLDY5mmzT 9z19eFctoZ
0iqwbC8/1YvTsl2dog6aXaGfXVypsv1BcbnDE06C7nl9REITn3NW18+ZUmc= Empty String Empty String

C Example

The C example requires a bit more effort to understand and use properly due to varying buffer sizes with regard to base64 padding. The example below shows how to use crypt_string_get_length to determine what buffer size you will need to allocate to store the result.

#include "SCEE.h"
#include <stdio.h>

int main(int argc, char* argv[]) {

    // Our plaintext and password.
    unsigned char plaintext[] = "Hello, World!";
    unsigned char password[] = "OddShapelyOak7332";

    // Make enough space for our ciphertext.
    // Note that scee_crypt_string_get_length will give us the size of the buffer we
    // need INCLUDING the null character.
    size_t ct_length = scee_crypt_string_get_length(strlen(plaintext), SCEE_CRYPT_ENCRYPT);
    unsigned char ciphertext[ct_length];

    // Encryption.
    // The operation places the null character at the end of the buffer for us.
    int r = scee_encrypt_string(plaintext, strlen(plaintext), password, strlen(password), ciphertext);
    if (r != SCEE_OK) { return 1; }

    // Output for Encryption.
    printf("Ciphertext Buffer Size: %zu\n", ct_length);
    printf("Ciphertext strlen     : %zu\n", strlen(ciphertext));
    printf("Ciphertext            : %s\n\n", ciphertext);

    // Make enough space for our plaintext again.
    // Note that because of base64 padding, scee_crypt_string_get_length will
    // usually tell us that we need more space than we do.  We can get the
    // actual length of the plaintext after we decrypt.
    size_t pt_max_length = scee_crypt_string_get_length(strlen(ciphertext), SCEE_CRYPT_DECRYPT);
    size_t pt_actual_length;
    unsigned char plaintext2[pt_max_length];

    // Decryption.
    // The operation places the null character at the end of the buffer for us.
    r = scee_decrypt_string(ciphertext, strlen(ciphertext), password, strlen(password), plaintext2, &pt_actual_length);
    if (r != SCEE_OK) { return 1; }

    // Output for Decryption.
    printf("Plaintext Buffer Size: %zu\n", pt_max_length);
    printf("Plaintext Actual Size: %zu\n", pt_actual_length);
    printf("Plaintext strlen     : %zu\n", strlen(plaintext));
    printf("Plaintext            : %s\n\n", plaintext);

    return 0;
}