@nibyou/crypto

Nibyou's crypto package is a wrapper around the WebCrypto and specifically the SubtleCrypto APIs. This package proides easily reusable functions around the cryptography used by Nibyou.

For client support, see caniuse.

Zero dependencies, 100% test coverage!

Usage

Install the package using npm or yarn.

Import the crypto functions:

import * as ncrypto from '@nibyou/crypto';

Asymmetric encryption

This library uses RSA-OAEP with SHA-256 and 4096 bit keylength in accordance with the current recommendations by the BSI.

Keys are exchanged headless, so the differenciation between public and private keys has to be made in the business logic.

Key handling

Generate a new RSA Key Pair:

const keyPairAlice: CryptoKeyPair = await ncrypto.generateKeyPair();

generateKeyPair() accepts an optional parameter extractable: boolean (set to true by default) that controls whether or not the keys can be exported using below functions.

Export the Public and Private key into Base64 (SPKI and PKCS #8 respectively):

const spki: string = await ncrypto.exportPublicKey(keyPairAlice.publicKey);
const pkcs8: string = await ncrypto.exportPrivateKey(keyPairAlice.privateKey);

Import Public and Private keys into CryptoKey objects again:

const publicKey: CryptoKey = await ncrypto.importPublicKey(spki);
const privateKey: CryptoKey = await ncrypto.importPrivateKey(pkcs8);

These functions accept an optional parameter extractable: boolean (set to false by default) that controls whether or not the keys can be exported again.

Encryption

To encrypt a message you need another public key, lets call this one keyPairBob.

const keyPairBob: CryptoKeyPair = await ncrypto.generateKeyPair();

A message can either be a string or an object, during encryption, objects will be converted into JSON strings.

const message = 'Guten Tag, Bob!';

The encryption function encryptRSA expects the data (in this case message) and a public key (in this case keyPairBob.publicKey).

const cipherText = await ncrypto.encryptRSA(message, keyPairBob.publicKey);

The resulting value will be an RSAEncryptionResult object containing the cipher text in its data property.

console.log(cipherText.data); // => 'aenc:AKV9xVMHFSCa2yIwOjCwvpP1UkSbLaqqMu49Tg2CWDXk9xsi5MiArQwmJrrfdKqyfJ3Fag7/9AS+TX4RnHqIxKX26WKgH7EKwdnRTjB9X/PbKOOfNLmq4T/K2CSr+y9n1iJbIOyQpvfnCOFIaIwmQ8CKVTKyrcGcOF8GBdJpujlqSENaD3Q16B4yW4G5M6kSnImnRebHtqhayRk5o84Omj6l4wXGyhqoT/yxD7wlet1nSuZTqU2U3JTfOvoFjYferHPTnEpo38uUWq09fbOoEI3vNBn/UiPN7MoA7uWufNOECvtDxuJty6frbTwvmzj9ZHfwdhy55x21MLXzctJUbw=='

All data encrypted with encryptRSA starts with the aenc prefix.

Decryption

To decrypt the previous message, you need Bob's private key.

Similar to the encryption function, decryptRSA expects the data (in this case cipherText.data) and the corresponding private key (in this case keyPairBob.privateKey).

const secretMessage = await ncrypto.decryptRSA(cipherText.data, keyPairBob.privateKey);
console.log(secretMessage); // => 'Guten Tag, Bob!';

Symmetric encryption

@nibyou/crypto supports AES-GCM-256 with random, 96 bit initialization vectors.

Key handling

Generate a new AES key:

const key: CryptoKey = await ncrypto.generateKey();

generateKey() accepts an optional parameter extractable: boolean (set to true by default) that controls whether or not the key can be exported using below function.

Export the key into raw Base64 format:

const raw: string = await ncrypto.exportKey(key);

Import raw format keys into CryptoKeys

const reImport: CryptoKey = await ncrypto.importKey(raw);

Encryption

You can use the generated key to encrypt data the same way it's done with RSA:

const encrypted = await ncrypto.encryptAES("Hallo, wie geht's denn so?", key);
console.log(encrypted.data); // => 'senc:26AsDbeclttMdQUHTXumWrTrg3ZEb+en0qU=.pUE96B4D8mhYetFP'

Notice the format: the data is prefixed with senc, and contains the ciphertext and initialization vector, joined with a dot.

Decryption

The same key can then decrypt the encrypted message:

const decrypted: string = await ncrypto.decryptAES(encrypted, key);
console.log(decrypted); // => 'Hallo, wie geht's denn so?'

Key derivation

Lastly, this package also supports deriving PBKDF2 keys from strings with 64 bit salts:

const randomUserInput = 'ThisIsASuperSecurePassword';
const derivedKey: CryptoKey = await ncrypto.deriveKey(randomUserInput);

The function supports passing iterations: number = 10000 and salt: string as optional second and third parameter. This allows for deterministic key generation (e.g. encrypting a User's private key with their password as input and email as salt).

The key can then be used in other AES operations.

Testing

To test this library, you can run the tests with npm test or yarn test.

Test Coverage

| Statements | Branches | Functions | Lines | | --------------------------- | ----------------------- | ------------------------- | ----------------- | | | | | |

License

This library is licensed under the GPL Version 3 license. See LICENSE.