@libp2p/keychain
Version:
Key management and cryptographically protected messages
221 lines (203 loc) • 6.14 kB
text/typescript
/**
* @packageDocumentation
*
* - Manages the life cycle of a key
* - Keys are encrypted at rest
* - Enforces the use of safe key names
* - Uses encrypted PKCS 8 for key storage
* - Uses PBKDF2 for a "stretched" key encryption key
* - Enforces NIST SP 800-131A and NIST SP 800-132
* - Delays reporting errors to slow down brute force attacks
*
* ## KeyInfo
*
* The key management and naming service API all return a `KeyInfo` object. The `id` is a universally unique identifier for the key. The `name` is local to the key chain.
*
* ```JSON
* {
* "name": "rsa-key",
* "id": "QmYWYSUZ4PV6MRFYpdtEDJBiGs4UrmE6g8wmAWSePekXVW"
* }
* ```
*
* The **key id** is the SHA-256 [multihash](https://github.com/multiformats/multihash) of its public key.
*
* The *public key* is a [protobuf encoding](https://github.com/libp2p/js-libp2p/blob/main/packages/crypto/src/keys/keys.proto.js) containing a type and the [DER encoding](https://en.wikipedia.org/wiki/X.690) of the PKCS [SubjectPublicKeyInfo](https://www.ietf.org/rfc/rfc3279.txt).
*
* ## Private key storage
*
* A private key is stored as an encrypted PKCS 8 structure in the PEM format. It is protected by a key generated from the key chain's *pass phrase* using **PBKDF2**.
*
* The default options for generating the derived encryption key are in the `dek` object. This, along with the pass phrase, is the input to a `PBKDF2` function.
*
* ```TypeScript
* const defaultOptions = {
* // See https://cryptosense.com/parameter-choice-for-pbkdf2/
* dek: {
* keyLength: 512 / 8,
* iterationCount: 1000,
* salt: 'at least 16 characters long',
* hash: 'sha2-512'
* }
* }
* ```
*
* 
*
* ## Physical storage
*
* The actual physical storage of an encrypted key is left to implementations of [interface-datastore](https://github.com/ipfs/interface-datastore/).
*
* A key benefit is that now the key chain can be used in browser with the [js-datastore-level](https://github.com/ipfs/js-datastore-level) implementation.
*/
import { Keychain as KeychainClass } from './keychain.js'
import type { ComponentLogger, PrivateKey } from '@libp2p/interface'
import type { Datastore } from 'interface-datastore'
export interface DEKConfig {
hash: string
salt: string
iterationCount: number
keyLength: number
}
export interface KeychainInit {
/**
* The password is used to derive a key which encrypts the keychain at rest
*/
pass?: string
/**
* This key configures how the keychain encryption key is derived from the
* configured password
*/
dek?: DEKConfig
/**
* The 'self' key is the private key of the node from which the peer id is
* derived.
*
* It cannot be renamed or removed.
*
* By default it is stored under the 'self' key, to use a different name, pass
* this option.
*
* @default 'self'
*/
selfKey?: string
}
export interface KeychainComponents {
datastore: Datastore
logger: ComponentLogger
}
export interface KeyInfo {
/**
* The universally unique key id
*/
id: string
/**
* The local key name
*/
name: string
}
export interface Keychain {
/**
* Find a key by name
*
* @example
*
* ```TypeScript
* import { generateKeyPair } from '@libp2p/crypto/keys'
*
* const key = await generateKeyPair('Ed25519')
* const keyInfo = await libp2p.keychain.importKey('my-key', key)
* const keyInfo2 = await libp2p.keychain.findKeyByName(keyInfo.name)
* ```
*/
findKeyByName(name: string): Promise<KeyInfo>
/**
* Find a key by id
*
* @example
*
* ```TypeScript
* import { generateKeyPair } from '@libp2p/crypto/keys'
*
* const key = await generateKeyPair('Ed25519')
* const keyInfo = await libp2p.keychain.importKey('my-key', key)
* const keyInfo2 = await libp2p.keychain.findKeyById(keyInfo.id)
* ```
*/
findKeyById (id: string): Promise<KeyInfo>
/**
* Import a new private key.
*
* @example
*
* ```TypeScript
* import { generateKeyPair } from '@libp2p/crypto/keys'
*
* const key = await generateKeyPair('Ed25519')
* const keyInfo = await libp2p.keychain.importKey('my-key', key)
* ```
*/
importKey(name: string, key: PrivateKey): Promise<KeyInfo>
/**
* Export an existing private key.
*
* @example
*
* ```TypeScript
* import { generateKeyPair } from '@libp2p/crypto/keys'
*
* const key = await generateKeyPair('Ed25519')
* const keyInfo = await libp2p.keychain.importKey('my-key', key)
* const key = await libp2p.keychain.exportKey(keyInfo.id)
* ```
*/
exportKey(name: string): Promise<PrivateKey>
/**
* Removes a key from the keychain.
*
* @example
*
* ```TypeScript
* await libp2p.services.keychain.createKey('keyTest', 'RSA', 4096)
* const keyInfo = await libp2p.services.keychain.removeKey('keyTest')
* ```
*/
removeKey(name: string): Promise<KeyInfo>
/**
* Rename a key in the keychain. This is done in a batch commit with rollback
* so errors thrown during the operation will not cause key loss.
*
* @example
*
* ```TypeScript
* await libp2p.services.keychain.createKey('keyTest', 'RSA', 4096)
* const keyInfo = await libp2p.services.keychain.renameKey('keyTest', 'keyNewTest')
* ```
*/
renameKey(oldName: string, newName: string): Promise<KeyInfo>
/**
* List all the keys.
*
* @example
*
* ```TypeScript
* const keyInfos = await libp2p.keychain.listKeys()
* ```
*/
listKeys(): Promise<KeyInfo[]>
/**
* Rotate keychain password and re-encrypt all associated keys
*
* @example
*
* ```TypeScript
* await libp2p.services.keychain.rotateKeychainPass('oldPassword', 'newPassword')
* ```
*/
rotateKeychainPass(oldPass: string, newPass: string): Promise<void>
}
export function keychain (init: KeychainInit = {}): (components: KeychainComponents) => Keychain {
return (components: KeychainComponents) => {
return new KeychainClass(components, init)
}
}