Hey!

Thanks for the interest in Lockbox. Please note that this project is still in the early phases of development. Whilst the concept of simple encryption for use in applications will not change, the implementation is almost certain to at this point.

In particular, the switch will probably be made in the near future from public key encryption to symmetric encryption. If you're looking for a good public-key based solution, perhaps take a look at PGP.

Lockbox by Eloquent

Lockbox is the simplest possible way to implement strong two-way encryption for use in applications. Lockbox uses a combination of well-established technologies to ensure the safety of data.

Lockbox = Simple, strong encryption.

Lockbox libraries

Why use Lockbox?

Avoiding poor choices

Encryption is a complicated subject. The are a myriad of options to choose from when deciding on an encryption scheme: algorithms, key sizes, modes, padding schemes, and encodings. Knowing what choices to make can be daunting even with a decent knowledge of cryptography.

Lockbox removes the burden of overwhelming choice. There is no configuration; Lockbox simply works in the best possible way straight out of the box.

Cross-platform compatibility

Anyone who's ever attempted to encrypt data in one language, and decrypt it in another, can explain how much of an arduous task it can be. Encryption must work exactly, byte-for-byte, the same across platforms in order to be compatible.

Libraries for Lockbox are available in multiple languages. Any combination of these libraries will work together flawlessly without any extra effort on the developer's part.

Excellent portability

Storage and/or transmission of encrypted data can pose problems of its own. Usually, the ciphertext produced by an encryption algorithm contains data that cannot be represented as a 'normal' string of text. This raw data is easily misinterpreted, and hence corrupted, by databases and other systems that may have to handle the data. The most common solution to this issue is to encode the data using something like Base64 encoding; but even Base64 causes issues for URIs and file names.

Lockbox uses a variant of Base64 designed specifically to address these issues. It's almost impossible to accidentally corrupt the data produced by Lockbox.

Public-key flexibility

Public-key cryptography allows for more flexible usage than symmetric cryptography. Encryption requires only the public key, but decryption requires access to the private key. This means that the public key can be published without compromising security. The practical upshot is that data can be securely shared without an initial secured exchange of secret keys.

Lockbox implements a public-key encryption system, allowing the developer to harness these features if they are required.

Standard key format support

Different platforms have differing levels of support for certain key formats. For example, Java has no built-in support for the default PEM format keys produced by OpenSSL. Lockbox fills in the gaps in support, and uses the same key format across all platforms, which allows for extremely simple key management.

Design goals for Lockbox

To utilize extremely strong encryption.
To use existing, well-vetted, open standards where possible.
To be completely transparent. That is, encryption and subsequent decryption produces the exact same data as the original, byte-for-byte.
To be able to detect decryption failures.
To be able to encrypt data of any length, including empty strings.
To produce ciphertext that is as portable as possible (able to be transmitted across many protocols without need for additional encoding).
To make integration as simple as possible across many languages and platforms.
To eliminate the need for configuration.

How does Lockbox actually work?

Lockbox with keys

Lockbox uses OpenSSL with PEM formatted keys, and is similar in operation to the PHP functions openssl_seal() and openssl_open().

Where Lockbox differs, is in its use of AES-256 instead of RC4 as the secondary encryption algorithm. In addition, Lockbox includes data verification steps that allow unsuccessful decryption to be detected.

Encryption process

Some data and an RSA public key are passed to Lockbox.
A random 256-bit key and 128-bit initialization vector (IV) are generated from a cryptographically secure source.
The generated key and IV are concatenated together and encrypted with the public key using RSA encryption and OAEP padding (with SHA-1 as the hash function and MGF1 as the mask generation function) in electronic codebook mode.
A SHA-1 hash of the supplied data is concatenated to the end of the data.
The data and hash are encrypted using the generated key and IV and AES encryption and PKCS #7 padding (also known as PKCS #5 padding) in cipher block chaining mode.
The encrypted key and IV, and the encrypted data and hash are concatenated together.
This concatenation of encrypted data is then encoded using Base64 with a URI and filename safe alphabet.
This encoded data is returned as the final ciphertext.

Decryption process

Some ciphertext and an RSA private key are passed to Lockbox.
The ciphertext is decoded using Base64 with a URI and filename safe alphabet.
The first n bits of the ciphertext are extracted, where n is the size of the private key; this extracted data is the encrypted key and initialization vector.
The remaining bits of the ciphertext are extracted as the encrypted data.
The encrypted key and IV from step 3 are decrypted with the private key using RSA encryption and OAEP padding (with SHA-1 as the hash function and MGF1 as the mask generation function) in electronic codebook mode.
The first 256 bits of the decrypted data are extracted as the key.
The next 128 bits of the decrypted data are extracted as the IV.
The encrypted data from step 4 is decrypted using the recovered key and IV from steps 6 and 7, and AES encryption with PKCS #7 padding (also known as PKCS #5 padding) in cipher block chaining mode.
The last 160 bits of the unpadded data are the verification hash.
The unpadded data before this point is considered the final data.
If the verification hash matches the SHA-1 hash of the final data, the final data is returned, otherwise decryption has failed.

Reference keys

All test vectors use the following keys:

2048-bit key

4096-bit key

Test vectors

All test vector values below are expressed as US-ASCII encoded strings, except the key names which are references to the relevant test key. Newlines are added only for readability, and do not make up part of the value.

Note that the RSA encrypted portion of the ciphertext will be different each time because it utilizes a random seed. Therefore, for the 2048-bit key, only the ciphertext after the 342^nd byte is guaranteed to be the same for all ciphertext. For the 4096-bit key, only the ciphertext after the 684^th byte is guaranteed to be the same for all ciphertext.

