js-libp2p-crypto/README.md

200 lines
6.3 KiB
Markdown
Raw Normal View History

# js-libp2p-crypto
2016-05-19 18:47:48 +02:00
[![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](http://ipn.io)
[![](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](http://ipfs.io/)
[![](https://img.shields.io/badge/freenode-%23ipfs-blue.svg?style=flat-square)](http://webchat.freenode.net/?channels=%23ipfs)
[![standard-readme compliant](https://img.shields.io/badge/standard--readme-OK-green.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)
2016-09-11 12:55:41 -04:00
[![Coverage Status](https://coveralls.io/repos/github/libp2p/js-libp2p-crypto/badge.svg?branch=master)](https://coveralls.io/github/libp2p/js-libp2p-crypto?branch=master)
[![Travis CI](https://travis-ci.org/libp2p/js-libp2p-crypto.svg?branch=master)](https://travis-ci.org/libp2p/js-libp2p-crypto)
[![Circle CI](https://circleci.com/gh/libp2p/js-libp2p-crypto.svg?style=svg)](https://circleci.com/gh/libp2p/js-libp2p-crypto)
[![Dependency Status](https://david-dm.org/libp2p/js-libp2p-crypto.svg?style=flat-square)](https://david-dm.org/libp2p/js-libp2p-crypto)
[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/feross/standard)
![](https://img.shields.io/badge/npm-%3E%3D3.0.0-orange.svg?style=flat-square)
![](https://img.shields.io/badge/Node.js-%3E%3D4.0.0-orange.svg?style=flat-square)
[![Sauce Test Status](https://saucelabs.com/browser-matrix/ipfs-js-libp2p-crypto.svg)](https://saucelabs.com/u/ipfs-js-
libp2p-crypto)
2016-05-19 18:47:48 +02:00
> Crypto primitives for libp2p in JavaScript
This repo contains the JavaScript implementation of the crypto primitives
needed for libp2p. This is based on this [go implementation](https://github.com/libp2p/go-libp2p-crypto).
2016-05-19 18:47:48 +02:00
## Table of Contents
- [Install](#install)
- [Usage](#usage)
- [Example](#example)
- [API](#api)
- [`hmac`](#hmac)
- [`create(hash, secret, callback)`](#createhash-secret-callback)
- [`digest(data, callback)`](#digestdata-callback)
- [`aes`](#aes)
- [`create(key, iv, callback)`](#createkey-iv-callback)
- [`encrypt(data, callback)`](#encryptdata-callback)
- [`encrypt(data, callback)`](#encryptdata-callback)
- [`webcrypto`](#webcrypto)
- [`keys`](#keys)
- [`generateKeyPair(type, bits, callback)`](#generatekeypairtype-bits-callback)
- [`generateEphemeralKeyPair(curve, callback)`](#generateephemeralkeypaircurve-callback)
- [`keyStretcher(cipherType, hashType, secret, callback)`](#keystretcherciphertype-hashtype-secret-callback)
- [`marshalPublicKey(key[, type], callback)`](#marshalpublickeykey-type-callback)
- [`unmarshalPublicKey(buf)`](#unmarshalpublickeybuf)
- [`marshalPrivateKey(key[, type])`](#marshalprivatekeykey-type)
- [`unmarshalPrivateKey(buf, callback)`](#unmarshalprivatekeybuf-callback)
- [Contribute](#contribute)
- [License](#license)
## Install
```sh
npm install --save libp2p-crypto
```
## Usage
### Example
```js
const crypto = require('libp2p-crypto')
crypto.generateKeyPair('RSA', 2048, (err, key) => {
})
```
2016-05-19 18:47:48 +02:00
## API
2016-05-19 20:18:31 +02:00
### `hmac`
Exposes an interface to the Keyed-Hash Message Authentication Code (HMAC) as defined in U.S. Federal Information Processing Standards Publication 198. An HMAC is a cryptographic hash that uses a key to sign a message. The receiver verifies the hash by recomputing it using the same key.
#### `create(hash, secret, callback)`
- `hash: String`
- `secret: Buffer`
- `callback: Function`
##### `digest(data, callback)`
- `data: Buffer`
- `callback: Function`
### `aes`
Expoes an interface to AES encryption (formerly Rijndael), as defined in U.S. Federal Information Processing Standards Publication 197.
This uses `CTR` mode.
#### `create(key, iv, callback)`
- `key: Buffer` The key, if length `16` then `AES 128` is used. For length `32`, `AES 256` is used.
- `iv: Buffer` Must have length `16`.
- `callback: Function`
##### `encrypt(data, callback)`
- `data: Buffer`
- `callback: Function`
##### `encrypt(data, callback)`
- `data: Buffer`
- `callback: Function`
### `webcrypto`
Depending on the environment this is either an instance of [node-webcrypto-ossl](https://github.com/PeculiarVentures/node-webcrypto-ossl) or the result of `window.crypto`.
### `keys`
### `generateKeyPair(type, bits, callback)`
2016-05-19 20:18:31 +02:00
- `type: String`, only `'RSA'` is currently supported
- `bits: Number` Minimum of 1024
- `callback: Function`
2016-05-19 21:45:43 +02:00
Generates a keypair of the given type and bitsize.
### `generateEphemeralKeyPair(curve, callback)`
- `curve: String`, one of `'P-256'`, `'P-384'`, `'P-521'` is currently supported
- `callback: Function`
Generates an ephemeral public key and returns a function that will compute the shared secret key.
Focuses only on ECDH now, but can be made more general in the future.
Calls back with an object of the form
2016-05-20 12:50:16 +02:00
```js
{
key: Buffer,
genSharedKey: Function
}
```
### `keyStretcher(cipherType, hashType, secret, callback)`
2016-05-20 15:55:19 +02:00
- `cipherType: String`, one of `'AES-128'`, `'AES-256'`, `'Blowfish'`
- `hashType: String`, one of `'SHA1'`, `SHA256`, `SHA512`
- `secret: Buffer`
- `callback: Function`
2016-05-20 15:55:19 +02:00
Generates a set of keys for each party by stretching the shared key.
Calls back with an object of the form
2016-05-20 15:55:19 +02:00
```js
{
k1: {
iv: Buffer,
cipherKey: Buffer,
macKey: Buffer
},
k2: {
iv: Buffer,
cipherKey: Buffer,
macKey: Buffer
}
}
```
### `marshalPublicKey(key[, type], callback)`
2016-05-19 21:45:43 +02:00
- `key: crypto.rsa.RsaPublicKey`
- `type: String`, only `'RSA'` is currently supported
Converts a public key object into a protobuf serialized public key.
### `unmarshalPublicKey(buf)`
- `buf: Buffer`
Converts a protobuf serialized public key into its representative object.
### `marshalPrivateKey(key[, type])`
- `key: crypto.rsa.RsaPrivateKey`
- `type: String`, only `'RSA'` is currently supported
Converts a private key object into a protobuf serialized private key.
### `unmarshalPrivateKey(buf, callback)`
2016-05-19 21:45:43 +02:00
- `buf: Buffer`
- `callback: Function`
Converts a protobuf serialized private key into its representative object.
2016-05-19 21:45:43 +02:00
## Contribute
Feel free to join in. All welcome. Open an [issue](https://github.com/libp2p/js-libp2p-crypto/issues)!
This repository falls under the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md).
[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/contributing.md)
## License
[MIT](LICENSE)