@libp2p/crypto 2.0.6-d5ef1c91 → 2.0.7-051154dd

package/README.md

@@ -1,5 +1,3 @@
-# @libp2p/crypto <!-- omit in toc -->
-
 [![libp2p.io](https://img.shields.io/badge/project-libp2p-yellow.svg?style=flat-square)](http://libp2p.io/)
 [![Discuss](https://img.shields.io/discourse/https/discuss.libp2p.io/posts.svg?style=flat-square)](https://discuss.libp2p.io)
 [![codecov](https://img.shields.io/codecov/c/github/libp2p/js-libp2p.svg?style=flat-square)](https://codecov.io/gh/libp2p/js-libp2p)
@@ -7,45 +5,13 @@
 
 > Crypto primitives for libp2p
 
-## Table of contents <!-- omit in toc -->
-
-- [Install](#install)
-  - [Browser `<script>` tag](#browser-script-tag)
-- [Lead Maintainer](#lead-maintainer)
-- [Usage](#usage)
-  - [Web Crypto API](#web-crypto-api)
-- [API](#api)
-  - [`crypto.aes`](#cryptoaes)
-    - [`crypto.aes.create(key, iv)`](#cryptoaescreatekey-iv)
-      - [`decrypt(data)`](#decryptdata)
-      - [`encrypt(data)`](#encryptdata)
-  - [`crypto.hmac`](#cryptohmac)
-    - [`crypto.hmac.create(hash, secret)`](#cryptohmaccreatehash-secret)
-      - [`digest(data)`](#digestdata)
-  - [`crypto.keys`](#cryptokeys)
-  - [`crypto.keys.generateKeyPair(type, bits)`](#cryptokeysgeneratekeypairtype-bits)
-  - [`crypto.keys.generateEphemeralKeyPair(curve)`](#cryptokeysgenerateephemeralkeypaircurve)
-  - [`crypto.keys.keyStretcher(cipherType, hashType, secret)`](#cryptokeyskeystretcherciphertype-hashtype-secret)
-  - [`crypto.keys.marshalPublicKey(key, [type])`](#cryptokeysmarshalpublickeykey-type)
-  - [`crypto.keys.unmarshalPublicKey(buf)`](#cryptokeysunmarshalpublickeybuf)
-  - [`crypto.keys.marshalPrivateKey(key, [type])`](#cryptokeysmarshalprivatekeykey-type)
-  - [`crypto.keys.unmarshalPrivateKey(buf)`](#cryptokeysunmarshalprivatekeybuf)
-  - [`crypto.keys.import(encryptedKey, password)`](#cryptokeysimportencryptedkey-password)
-  - [`privateKey.export(password, format)`](#privatekeyexportpassword-format)
-  - [`crypto.randomBytes(number)`](#cryptorandombytesnumber)
-  - [`crypto.pbkdf2(password, salt, iterations, keySize, hash)`](#cryptopbkdf2password-salt-iterations-keysize-hash)
-- [Contribute](#contribute)
-- [API Docs](#api-docs)
-- [License](#license)
-- [Contribution](#contribution)
-
-## Install
+# Install
 
 ```console
 $ npm i @libp2p/crypto
 ```
 
-### Browser `<script>` tag
+## Browser `<script>` tag
 
 Loading this module through a script tag will make it's exports available as `Libp2pCrypto` in the global namespace.
 
@@ -53,260 +19,7 @@ Loading this module through a script tag will make it's exports available as `Li
 <script src="https://unpkg.com/@libp2p/crypto/dist/index.min.js"></script>
 ```
 
-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).
-
-## Lead Maintainer
-
-[Jacob Heun](https://github.com/jacobheun/)
-
-## Usage
-
-```js
-const crypto = require('libp2p-crypto')
-
-// Now available to you:
-//
-// crypto.aes
-// crypto.hmac
-// crypto.keys
-// etc.
-//
-// See full API details below...
-```
-
-### Web Crypto API
-
-The `libp2p-crypto` library depends on the [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) in the browser. Web Crypto is available in all modern browsers, however browsers restrict its usage to [Secure Contexts](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts).
-
-**This means you will not be able to use some `libp2p-crypto` functions in the browser when the page is served over HTTP.** To enable the Web Crypto API and allow `libp2p-crypto` to work fully, please serve your page over HTTPS.
-
-## API
-
-### `crypto.aes`
-
-Exposes an interface to AES encryption (formerly Rijndael), as defined in U.S. Federal Information Processing Standards Publication 197.
-
-This uses `CTR` mode.
-
-#### `crypto.aes.create(key, iv)`
-
-- `key: Uint8Array` The key, if length `16` then `AES 128` is used. For length `32`, `AES 256` is used.
-- `iv: Uint8Array` Must have length `16`.
-
-Returns `Promise<{decrypt<Function>, encrypt<Function>}>`
-
-##### `decrypt(data)`
-
-- `data: Uint8Array`
-
-Returns `Promise<Uint8Array>`
-
-##### `encrypt(data)`
-
-- `data: Uint8Array`
-
-Returns `Promise<Uint8Array>`
-
-```js
-const crypto = require('libp2p-crypto')
-
-// Setting up Key and IV
-
-// A 16 bytes array, 128 Bits, AES-128 is chosen
-const key128 = Uint8Array.from([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15])
-
-// A 16 bytes array, 128 Bits,
-const IV = Uint8Array.from([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15])
-
-async function main () {
-  const decryptedMessage = 'Hello, world!'
-
-  // Encrypting
-  const cipher = await crypto.aes.create(key128, IV)
-  const encryptedBuffer = await cipher.encrypt(Uint8Array.from(decryptedMessage))
-  console.log(encryptedBuffer)
-  // prints: <Uint8Array 42 f1 67 d9 2e 42 d0 32 9e b1 f8 3c>
-
-  // Decrypting
-  const decipher = await crypto.aes.create(key128, IV)
-  const decryptedBuffer = await cipher.decrypt(encryptedBuffer)
-
-  console.log(decryptedBuffer)
-  // prints: <Uint8Array 42 f1 67 d9 2e 42 d0 32 9e b1 f8 3c>
-
-  console.log(decryptedBuffer.toString('utf-8'))
-  // prints: Hello, world!
-}
-
-main()
-```
-
-### `crypto.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.
-
-#### `crypto.hmac.create(hash, secret)`
-
-- `hash: String`
-- `secret: Uint8Array`
-
-Returns `Promise<{digest<Function>}>`
-
-##### `digest(data)`
-
-- `data: Uint8Array`
-
-Returns `Promise<Uint8Array>`
-
-Example:
-
-```js
-const crypto = require('libp2p-crypto')
-
-async function main () {
-  const hash = 'SHA1' // 'SHA256' || 'SHA512'
-  const hmac = await crypto.hmac.create(hash, uint8ArrayFromString('secret'))
-  const sig = await hmac.digest(uint8ArrayFromString('hello world'))
-  console.log(sig)
-}
-
-main()
-```
-
-### `crypto.keys`
-
-**Supported Key Types**
-
-The [`generateKeyPair`](#generatekeypairtype-bits), [`marshalPublicKey`](#marshalpublickeykey-type), and [`marshalPrivateKey`](#marshalprivatekeykey-type) functions accept a string `type` argument.
-
-Currently the `'RSA'`, `'ed25519'`, and `secp256k1` types are supported, although ed25519 and secp256k1 keys support only signing and verification of messages.  For encryption / decryption support, RSA keys should be used.
-
-### `crypto.keys.generateKeyPair(type, bits)`
-
-- `type: String`, see [Supported Key Types](#supported-key-types) above.
-- `bits: Number` Minimum of 1024
-
-Returns `Promise<{privateKey<Uint8Array>, publicKey<Uint8Array>}>`
-
-Generates a keypair of the given type and bitsize.
-
-### `crypto.keys.generateEphemeralKeyPair(curve)`
-
-- `curve: String`, one of `'P-256'`, `'P-384'`, `'P-521'` is currently supported
-
-Returns `Promise`
-
-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.
-
-Resolves to an object of the form:
-
-```js
-{
-  key: Uint8Array,
-  genSharedKey: Function
-}
-```
-
-### `crypto.keys.keyStretcher(cipherType, hashType, secret)`
-
-- `cipherType: String`, one of `'AES-128'`, `'AES-256'`, `'Blowfish'`
-- `hashType: String`, one of `'SHA1'`, `SHA256`, `SHA512`
-- `secret: Uint8Array`
-
-Returns `Promise`
-
-Generates a set of keys for each party by stretching the shared key.
-
-Resolves to an object of the form:
-
-```js
-{
-  k1: {
-    iv: Uint8Array,
-    cipherKey: Uint8Array,
-    macKey: Uint8Array
-  },
-  k2: {
-    iv: Uint8Array,
-    cipherKey: Uint8Array,
-    macKey: Uint8Array
-  }
-}
-```
-
-### `crypto.keys.marshalPublicKey(key, [type])`
-
-- `key: keys.rsa.RsaPublicKey | keys.ed25519.Ed25519PublicKey | keys.secp256k1.Secp256k1PublicKey`
-- `type: String`, see [Supported Key Types](#supported-key-types) above.  Defaults to 'rsa'.
-
-Returns `Uint8Array`
-
-Converts a public key object into a protobuf serialized public key.
-
-### `crypto.keys.unmarshalPublicKey(buf)`
-
-- `buf: Uint8Array`
-
-Returns `RsaPublicKey|Ed25519PublicKey|Secp256k1PublicKey`
-
-Converts a protobuf serialized public key into its representative object.
-
-### `crypto.keys.marshalPrivateKey(key, [type])`
-
-- `key: keys.rsa.RsaPrivateKey | keys.ed25519.Ed25519PrivateKey | keys.secp256k1.Secp256k1PrivateKey`
-- `type: String`, see [Supported Key Types](#supported-key-types) above.
-
-Returns `Uint8Array`
-
-Converts a private key object into a protobuf serialized private key.
-
-### `crypto.keys.unmarshalPrivateKey(buf)`
-
-- `buf: Uint8Array`
-
-Returns `Promise<RsaPrivateKey|Ed25519PrivateKey|Secp256k1PrivateKey>`
-
-Converts a protobuf serialized private key into its representative object.
-
-### `crypto.keys.import(encryptedKey, password)`
-
-- `encryptedKey: string`
-- `password: string`
-
-Returns `Promise<PrivateKey>`
-
-Converts an exported private key into its representative object. Supported formats are 'pem' (RSA only) and 'libp2p-key'.
-
-### `privateKey.export(password, format)`
-
-- `password: string`
-- `format: string` the format to export to: 'pem' (rsa only), 'libp2p-key'
-
-Returns `string`
-
-Exports the password protected `PrivateKey`. RSA keys will be exported as password protected PEM by default. Ed25519 and Secp256k1 keys will be exported as password protected AES-GCM base64 encoded strings ('libp2p-key' format).
-
-### `crypto.randomBytes(number)`
-
-- `number: Number`
-
-Returns `Uint8Array`
-
-Generates a Uint8Array with length `number` populated by random bytes.
-
-### `crypto.pbkdf2(password, salt, iterations, keySize, hash)`
-
-- `password: String`
-- `salt: String`
-- `iterations: Number`
-- `keySize: Number` in bytes
-- `hash: String` the hashing algorithm ('sha1', 'sha2-512', ...)
-
-Computes the Password Based Key Derivation Function 2; returning a new password.
-
-## Contribute
+# Contribute
 
 Feel free to join in. All welcome. Open an [issue](https://github.com/libp2p/js-libp2p-crypto/issues)!
 
@@ -314,17 +27,17 @@ This repository falls under the IPFS [Code of Conduct](https://github.com/ipfs/c
 
 [![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/contributing.md)
 
-## API Docs
+# API Docs
 
 - <https://libp2p.github.io/js-libp2p/modules/_libp2p_crypto.html>
 
-## License
+# License
 
 Licensed under either of
 
 - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / <http://www.apache.org/licenses/LICENSE-2.0>)
 - MIT ([LICENSE-MIT](LICENSE-MIT) / <http://opensource.org/licenses/MIT>)
 
-## Contribution
+# Contribution
 
 Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

package/dist/src/aes/index.d.ts

@@ -1,6 +1,50 @@
+/**
+ * @packageDocumentation
+ *
+ * Exposes an interface to AES encryption (formerly Rijndael), as defined in U.S. Federal Information Processing Standards Publication 197.
+ *
+ * This uses `CTR` mode.
+ *
+ * /**
+ * @example
+ *
+ * ```js
+ * import { create } from '@libp2p/crypto/aes'
+ *
+ * // Setting up Key and IV
+ *
+ * // A 16 bytes array, 128 Bits, AES-128 is chosen
+ * const key128 = Uint8Array.from([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15])
+ *
+ * // A 16 bytes array, 128 Bits,
+ * const IV = Uint8Array.from([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15])
+ *
+ * const decryptedMessage = 'Hello, world!'
+ *
+ * // Encrypting
+ * const cipher = await crypto.aes.create(key128, IV)
+ * const encryptedBuffer = await encrypt(Uint8Array.from(decryptedMessage))
+ * console.log(encryptedBuffer)
+ * // prints: <Uint8Array 42 f1 67 d9 2e 42 d0 32 9e b1 f8 3c>
+ *
+ * // Decrypting
+ * const decipher = await crypto.aes.create(key128, IV)
+ * const decryptedBuffer = await decrypt(encryptedBuffer)
+ *
+ * console.log(decryptedBuffer)
+ * // prints: <Uint8Array 42 f1 67 d9 2e 42 d0 32 9e b1 f8 3c>
+ *
+ * console.log(decryptedBuffer.toString('utf-8'))
+ * // prints: Hello, world!
+ * ```
+ */
 export interface AESCipher {
     encrypt(data: Uint8Array): Promise<Uint8Array>;
     decrypt(data: Uint8Array): Promise<Uint8Array>;
 }
+/**
+ * @param key - The key, if length `16` then `AES 128` is used. For length `32`, `AES 256` is used
+ * @param iv - Must have length `16`
+ */
 export declare function create(key: Uint8Array, iv: Uint8Array): Promise<AESCipher>;
 //# sourceMappingURL=index.d.ts.map

package/dist/src/aes/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/aes/index.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;IAC9C,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;CAC/C;AAED,wBAAsB,MAAM,CAAE,GAAG,EAAE,UAAU,EAAE,EAAE,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAgBjF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/aes/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAKH,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;IAC9C,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;CAC/C;AAED;;;GAGG;AACH,wBAAsB,MAAM,CAAE,GAAG,EAAE,UAAU,EAAE,EAAE,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAgBjF"}

package/dist/src/aes/index.js

@@ -1,5 +1,49 @@
+/**
+ * @packageDocumentation
+ *
+ * Exposes an interface to AES encryption (formerly Rijndael), as defined in U.S. Federal Information Processing Standards Publication 197.
+ *
+ * This uses `CTR` mode.
+ *
+ * /**
+ * @example
+ *
+ * ```js
+ * import { create } from '@libp2p/crypto/aes'
+ *
+ * // Setting up Key and IV
+ *
+ * // A 16 bytes array, 128 Bits, AES-128 is chosen
+ * const key128 = Uint8Array.from([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15])
+ *
+ * // A 16 bytes array, 128 Bits,
+ * const IV = Uint8Array.from([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15])
+ *
+ * const decryptedMessage = 'Hello, world!'
+ *
+ * // Encrypting
+ * const cipher = await crypto.aes.create(key128, IV)
+ * const encryptedBuffer = await encrypt(Uint8Array.from(decryptedMessage))
+ * console.log(encryptedBuffer)
+ * // prints: <Uint8Array 42 f1 67 d9 2e 42 d0 32 9e b1 f8 3c>
+ *
+ * // Decrypting
+ * const decipher = await crypto.aes.create(key128, IV)
+ * const decryptedBuffer = await decrypt(encryptedBuffer)
+ *
+ * console.log(decryptedBuffer)
+ * // prints: <Uint8Array 42 f1 67 d9 2e 42 d0 32 9e b1 f8 3c>
+ *
+ * console.log(decryptedBuffer.toString('utf-8'))
+ * // prints: Hello, world!
+ * ```
+ */
 import { cipherMode } from './cipher-mode.js';
 import * as ciphers from './ciphers.js';
+/**
+ * @param key - The key, if length `16` then `AES 128` is used. For length `32`, `AES 256` is used
+ * @param iv - Must have length `16`
+ */
 export async function create(key, iv) {
     const mode = cipherMode(key);
     const cipher = ciphers.createCipheriv(mode, key, iv);

package/dist/src/aes/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/aes/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAOvC,MAAM,CAAC,KAAK,UAAU,MAAM,CAAE,GAAe,EAAE,EAAc;IAC3D,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,CAAA;IAC5B,MAAM,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,CAAA;IACpD,MAAM,QAAQ,GAAG,OAAO,CAAC,gBAAgB,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,CAAA;IAExD,MAAM,GAAG,GAAc;QACrB,KAAK,CAAC,OAAO,CAAE,IAAI;YACjB,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QAC5B,CAAC;QAED,KAAK,CAAC,OAAO,CAAE,IAAI;YACjB,OAAO,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QAC9B,CAAC;KACF,CAAA;IAED,OAAO,GAAG,CAAA;AACZ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/aes/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAOvC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAE,GAAe,EAAE,EAAc;IAC3D,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,CAAA;IAC5B,MAAM,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,CAAA;IACpD,MAAM,QAAQ,GAAG,OAAO,CAAC,gBAAgB,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,CAAA;IAExD,MAAM,GAAG,GAAc;QACrB,KAAK,CAAC,OAAO,CAAE,IAAI;YACjB,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QAC5B,CAAC;QAED,KAAK,CAAC,OAAO,CAAE,IAAI;YACjB,OAAO,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QAC9B,CAAC;KACF,CAAA;IAED,OAAO,GAAG,CAAA;AACZ,CAAC"}

package/dist/src/hmac/index.d.ts

@@ -1,3 +1,19 @@
+/**
+ * @packageDocumentation
+ *
+ * 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.
+ *
+ * @example
+ *
+ * ```js
+ * import { create } from '@libp2p/hmac'
+ *
+ * const hash = 'SHA1' // 'SHA256' || 'SHA512'
+ * const hmac = await crypto.hmac.create(hash, uint8ArrayFromString('secret'))
+ * const sig = await hmac.digest(uint8ArrayFromString('hello world'))
+ * console.log(sig)
+ * ```
+ */
 export interface HMAC {
     digest(data: Uint8Array): Promise<Uint8Array>;
     length: number;

package/dist/src/hmac/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hmac/index.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,IAAI;IACnB,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;IAC7C,MAAM,EAAE,MAAM,CAAA;CACf;AAED,wBAAsB,MAAM,CAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAWnG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hmac/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,MAAM,WAAW,IAAI;IACnB,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;IAC7C,MAAM,EAAE,MAAM,CAAA;CACf;AAED,wBAAsB,MAAM,CAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAWnG"}

package/dist/src/hmac/index.js

@@ -1,3 +1,19 @@
+/**
+ * @packageDocumentation
+ *
+ * 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.
+ *
+ * @example
+ *
+ * ```js
+ * import { create } from '@libp2p/hmac'
+ *
+ * const hash = 'SHA1' // 'SHA256' || 'SHA512'
+ * const hmac = await crypto.hmac.create(hash, uint8ArrayFromString('secret'))
+ * const sig = await hmac.digest(uint8ArrayFromString('hello world'))
+ * console.log(sig)
+ * ```
+ */
 import crypto from 'crypto';
 import lengths from './lengths.js';
 export async function create(hash, secret) {

package/dist/src/hmac/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/hmac/index.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAA;AAC3B,OAAO,OAAO,MAAM,cAAc,CAAA;AAOlC,MAAM,CAAC,KAAK,UAAU,MAAM,CAAE,IAAkC,EAAE,MAAkB;IAClF,MAAM,GAAG,GAAG;QACV,KAAK,CAAC,MAAM,CAAE,IAAgB;YAC5B,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,MAAM,CAAC,CAAA;YAC1D,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;YACjB,OAAO,IAAI,CAAC,MAAM,EAAE,CAAA;QACtB,CAAC;QACD,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC;KACtB,CAAA;IAED,OAAO,GAAG,CAAA;AACZ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/hmac/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,MAAM,MAAM,QAAQ,CAAA;AAC3B,OAAO,OAAO,MAAM,cAAc,CAAA;AAOlC,MAAM,CAAC,KAAK,UAAU,MAAM,CAAE,IAAkC,EAAE,MAAkB;IAClF,MAAM,GAAG,GAAG;QACV,KAAK,CAAC,MAAM,CAAE,IAAgB;YAC5B,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,MAAM,CAAC,CAAA;YAC1D,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;YACjB,OAAO,IAAI,CAAC,MAAM,EAAE,CAAA;QACtB,CAAC;QACD,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC;KACtB,CAAA;IAED,OAAO,GAAG,CAAA;AACZ,CAAC"}

package/dist/src/index.d.ts

@@ -1,3 +1,12 @@
+/**
+ * @packageDocumentation
+ *
+ * The `libp2p-crypto` library depends on the [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) in the browser. Web Crypto is available in all modern browsers, however browsers restrict its usage to [Secure Contexts](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts).
+ *
+ * *This means you will not be able to use some `@libp2p/crypto` functions in the browser when the page is served over HTTP.*
+ *
+ * To enable the Web Crypto API and allow `@libp2p/crypto` to work fully, please serve your page over HTTPS.
+ */
 import * as aes from './aes/index.js';
 import * as hmac from './hmac/index.js';
 import * as keys from './keys/index.js';

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,gBAAgB,CAAA;AACrC,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAA;AACvC,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAA;AACvC,OAAO,MAAM,MAAM,aAAa,CAAA;AAChC,OAAO,WAAW,MAAM,mBAAmB,CAAA;AAE3C,OAAO,EAAE,GAAG,EAAE,CAAA;AACd,OAAO,EAAE,IAAI,EAAE,CAAA;AACf,OAAO,EAAE,IAAI,EAAE,CAAA;AACf,OAAO,EAAE,WAAW,EAAE,CAAA;AACtB,OAAO,EAAE,MAAM,EAAE,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,GAAG,MAAM,gBAAgB,CAAA;AACrC,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAA;AACvC,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAA;AACvC,OAAO,MAAM,MAAM,aAAa,CAAA;AAChC,OAAO,WAAW,MAAM,mBAAmB,CAAA;AAE3C,OAAO,EAAE,GAAG,EAAE,CAAA;AACd,OAAO,EAAE,IAAI,EAAE,CAAA;AACf,OAAO,EAAE,IAAI,EAAE,CAAA;AACf,OAAO,EAAE,WAAW,EAAE,CAAA;AACtB,OAAO,EAAE,MAAM,EAAE,CAAA"}

package/dist/src/index.js

@@ -1,3 +1,12 @@
+/**
+ * @packageDocumentation
+ *
+ * The `libp2p-crypto` library depends on the [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) in the browser. Web Crypto is available in all modern browsers, however browsers restrict its usage to [Secure Contexts](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts).
+ *
+ * *This means you will not be able to use some `@libp2p/crypto` functions in the browser when the page is served over HTTP.*
+ *
+ * To enable the Web Crypto API and allow `@libp2p/crypto` to work fully, please serve your page over HTTPS.
+ */
 import * as aes from './aes/index.js';
 import * as hmac from './hmac/index.js';
 import * as keys from './keys/index.js';

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,gBAAgB,CAAA;AACrC,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAA;AACvC,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAA;AACvC,OAAO,MAAM,MAAM,aAAa,CAAA;AAChC,OAAO,WAAW,MAAM,mBAAmB,CAAA;AAE3C,OAAO,EAAE,GAAG,EAAE,CAAA;AACd,OAAO,EAAE,IAAI,EAAE,CAAA;AACf,OAAO,EAAE,IAAI,EAAE,CAAA;AACf,OAAO,EAAE,WAAW,EAAE,CAAA;AACtB,OAAO,EAAE,MAAM,EAAE,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,GAAG,MAAM,gBAAgB,CAAA;AACrC,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAA;AACvC,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAA;AACvC,OAAO,MAAM,MAAM,aAAa,CAAA;AAChC,OAAO,WAAW,MAAM,mBAAmB,CAAA;AAE3C,OAAO,EAAE,GAAG,EAAE,CAAA;AACd,OAAO,EAAE,IAAI,EAAE,CAAA;AACf,OAAO,EAAE,IAAI,EAAE,CAAA;AACf,OAAO,EAAE,WAAW,EAAE,CAAA;AACtB,OAAO,EAAE,MAAM,EAAE,CAAA"}

package/dist/src/keys/ecdh.d.ts

@@ -1,3 +1,8 @@
 import type { ECDHKey } from './interface.js';
+/**
+ * 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.
+ */
 export declare function generateEphmeralKeyPair(curve: string): Promise<ECDHKey>;
 //# sourceMappingURL=ecdh.d.ts.map

package/dist/src/keys/ecdh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ecdh.d.ts","sourceRoot":"","sources":["../../../src/keys/ecdh.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAe,MAAM,gBAAgB,CAAA;AAW1D,wBAAsB,uBAAuB,CAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAmB9E"}
+{"version":3,"file":"ecdh.d.ts","sourceRoot":"","sources":["../../../src/keys/ecdh.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAe,MAAM,gBAAgB,CAAA;AAW1D;;;;GAIG;AACH,wBAAsB,uBAAuB,CAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAmB9E"}

package/dist/src/keys/ecdh.js

@@ -7,6 +7,11 @@ const curves = {
 };
 const curveTypes = Object.keys(curves);
 const names = curveTypes.join(' / ');
+/**
+ * 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.
+ */
 export async function generateEphmeralKeyPair(curve) {
     if (curve !== 'P-256' && curve !== 'P-384' && curve !== 'P-521') {
         throw new CodeError(`Unknown curve: ${curve}. Must be ${names}`, 'ERR_INVALID_CURVE');

package/dist/src/keys/ecdh.js.map

@@ -1 +1 @@
-{"version":3,"file":"ecdh.js","sourceRoot":"","sources":["../../../src/keys/ecdh.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAA;AAC3B,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AAGpD,MAAM,MAAM,GAAG;IACb,OAAO,EAAE,YAAY;IACrB,OAAO,EAAE,WAAW;IACpB,OAAO,EAAE,WAAW;CACrB,CAAA;AAED,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;AACtC,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;AAEpC,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAE,KAAa;IAC1D,IAAI,KAAK,KAAK,OAAO,IAAI,KAAK,KAAK,OAAO,IAAI,KAAK,KAAK,OAAO,EAAE;QAC/D,MAAM,IAAI,SAAS,CAAC,kBAAkB,KAAK,aAAa,KAAK,EAAE,EAAE,mBAAmB,CAAC,CAAA;KACtF;IAED,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;IAC7C,IAAI,CAAC,YAAY,EAAE,CAAA;IAEnB,OAAO;QACL,GAAG,EAAE,IAAI,CAAC,YAAY,EAAgB;QAEtC,KAAK,CAAC,YAAY,CAAE,QAAoB,EAAE,YAA0B;YAClE,IAAI,YAAY,IAAI,IAAI,EAAE;gBACxB,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC,OAAO,CAAC,CAAA;aACzC;YAED,OAAO,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAA;QACrC,CAAC;KACF,CAAA;AACH,CAAC"}
+{"version":3,"file":"ecdh.js","sourceRoot":"","sources":["../../../src/keys/ecdh.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAA;AAC3B,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AAGpD,MAAM,MAAM,GAAG;IACb,OAAO,EAAE,YAAY;IACrB,OAAO,EAAE,WAAW;IACpB,OAAO,EAAE,WAAW;CACrB,CAAA;AAED,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;AACtC,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;AAEpC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAE,KAAa;IAC1D,IAAI,KAAK,KAAK,OAAO,IAAI,KAAK,KAAK,OAAO,IAAI,KAAK,KAAK,OAAO,EAAE;QAC/D,MAAM,IAAI,SAAS,CAAC,kBAAkB,KAAK,aAAa,KAAK,EAAE,EAAE,mBAAmB,CAAC,CAAA;KACtF;IAED,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;IAC7C,IAAI,CAAC,YAAY,EAAE,CAAA;IAEnB,OAAO;QACL,GAAG,EAAE,IAAI,CAAC,YAAY,EAAgB;QAEtC,KAAK,CAAC,YAAY,CAAE,QAAoB,EAAE,YAA0B;YAClE,IAAI,YAAY,IAAI,IAAI,EAAE;gBACxB,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC,OAAO,CAAC,CAAA;aACzC;YAED,OAAO,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAA;QACrC,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/src/keys/index.d.ts

@@ -1,3 +1,14 @@
+/**
+ * @packageDocumentation
+ *
+ * **Supported Key Types**
+ *
+ * The {@link generateKeyPair}, {@link marshalPublicKey}, and {@link marshalPrivateKey} functions accept a string `type` argument.
+ *
+ * Currently the `'RSA'`, `'ed25519'`, and `secp256k1` types are supported, although ed25519 and secp256k1 keys support only signing and verification of messages.
+ *
+ * For encryption / decryption support, RSA keys should be used.
+ */
 import 'node-forge/lib/asn1.js';
 import 'node-forge/lib/pbe.js';
 import * as Ed25519 from './ed25519-class.js';
@@ -16,20 +27,43 @@ export declare const supportedKeys: {
     ed25519: typeof Ed25519;
     secp256k1: typeof Secp256k1;
 };
+/**
+ * Generates a keypair of the given type and bitsize
+ *
+ * @param type
+ * @param bits -  Minimum of 1024
+ */
 export declare function generateKeyPair(type: KeyTypes, bits?: number): Promise<PrivateKey>;
+/**
+ * Generates a keypair of the given type and bitsize.
+ *
+ * Seed is a 32 byte uint8array
+ */
 export declare function generateKeyPairFromSeed(type: KeyTypes, seed: Uint8Array, bits?: number): Promise<PrivateKey>;
+/**
+ * Converts a protobuf serialized public key into its representative object
+ */
 export declare function unmarshalPublicKey(buf: Uint8Array): PublicKey;
+/**
+ * Converts a public key object into a protobuf serialized public key
+ */
 export declare function marshalPublicKey(key: {
     bytes: Uint8Array;
 }, type?: string): Uint8Array;
+/**
+ * Converts a protobuf serialized private key into its representative object
+ */
 export declare function unmarshalPrivateKey(buf: Uint8Array): Promise<PrivateKey>;
+/**
+ * Converts a private key object into a protobuf serialized private key
+ */
 export declare function marshalPrivateKey(key: {
     bytes: Uint8Array;
 }, type?: string): Uint8Array;
 /**
+ * Converts an exported private key into its representative object.
  *
- * @param {string} encryptedKey
- * @param {string} password
+ * Supported formats are 'pem' (RSA only) and 'libp2p-key'.
  */
 export declare function importKey(encryptedKey: string, password: string): Promise<PrivateKey>;
 //# sourceMappingURL=index.d.ts.map

package/dist/src/keys/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/keys/index.ts"],"names":[],"mappings":"AAAA,OAAO,wBAAwB,CAAA;AAC/B,OAAO,uBAAuB,CAAA;AAK9B,OAAO,KAAK,OAAO,MAAM,oBAAoB,CAAA;AAC7C,OAAO,wBAAwB,MAAM,qBAAqB,CAAA;AAE1D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,KAAK,OAAO,MAAM,WAAW,CAAA;AACpC,OAAO,KAAK,GAAG,MAAM,gBAAgB,CAAA;AACrC,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAA;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAEnE,OAAO,EAAE,YAAY,EAAE,CAAA;AACvB,OAAO,EAAE,wBAAwB,EAAE,CAAA;AACnC,OAAO,EAAE,OAAO,EAAE,CAAA;AAElB,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,SAAS,GAAG,WAAW,CAAA;AAEtD,eAAO,MAAM,aAAa;;;;CAIzB,CAAA;AAkBD,wBAAsB,eAAe,CAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAEzF;AAID,wBAAsB,uBAAuB,CAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAMnH;AAID,wBAAgB,kBAAkB,CAAE,GAAG,EAAE,UAAU,GAAG,SAAS,CAc9D;AAGD,wBAAgB,gBAAgB,CAAE,GAAG,EAAE;IAAE,KAAK,EAAE,UAAU,CAAA;CAAE,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,CAIvF;AAID,wBAAsB,mBAAmB,CAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAc/E;AAGD,wBAAgB,iBAAiB,CAAE,GAAG,EAAE;IAAE,KAAK,EAAE,UAAU,CAAA;CAAE,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,CAIxF;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAgB5F"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/keys/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,wBAAwB,CAAA;AAC/B,OAAO,uBAAuB,CAAA;AAK9B,OAAO,KAAK,OAAO,MAAM,oBAAoB,CAAA;AAC7C,OAAO,wBAAwB,MAAM,qBAAqB,CAAA;AAE1D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,KAAK,OAAO,MAAM,WAAW,CAAA;AACpC,OAAO,KAAK,GAAG,MAAM,gBAAgB,CAAA;AACrC,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAA;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAEnE,OAAO,EAAE,YAAY,EAAE,CAAA;AACvB,OAAO,EAAE,wBAAwB,EAAE,CAAA;AACnC,OAAO,EAAE,OAAO,EAAE,CAAA;AAElB,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,SAAS,GAAG,WAAW,CAAA;AAEtD,eAAO,MAAM,aAAa;;;;CAIzB,CAAA;AAiBD;;;;;GAKG;AACH,wBAAsB,eAAe,CAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAEzF;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAMnH;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAE,GAAG,EAAE,UAAU,GAAG,SAAS,CAc9D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAE,GAAG,EAAE;IAAE,KAAK,EAAE,UAAU,CAAA;CAAE,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,CAIvF;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAc/E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAE,GAAG,EAAE;IAAE,KAAK,EAAE,UAAU,CAAA;CAAE,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,CAIxF;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAgB5F"}

package/dist/src/keys/index.js

@@ -1,3 +1,14 @@
+/**
+ * @packageDocumentation
+ *
+ * **Supported Key Types**
+ *
+ * The {@link generateKeyPair}, {@link marshalPublicKey}, and {@link marshalPrivateKey} functions accept a string `type` argument.
+ *
+ * Currently the `'RSA'`, `'ed25519'`, and `secp256k1` types are supported, although ed25519 and secp256k1 keys support only signing and verification of messages.
+ *
+ * For encryption / decryption support, RSA keys should be used.
+ */
 import 'node-forge/lib/asn1.js';
 import 'node-forge/lib/pbe.js';
 import { CodeError } from '@libp2p/interface/errors';
@@ -30,20 +41,29 @@ function typeToKey(type) {
     }
     throw unsupportedKey(type);
 }
-// Generates a keypair of the given type and bitsize
+/**
+ * Generates a keypair of the given type and bitsize
+ *
+ * @param type
+ * @param bits -  Minimum of 1024
+ */
 export async function generateKeyPair(type, bits) {
     return typeToKey(type).generateKeyPair(bits ?? 2048);
 }
-// Generates a keypair of the given type and bitsize
-// seed is a 32 byte uint8array
+/**
+ * Generates a keypair of the given type and bitsize.
+ *
+ * Seed is a 32 byte uint8array
+ */
 export async function generateKeyPairFromSeed(type, seed, bits) {
     if (type.toLowerCase() !== 'ed25519') {
         throw new CodeError('Seed key derivation is unimplemented for RSA or secp256k1', 'ERR_UNSUPPORTED_KEY_DERIVATION_TYPE');
     }
     return Ed25519.generateKeyPairFromSeed(seed);
 }
-// Converts a protobuf serialized public key into its
-// representative object
+/**
+ * Converts a protobuf serialized public key into its representative object
+ */
 export function unmarshalPublicKey(buf) {
     const decoded = keysPBM.PublicKey.decode(buf);
     const data = decoded.Data ?? new Uint8Array();
@@ -58,14 +78,17 @@ export function unmarshalPublicKey(buf) {
             throw unsupportedKey(decoded.Type ?? 'unknown');
     }
 }
-// Converts a public key object into a protobuf serialized public key
+/**
+ * Converts a public key object into a protobuf serialized public key
+ */
 export function marshalPublicKey(key, type) {
     type = (type ?? 'rsa').toLowerCase();
     typeToKey(type); // check type
     return key.bytes;
 }
-// Converts a protobuf serialized private key into its
-// representative object
+/**
+ * Converts a protobuf serialized private key into its representative object
+ */
 export async function unmarshalPrivateKey(buf) {
     const decoded = keysPBM.PrivateKey.decode(buf);
     const data = decoded.Data ?? new Uint8Array();
@@ -80,16 +103,18 @@ export async function unmarshalPrivateKey(buf) {
             throw unsupportedKey(decoded.Type ?? 'RSA');
     }
 }
-// Converts a private key object into a protobuf serialized private key
+/**
+ * Converts a private key object into a protobuf serialized private key
+ */
 export function marshalPrivateKey(key, type) {
     type = (type ?? 'rsa').toLowerCase();
     typeToKey(type); // check type
     return key.bytes;
 }
 /**
+ * Converts an exported private key into its representative object.
  *
- * @param {string} encryptedKey
- * @param {string} password
+ * Supported formats are 'pem' (RSA only) and 'libp2p-key'.
  */
 export async function importKey(encryptedKey, password) {
     try {

package/dist/src/keys/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/keys/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/keys/index.ts"],"names":[],"mappings":"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"}

package/dist/src/random-bytes.d.ts

@@ -1,2 +1,5 @@
+/**
+ * Generates a Uint8Array with length `number` populated by random bytes
+ */
 export default function randomBytes(length: number): Uint8Array;
 //# sourceMappingURL=random-bytes.d.ts.map

package/dist/src/random-bytes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"random-bytes.d.ts","sourceRoot":"","sources":["../../src/random-bytes.ts"],"names":[],"mappings":"AAGA,MAAM,CAAC,OAAO,UAAU,WAAW,CAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAK/D"}
+{"version":3,"file":"random-bytes.d.ts","sourceRoot":"","sources":["../../src/random-bytes.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,CAAC,OAAO,UAAU,WAAW,CAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAK/D"}

package/dist/src/random-bytes.js

@@ -1,5 +1,8 @@
 import { CodeError } from '@libp2p/interface/errors';
 import { randomBytes as randB } from '@noble/hashes/utils';
+/**
+ * Generates a Uint8Array with length `number` populated by random bytes
+ */
 export default function randomBytes(length) {
     if (isNaN(length) || length <= 0) {
         throw new CodeError('random bytes length must be a Number bigger than 0', 'ERR_INVALID_LENGTH');

package/dist/src/random-bytes.js.map

@@ -1 +1 @@
-{"version":3,"file":"random-bytes.js","sourceRoot":"","sources":["../../src/random-bytes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AACpD,OAAO,EAAE,WAAW,IAAI,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAE1D,MAAM,CAAC,OAAO,UAAU,WAAW,CAAE,MAAc;IACjD,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE;QAChC,MAAM,IAAI,SAAS,CAAC,oDAAoD,EAAE,oBAAoB,CAAC,CAAA;KAChG;IACD,OAAO,KAAK,CAAC,MAAM,CAAC,CAAA;AACtB,CAAC"}
+{"version":3,"file":"random-bytes.js","sourceRoot":"","sources":["../../src/random-bytes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AACpD,OAAO,EAAE,WAAW,IAAI,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAE1D;;GAEG;AACH,MAAM,CAAC,OAAO,UAAU,WAAW,CAAE,MAAc;IACjD,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE;QAChC,MAAM,IAAI,SAAS,CAAC,oDAAoD,EAAE,oBAAoB,CAAC,CAAA;KAChG;IACD,OAAO,KAAK,CAAC,MAAM,CAAC,CAAA;AACtB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libp2p/crypto",
-  "version": "2.0.6-d5ef1c91",
+  "version": "2.0.7-051154dd",
   "description": "Crypto primitives for libp2p",
   "license": "Apache-2.0 OR MIT",
   "homepage": "https://github.com/libp2p/js-libp2p/tree/master/packages/crypto#readme",
@@ -86,7 +86,7 @@
     "generate": "protons ./src/keys/keys.proto"
   },
   "dependencies": {
-    "@libp2p/interface": "0.1.4-d5ef1c91",
+    "@libp2p/interface": "0.1.5-051154dd",
     "@noble/curves": "^1.1.0",
     "@noble/hashes": "^1.3.1",
     "multiformats": "^12.0.1",

package/src/aes/index.ts

@@ -1,3 +1,44 @@
+/**
+ * @packageDocumentation
+ *
+ * Exposes an interface to AES encryption (formerly Rijndael), as defined in U.S. Federal Information Processing Standards Publication 197.
+ *
+ * This uses `CTR` mode.
+ *
+ * /**
+ * @example
+ *
+ * ```js
+ * import { create } from '@libp2p/crypto/aes'
+ *
+ * // Setting up Key and IV
+ *
+ * // A 16 bytes array, 128 Bits, AES-128 is chosen
+ * const key128 = Uint8Array.from([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15])
+ *
+ * // A 16 bytes array, 128 Bits,
+ * const IV = Uint8Array.from([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15])
+ *
+ * const decryptedMessage = 'Hello, world!'
+ *
+ * // Encrypting
+ * const cipher = await crypto.aes.create(key128, IV)
+ * const encryptedBuffer = await encrypt(Uint8Array.from(decryptedMessage))
+ * console.log(encryptedBuffer)
+ * // prints: <Uint8Array 42 f1 67 d9 2e 42 d0 32 9e b1 f8 3c>
+ *
+ * // Decrypting
+ * const decipher = await crypto.aes.create(key128, IV)
+ * const decryptedBuffer = await decrypt(encryptedBuffer)
+ *
+ * console.log(decryptedBuffer)
+ * // prints: <Uint8Array 42 f1 67 d9 2e 42 d0 32 9e b1 f8 3c>
+ *
+ * console.log(decryptedBuffer.toString('utf-8'))
+ * // prints: Hello, world!
+ * ```
+ */
+
 import { cipherMode } from './cipher-mode.js'
 import * as ciphers from './ciphers.js'
 
@@ -6,6 +47,10 @@ export interface AESCipher {
   decrypt(data: Uint8Array): Promise<Uint8Array>
 }
 
+/**
+ * @param key - The key, if length `16` then `AES 128` is used. For length `32`, `AES 256` is used
+ * @param iv - Must have length `16`
+ */
 export async function create (key: Uint8Array, iv: Uint8Array): Promise<AESCipher> {
   const mode = cipherMode(key)
   const cipher = ciphers.createCipheriv(mode, key, iv)

package/src/hmac/index.ts

@@ -1,3 +1,20 @@
+/**
+ * @packageDocumentation
+ *
+ * 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.
+ *
+ * @example
+ *
+ * ```js
+ * import { create } from '@libp2p/hmac'
+ *
+ * const hash = 'SHA1' // 'SHA256' || 'SHA512'
+ * const hmac = await crypto.hmac.create(hash, uint8ArrayFromString('secret'))
+ * const sig = await hmac.digest(uint8ArrayFromString('hello world'))
+ * console.log(sig)
+ * ```
+ */
+
 import crypto from 'crypto'
 import lengths from './lengths.js'
 

package/src/index.ts

@@ -1,3 +1,13 @@
+/**
+ * @packageDocumentation
+ *
+ * The `libp2p-crypto` library depends on the [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) in the browser. Web Crypto is available in all modern browsers, however browsers restrict its usage to [Secure Contexts](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts).
+ *
+ * *This means you will not be able to use some `@libp2p/crypto` functions in the browser when the page is served over HTTP.*
+ *
+ * To enable the Web Crypto API and allow `@libp2p/crypto` to work fully, please serve your page over HTTPS.
+ */
+
 import * as aes from './aes/index.js'
 import * as hmac from './hmac/index.js'
 import * as keys from './keys/index.js'

package/src/keys/ecdh.ts

@@ -11,6 +11,11 @@ const curves = {
 const curveTypes = Object.keys(curves)
 const names = curveTypes.join(' / ')
 
+/**
+ * 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.
+ */
 export async function generateEphmeralKeyPair (curve: string): Promise<ECDHKey> {
   if (curve !== 'P-256' && curve !== 'P-384' && curve !== 'P-521') {
     throw new CodeError(`Unknown curve: ${curve}. Must be ${names}`, 'ERR_INVALID_CURVE')

package/src/keys/index.ts

@@ -1,3 +1,15 @@
+/**
+ * @packageDocumentation
+ *
+ * **Supported Key Types**
+ *
+ * The {@link generateKeyPair}, {@link marshalPublicKey}, and {@link marshalPrivateKey} functions accept a string `type` argument.
+ *
+ * Currently the `'RSA'`, `'ed25519'`, and `secp256k1` types are supported, although ed25519 and secp256k1 keys support only signing and verification of messages.
+ *
+ * For encryption / decryption support, RSA keys should be used.
+ */
+
 import 'node-forge/lib/asn1.js'
 import 'node-forge/lib/pbe.js'
 import { CodeError } from '@libp2p/interface/errors'
@@ -40,13 +52,21 @@ function typeToKey (type: string): typeof RSA | typeof Ed25519 | typeof Secp256k
   throw unsupportedKey(type)
 }
 
-// Generates a keypair of the given type and bitsize
+/**
+ * Generates a keypair of the given type and bitsize
+ *
+ * @param type
+ * @param bits -  Minimum of 1024
+ */
 export async function generateKeyPair (type: KeyTypes, bits?: number): Promise<PrivateKey> {
   return typeToKey(type).generateKeyPair(bits ?? 2048)
 }
 
-// Generates a keypair of the given type and bitsize
-// seed is a 32 byte uint8array
+/**
+ * Generates a keypair of the given type and bitsize.
+ *
+ * Seed is a 32 byte uint8array
+ */
 export async function generateKeyPairFromSeed (type: KeyTypes, seed: Uint8Array, bits?: number): Promise<PrivateKey> {
   if (type.toLowerCase() !== 'ed25519') {
     throw new CodeError('Seed key derivation is unimplemented for RSA or secp256k1', 'ERR_UNSUPPORTED_KEY_DERIVATION_TYPE')
@@ -55,8 +75,9 @@ export async function generateKeyPairFromSeed (type: KeyTypes, seed: Uint8Array,
   return Ed25519.generateKeyPairFromSeed(seed)
 }
 
-// Converts a protobuf serialized public key into its
-// representative object
+/**
+ * Converts a protobuf serialized public key into its representative object
+ */
 export function unmarshalPublicKey (buf: Uint8Array): PublicKey {
   const decoded = keysPBM.PublicKey.decode(buf)
   const data = decoded.Data ?? new Uint8Array()
@@ -73,15 +94,18 @@ export function unmarshalPublicKey (buf: Uint8Array): PublicKey {
   }
 }
 
-// Converts a public key object into a protobuf serialized public key
+/**
+ * Converts a public key object into a protobuf serialized public key
+ */
 export function marshalPublicKey (key: { bytes: Uint8Array }, type?: string): Uint8Array {
   type = (type ?? 'rsa').toLowerCase()
   typeToKey(type) // check type
   return key.bytes
 }
 
-// Converts a protobuf serialized private key into its
-// representative object
+/**
+ * Converts a protobuf serialized private key into its representative object
+ */
 export async function unmarshalPrivateKey (buf: Uint8Array): Promise<PrivateKey> {
   const decoded = keysPBM.PrivateKey.decode(buf)
   const data = decoded.Data ?? new Uint8Array()
@@ -98,7 +122,9 @@ export async function unmarshalPrivateKey (buf: Uint8Array): Promise<PrivateKey>
   }
 }
 
-// Converts a private key object into a protobuf serialized private key
+/**
+ * Converts a private key object into a protobuf serialized private key
+ */
 export function marshalPrivateKey (key: { bytes: Uint8Array }, type?: string): Uint8Array {
   type = (type ?? 'rsa').toLowerCase()
   typeToKey(type) // check type
@@ -106,9 +132,9 @@ export function marshalPrivateKey (key: { bytes: Uint8Array }, type?: string): U
 }
 
 /**
+ * Converts an exported private key into its representative object.
  *
- * @param {string} encryptedKey
- * @param {string} password
+ * Supported formats are 'pem' (RSA only) and 'libp2p-key'.
  */
 export async function importKey (encryptedKey: string, password: string): Promise<PrivateKey> {
   try {

package/src/random-bytes.ts

@@ -1,6 +1,9 @@
 import { CodeError } from '@libp2p/interface/errors'
 import { randomBytes as randB } from '@noble/hashes/utils'
 
+/**
+ * Generates a Uint8Array with length `number` populated by random bytes
+ */
 export default function randomBytes (length: number): Uint8Array {
   if (isNaN(length) || length <= 0) {
     throw new CodeError('random bytes length must be a Number bigger than 0', 'ERR_INVALID_LENGTH')