Key:                <2048-bit key>
Data:               <empty>
Generated key:      12345678901234567890123456789012
Generated IV:       1234567890123456
Example ciphertext: QJyn73i2dlN_V9o2fVLLmh4U85AIEL5v
                    Cch2sP5aw3CogMBn5qRpokg6OFjRxsYB
                    xb_Oqe8n9GALxJsuuqyZgWXxSK0exA2P
                    QnAECIcujG9EyM4GlQodJiJdMtDJh0Dd
                    frp7s87w7YWgleaK_3JVqEpjRolj1AWr
                    DjXeFDl_tGIZ1R95PD2mbq6OUgm1Q56M
                    CRLZdZJOm3yixcGHQOV2wv73YIbOvOa8
                    hEZ7ydX-VRHPMmJyFgUe9gv8G8sDm6xY
                    UEz1rIu62XwMoMB4B3UZo_r0Q9xCr4sx
                    BVPY7bOAp6AUjOuvsHwBGJQHZi3k665w
                    mShg7pw8HFkr_Fea4nzimditNTFRhW3K
                    MfhqusPDqWJ7K37AvEHDaLULPKBNj24c

Key:                <2048-bit key>
Data:               1234
Generated key:      12345678901234567890123456789012
Generated IV:       1234567890123456
Example ciphertext: MFq4hhLJN8_F6ODUWX20tO4RIJURlMHA
                    mdujFMTyqc2Y3zHIXzmaK4CcoThggqZX
                    44-4kbhjwk9ihwuzS4GAQuSCCdoh5xzT
                    WfeboPu6zE51BrZQdz67VavvmvpHVdGg
                    oQcSsa_GiZcc7aBYh-AhfCyHrPb-r1hN
                    y_AWXv8hcO8mIS1fJ3Mvtr3Xxfwlydrn
                    23YUwuOG-tX4FctKqh2eFFkrht53ZwVv
                    7q67U3x774KjbUpB4LbML6APxe4ucghl
                    DpY_A_DFLH2GlvvouVaT3jCibkY_yIMC
                    1lNSBIdgpKGoAoZWy4bIpqDUu0SiLvDO
                    mclpPRARakRr15F21a_MQ9wL_JNwnG1u
                    T1zKZNgUcr2GaWk31ahOBKB0lfr-E7W2

Key:                <2048-bit key>
Data:               1234567890123456
Generated key:      12345678901234567890123456789012
Generated IV:       1234567890123456
Example ciphertext: oFqfBVNvWyUYThQiA54V_Lpx6Ka2zqEF
                    QCQBxcYhnbG2uuShACbf3I31USwRCFDV
                    mBLmfcO4ReMJFQzen-tRRuapOQ4Pjzdp
                    IRw_T9wYjj0n3Sjs1NZnDbN3hbHCmXoq
                    sl0byi0Lr5hwhmqOCj7Po5ey4EsPpuqb
                    tPx38PPae-zOlnMrdYuKhV8jIMDSsslf
                    VWMOgUlYnDOt9Pd1NEJkJE-GxYIYyzPB
                    _NtxwQf5moDjsNzxtx5fzEejo8BGDQ5Q
                    phjkQCBmMWd1fKN3Z3aBSNn_WS2HwxzU
                    gl10lzaHityP9iZU2DY8qkQB_wSk7-pf
                    h05CITq0DPIOHDQzVkcWlnuUZ55SZL-E
                    BpxoZDMH74B7GmHK66rSGH0MoSGY1fZC
                    hAWyjRKa0nWslBVkLoJRUg

Key:                <4096-bit key>
Data:               1234567890123456
Generated key:      12345678901234567890123456789012
Generated IV:       1234567890123456
Example ciphertext: rqA8g_yyA0eeLoun6rqnUxgy3JnIS9p8
                    bAgZYf4774ZahHcFCOozwWbMU_0HVMS9
                    sOlAmr-dQl6RqDaOLfAxrHq3mluFSlXf
                    gcJXrvPtf27u_4NCHXuwm825ptpmprPx
                    wl0z4tz6u-fqNBSfQuHApZ3MvAGsEa0v
                    b0IftBX0q8tKL6sdCx6WpTGcynEdxLcZ
                    Tx6cM4LRdcjL3SQZ5vk4VF69lS2r1WgJ
                    h8eUa_VwgsqhTkoc7wJAECqxHBQSh6q-
                    GOt6bpVnlaGkM_BfcrB5SJdtcEZd5BgG
                    xG8QwQGwsT60jErxpd5rYLfBrG7kgVse
                    yksfN-99-kUHQpkwCIS_zS5bpr3hLpBi
                    UhSA4638Xgd2qyAZCgl3OBY56HSdncZq
                    5o4xGycM69eN5hb-c852W-dP6S49BXSn
                    3OpmEOkZoIeNw0EYHpLLpfaLwafIVdLC
                    bQZX1g_szDcBDyyM-PN5-jnuaqySRywF
                    rMj56U9vAvwtFMaHKY-ll4Qxf8PgoDWM
                    7KogGgkztlZ0ZzaMwBLQeTDpjbNl5NXJ
                    CxobJfGv8w6zQZmDz8J2K3DsQrDmZid_
                    W6Gtsv7XsSnY-gl6TD4IkK1VEKnttqXa
                    PfVdCNadtQ-Z1INiK2pa3F0NKs4POO-K
                    PpW68kQ5l2qeUAVv6B-QdcwunyMh9XO_
                    vGx8Wf8SrbZ7lGeeUmS_hAacaGQzB--A
                    exphyuuq0hh9DKEhmNX2QoQFso0SmtJ1
                    rJQVZC6CUVI