# cwi-crypto

> Common implementations for standard cryptographic utilities

Latest version **0.1.8** (published 2023-12-10) · Open BSV License license · 0 weekly downloads

## Install

```sh
npm install cwi-crypto
pnpm add cwi-crypto
yarn add cwi-crypto
bun add cwi-crypto
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.8 |
| Published | 2023-12-10 |
| First published | 2022-09-06 |
| Weekly downloads | 0 |
| License | Open BSV License |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 135.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Peer-to-Peer Privacy Systems Research LLC |
| Maintainers | tonesnotes, braydude, tyeverett |

## Links

- npm: https://www.npmjs.com/package/cwi-crypto
- Repository: https://github.com/p2ppsr/cwi-crypto
- Homepage: https://github.com/p2ppsr/cwi-crypto#readme
- Issues: https://github.com/p2ppsr/cwi-crypto/issues
- npm.io page: https://npm.io/package/cwi-crypto

## Dependencies (1)

- [cwi-array-encoding](https://npm.io/package/cwi-array-encoding.md) ^0.1.11

## Recent versions

- 0.1.8 (latest) — 2023-12-10
- 0.1.7 — 2023-12-09
- 0.1.6 — 2023-12-08
- 0.1.5 — 2023-12-08
- 0.1.3 — 2022-12-27
- 0.1.1 — 2022-09-06

## README

# 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.

---
_Source: https://npm.io/package/cwi-crypto · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._