@libp2p/crypto
Crypto primitives for libp2p
Table of contents
- Install
- Lead Maintainer
- Usage
- API
crypto.aes
crypto.hmac
crypto.keys
crypto.keys.generateKeyPair(type, bits)
crypto.keys.generateEphemeralKeyPair(curve)
crypto.keys.keyStretcher(cipherType, hashType, secret)
crypto.keys.marshalPublicKey(key, [type])
crypto.keys.unmarshalPublicKey(buf)
crypto.keys.marshalPrivateKey(key, [type])
crypto.keys.unmarshalPrivateKey(buf)
crypto.keys.import(encryptedKey, password)
privateKey.export(password, format)
crypto.randomBytes(number)
crypto.pbkdf2(password, salt, iterations, keySize, hash)
- Contribute
- API Docs
- License
- Contribution
Install
$ npm i @libp2p/crypto
Browser <script>
tag
Loading this module through a script tag will make it's exports available as Libp2pCrypto
in the global namespace.
<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.
Lead Maintainer
Jacob Heun
Usage
const crypto = require('libp2p-crypto')
Web Crypto API
The libp2p-crypto
library depends on the Web Crypto API in the browser. Web Crypto is available in all modern browsers, however browsers restrict its usage to 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)
Returns Promise<Uint8Array>
encrypt(data)
Returns Promise<Uint8Array>
const crypto = require('libp2p-crypto')
const key128 = Uint8Array.from([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15])
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!'
const cipher = await crypto.aes.create(key128, IV)
const encryptedBuffer = await cipher.encrypt(Uint8Array.from(decryptedMessage))
console.log(encryptedBuffer)
const decipher = await crypto.aes.create(key128, IV)
const decryptedBuffer = await cipher.decrypt(encryptedBuffer)
console.log(decryptedBuffer)
console.log(decryptedBuffer.toString('utf-8'))
}
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)
Returns Promise<Uint8Array>
Example:
const crypto = require('libp2p-crypto')
async function main () {
const hash = 'SHA1'
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
, marshalPublicKey
, and 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.
crypto.keys.generateKeyPair(type, bits)
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:
{
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:
{
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 above. Defaults to 'rsa'.
Returns Uint8Array
Converts a public key object into a protobuf serialized public key.
crypto.keys.unmarshalPublicKey(buf)
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 above.
Returns Uint8Array
Converts a private key object into a protobuf serialized private key.
crypto.keys.unmarshalPrivateKey(buf)
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)
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 byteshash: String
the hashing algorithm ('sha1', 'sha2-512', ...)
Computes the Password Based Key Derivation Function 2; returning a new password.
Contribute
Feel free to join in. All welcome. Open an issue!
This repository falls under the IPFS Code of Conduct.
API Docs
License
Licensed under either of
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.