cwi-crypto
This module provides a common implementation for standard cryptographic utilities, ciphers, IV management, low-level promitives and operations.
Exported Functions
| Names | Description |
|---|---|
encrypt and decrypt |
Symmetric AES-GCM encryption with a 32-byte prepended IV and support for data encoded as a Uint8Array or a string |
XOR |
Bitwise Exclusive-OR between two Uint8Arrays of equal length |
keyFromString |
Derives a CryptoKey from a string with PBKDF2 using a sane iteration count and the given salt |
API
encrypt(plaintext: Uint8Array|string, key: CryptoKey, returnType: string) => ciphertext: Uint8Array|string
Encrypts the given plaintext with the given key. Returns the ciphertext.
Parameters
| Name | Description |
|---|---|
| plaintext | The data to encrypt. May be a String or a Uint8Array |
| key | The CryptoKey object to use for the encryption operation |
| returnType | A string indicating the desired return type. May be either string (default) or Uint8Array |
Return Value
The function will either return a string or a Uint8Array representing the ciphertext, depending on the value of returnType.
decrypt(ciphertext: Uint8Array|string, key: CryptoKey, returnType: string) => plaintext: Uint8Array|string
Decrypts the given ciphertext with the given key. Returns the plaintext.
Parameters
| Name | Description |
|---|---|
| ciphertext | The data to decrypt. May be a String or a Uint8Array |
| key | The CryptoKey object to use for the decryption operation |
| returnType | A string indicating the desired return type. May be either string (default) or Uint8Array |
Return Value
The function will either return a string or a Uint8Array representing the plaintext, depending on the value of returnType.
keyFromString({ string: String, salt: Uint8Array }) => key: CryptoKey
Derives a suitable CryptoKey from the password string with PBKDF2 and the given salt.
Parameters
| Name | Description |
|---|---|
| string | The password string to use |
| salt | a Uint8Array representing the password salt to use |
Return Value
The function will return a CryptoKey object representing the derived key.
XOR(k1: Uint8Array, k2: Uint8Array) => result: Uint8Array
Performs a bitwise exclusive OR operation with the given data. Returns the result. Inputs must be the same length.
Parameters
| Name | Description |
|---|---|
| k1 | A Uint8Array representing the first input to XOR |
| k2 | A Uint8Array representing the second input to XOR |
Return Value
The function will return a Uint8Array containing the output data.
Testing
While this is not a React application, the react-scripts package is used for testing. I tried to get Jest to work on its own with the Web Cryptography API, TextEncoder and TextDecoder, but
was unable to find a suitable configuration. If anyone can get the tests to pass with only Jest, please feel free to create a pull request.
Adequate testing practices for use in a critical production application should be observed at all times for this library.
License
The license for the code in this repository is the Open BSV License.