docs: update the docs

This commit is contained in:
Friedel Ziegelmayer 2016-09-26 14:39:59 +02:00
parent 08c5df5e79
commit 6ebc408f73
3 changed files with 122 additions and 80 deletions

121
API.md Normal file
View File

@ -0,0 +1,121 @@
# API
## `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)`
- `type: String`, only `'RSA'` is currently supported
- `bits: Number` Minimum of 1024
- `callback: Function`
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
```js
{
key: Buffer,
genSharedKey: Function
}
```
## `keyStretcher(cipherType, hashType, secret, callback)`
- `cipherType: String`, one of `'AES-128'`, `'AES-256'`, `'Blowfish'`
- `hashType: String`, one of `'SHA1'`, `SHA256`, `SHA512`
- `secret: Buffer`
- `callback: Function`
Generates a set of keys for each party by stretching the shared key.
Calls back with an object of the form
```js
{
k1: {
iv: Buffer,
cipherKey: Buffer,
macKey: Buffer
},
k2: {
iv: Buffer,
cipherKey: Buffer,
macKey: Buffer
}
}
```
## `marshalPublicKey(key[, type], callback)`
- `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)`
- `buf: Buffer`
- `callback: Function`
Converts a protobuf serialized private key into its representative object.

View File

@ -21,13 +21,6 @@ needed for libp2p. This is based on this [go implementation](https://github.com/
- [Usage](#usage)
- [Example](#example)
- [API](#api)
- [`generateKeyPair(type, bits, cb)`](#generatekeypairtype-bits-cb)
- [`generateEphemeralKeyPair(curve)`](#generateephemeralkeypaircurve)
- [`keyStretcher(cipherType, hashType, secret)`](#keystretcherciphertype-hashtype-secret)
- [`marshalPublicKey(key[, type])`](#marshalpublickeykey-type)
- [`unmarshalPublicKey(buf)`](#unmarshalpublickeybuf)
- [`marshalPrivateKey(key[, type])`](#marshalprivatekeykey-type)
- [`unmarshalPrivateKey(buf)`](#unmarshalprivatekeybuf)
- [Contribute](#contribute)
- [License](#license)
@ -50,78 +43,7 @@ crypto.generateKeyPair('RSA', 2048, (err, key) => {
## API
### `generateKeyPair(type, bits, cb)`
- `type: String`, only `'RSA'` is currently supported
- `bits: Number`
- `cb: Function`
Generates a keypair of the given type and bitsize.
### `generateEphemeralKeyPair(curve)`
- `curve: String`, one of `'P-256'`, `'P-384'`, `'P-521'` is currently supported
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.
Returns an object of the form
```js
{
key: Buffer,
genSharedKey: Function
}
```
### `keyStretcher(cipherType, hashType, secret)`
- `cipherType: String`, one of `'AES-128'`, `'AES-256'`, `'Blowfish'`
- `hashType: String`, one of `'SHA1'`, `SHA256`, `SHA512`
- `secret: Buffer`
Generates a set of keys for each party by stretching the shared key.
Returns an object of the form
```js
{
k1: {
iv: Buffer,
cipherKey: Buffer,
macKey: Buffer
},
k2: {
iv: Buffer,
cipherKey: Buffer,
macKey: Buffer
}
}
```
### `marshalPublicKey(key[, type])`
- `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)`
- `buf: Buffer`
Converts a protobuf serialized private key into its representative object.
See [API.md](API.md)
## Contribute

View File

@ -6,7 +6,6 @@ const c = require('./crypto')
exports.hmac = c.hmac
exports.aes = c.aes
exports.rsa = c.rsa
exports.webcrypto = c.webcrypto
const keys = exports.keys = require('./keys')