Class KeyRing

Hierarchy

  • CreateDestroyStartStop
    • KeyRing

Constructors

constructor

Properties

[initLock] _dbKey? _keyPair? _recoveryCodeData? dbKeyPath fs keysPath logger passwordHash? passwordMemLimit? passwordOpsLimit? privateKeyPath publicKeyPath rotateLock strictMemoryLock workerManager?

Accessors

[destroyed] [eventHandled] [eventHandlers] [eventTarget] [handleEventError] [running] [statusP] [status] dbKey keyPair recoveryCode

Methods

addEventListener changePassword checkPassword decrypt destroy dispatchEvent encrypt existsDbKey existsKeyPair existsPrivateKey existsPublicKey generateDbKey generateKeyPair getNodeId readDbKey readKeyPair readPrivateKey readPublicKey recoverKeyPair removeEventListener rotateKeyPair setWorkerManager setupDbKey setupKeyPair setupPasswordHash sign start stop unsetWorkerManager verify writeDbKey writeKeyPair createKeyRing

Constructors

constructor

Properties

Readonly [initLock]

[initLock]: RWLockWriter

Protected Optional _dbKey

_dbKey?: BufferLocked<Key>

Protected Optional _keyPair

_keyPair?: Readonly<{
    privateKey: BufferLocked<PrivateKey>;
    publicKey: BufferLocked<PublicKey>;
    secretKey: BufferLocked<SecretKey>;
}>

Type declaration

Protected Optional _recoveryCodeData

_recoveryCodeData?: RecoveryCodeLocked

Readonly dbKeyPath

dbKeyPath: string

Protected fs

fs: FileSystem

Readonly keysPath

keysPath: string

Protected logger

logger: Logger

Protected Optional passwordHash

passwordHash?: Readonly<{
    hash: BufferLocked<PasswordHash>;
    salt: BufferLocked<PasswordSalt>;
}>

Type declaration

Protected Optional passwordMemLimit

passwordMemLimit?: PasswordMemLimit

Protected Optional passwordOpsLimit

passwordOpsLimit?: PasswordOpsLimit

Readonly privateKeyPath

privateKeyPath: string

Readonly publicKeyPath

publicKeyPath: string

Protected rotateLock

rotateLock: Lock = ...

Readonly strictMemoryLock

strictMemoryLock: boolean

Protected Optional workerManager

workerManager?: PolykeyWorkerManagerInterface

Accessors

[destroyed]

  • get [destroyed](): boolean

  • Returns boolean

[eventHandled]

  • get [eventHandled](): ReadonlyWeakSet<Event>

  • Returns ReadonlyWeakSet<Event>

[eventHandlers]

  • get [eventHandlers](): ReadonlyMap<string, Set<EventHandlerInfo>>

  • Returns ReadonlyMap<string, Set<EventHandlerInfo>>

[eventTarget]

  • get [eventTarget](): EventTarget

  • Returns EventTarget

[handleEventError]

  • get [handleEventError](): ((evt) => void)

  • Returns ((evt) => void)

      • (evt): void

      • Parameters

        • evt: EventError

        Returns void

[running]

  • get [running](): boolean

  • Returns boolean

[statusP]

  • get [statusP](): Promise<Status>

  • Returns Promise<Status>

[status]

  • get [status](): Status

  • Returns Status

dbKey

keyPair

recoveryCode

Methods

addEventListener

  • Parameters

    • type: string
    • callback: null | EventListenerOrEventListenerObject
    • Optional options: boolean | AddEventListenerOptions

    Returns void

changePassword

  • Changes the root key pair password. This will re-wrap the private key. The password is the new password. This does not require the old password because if the KeyRing is ready, that means the agent is unlocked at least from the perspective of the KeyRing. If an external client intends to change the password, they must be authenticated first.

    Parameters

    • password: string

    Returns Promise<void>

checkPassword

  • Warning: this is intended to be a slow operation to prevent brute force attacks

    Parameters

    • password: string

    Returns Promise<boolean>

decrypt

  • Decrypt data sent to this key pair Note that this does not automatically authenticate the sender.

    Parameters

    • cipherText: Buffer

    Returns undefined | Buffer

destroy

  • Returns Promise<void>

dispatchEvent

  • Parameters

    • event: Event

    Returns boolean

encrypt

  • Encrypt to a public key. The authenticated option is used to determine whether to use the static root key pair. By default it will use generate an ephemeral key pair. Neither ensures forward secrecy. However ephemeral key pair provides one-way forward secrecy. If it is important that the receiver can authenticate the sender, consider doing sign-then-encrypt, by adding a signature into the plain text being sent.

    Parameters

    • receiverPublicKey: PublicKey
    • plainText: Buffer
    • authenticated: boolean = false

    Returns Buffer

Protected existsDbKey

  • Checks the existence of the DB key path. This checks if the file can be read and written. If the file does not exist, this returns false. If the file does exist but it cannot be read or written, then this will throw ErrorDBKeyRead.

    Returns Promise<boolean>

Protected existsKeyPair

  • Only the private key is necessary. We can derive the public key from the private key.

    Returns Promise<boolean>

Protected existsPrivateKey

Protected existsPublicKey

Protected generateDbKey

Protected generateKeyPair

getNodeId

Protected readDbKey

  • Reads the DB key from the filesystem. The DB key is expected to be stored in flattened JWE format. The DB key is expected to be encrypted with our ECIES.

    Parameters

    Returns Promise<Key>

Protected readKeyPair

  • Reads the key pair from the filesystem. This only needs to read the private key as the public key is derived. The private key is expected to be stored in a flattened JWE format.

    Parameters

    • password: string

    Returns Promise<Readonly<{
        privateKey: PrivateKey;
        publicKey: PublicKey;
        secretKey: SecretKey;
    }>>

Protected readPrivateKey

  • Reads the private key from the filesystem. The private key is expected to be stored in a flattened JWE format.

    Parameters

    • password: string
    • privateKeyPath: string = ...

    Returns Promise<PrivateKey>

Protected readPublicKey

  • Reads the public key from the filesystem. The public key is expected to be stored in a flattened JWE format.

    Parameters

    • publicKeyPath: string = ...

    Returns Promise<PublicKey>

Protected recoverKeyPair

removeEventListener

  • Parameters

    • type: string
    • callback: null | EventListenerOrEventListenerObject
    • Optional options: boolean | EventListenerOptions

    Returns void

rotateKeyPair

  • Rotates the key pair. This generates a new recovery code and new key pair. The DB key is not rotated, it is just re-encrypted with the new key pair. The key pair is wrapped with the new password.

    Parameters

    • password: string
    • Optional rotateHook: ((keyPairNew, keyPairOld, recoveryCodeNew, recoveryCodeOld?) => any)

    Returns Promise<void>

setWorkerManager

Protected setupDbKey

  • Setup the DB key. This is the data encryption key for the rest of PK. This is what makes PK a hybrid cryptosystem.

    Parameters

    Returns Promise<Key>

Protected setupKeyPair

  • Sets up the root key pair. If the root key pair already exists:

    • If password is supplied, the key pair is decrypted with the password. The key pair is returned without the recovery code.
    • If password and recovery code is supplied, then the key pair will be recovered. The recovery code is used to derive a key pair that is checked against the existing key pair. If the key pairs match, then the derived key pair is encrypted with the password. The key pair is returned without the recovery code.
    • Private key and private key path is ignored, and this is handled the same as if only the password was supplied. If the root key pair does not exist:
    • If password is supplied, then recovery code and key pair is generated. The key pair is encrypted with the password. The key pair and recovery code will be returned.
    • If password and recovery code is supplied, then it will be used for key pair generation. The key pair is encrypted with the password. The key pair and recovery code will be returned.
    • If password and private key is supplied, then key pair will be derived from the private key. The key pair is encrypted with the password. The key pair is returned without the recovery code.

    Parameters

    • options: {
          password: string;
      } | {
          password: string;
          recoveryCode: RecoveryCode;
      } | {
          password: string;
          privateKey: PrivateKey;
      } | {
          password: string;
          privateKeyPath: string;
      }

    Returns Promise<[Readonly<{
        privateKey: PrivateKey;
        publicKey: PublicKey;
        secretKey: SecretKey;
    }>, undefined | RecoveryCode]>

Protected setupPasswordHash

  • This sets up a password hash in-memory. This is used to check if the password is correct. The returned buffers are guaranteed to unpooled and memory-locked. This means the underlying ArrayBuffer is safely transferrable.

    Parameters

    • password: string

    Returns Promise<[PasswordHash, PasswordSalt]>

sign

start

  • Parameters

    • options: Object

    Returns Promise<void>

stop

  • Returns Promise<void>

unsetWorkerManager

verify

Protected writeDbKey

  • Writes the DB key from the filesystem. The DB key will be stored in flattened JWE format. The DB key will be encrypted with our ECIES.

    Parameters

    Returns Promise<void>

Protected writeKeyPair

  • Writes the root key pair to the filesystem. The public key will be stored in JWK format. The private key will be stored in flattened JWE format. This first writes the public key and private key to .tmp files. Then proceeds to atomically rename the files together. The files should be updated together to ensure consistency.

    Parameters

    Returns Promise<void>

Static createKeyRing

Settings

Member Visibility

Theme

On This Page

Generated using TypeDoc