@lagoware/capacitor-key-manager

Utilize and store encryption and signing keys.

• Android
• Web
• iOS (PRs welcome)

Key Storage

Android

Keys are stored in the Android Key Store.

Web

Keys are stored as non-extractable Web Crypto keys in an IndexedDB database. Please note that your keys may be at risk of eviction by the browser unless your app successfully requests persistent storage.

Install

npm install @lagoware/capacitor-key-manager
npx cap sync

API

• checkAliasExists(...)
• generateKey(...)
• generateRecoverableSignatureKeyPair(...)
• generateRecoverableAgreementKeyPair(...)
• generateRecoverableKey(...)
• importPublicSignatureKey(...)
• importPublicAgreementKey(...)
• rewrapSignatureKeyPair(...)
• rewrapAgreementKeyPair(...)
• rewrapKey(...)
• recoverKey(...)
• recoverAgreementKeyPair(...)
• recoverSignatureKeyPair(...)
• encrypt(...)
• decrypt(...)
• sign(...)
• verify(...)
• Type Aliases

checkAliasExists(...)

checkAliasExists(options: { keyAlias: string; }) => Promise<{ aliasExists: boolean; }>

Checks if a key or key pair exists in the key store under the provided alias.

Param	Type
options	{ keyAlias: string; }

Returns: Promise<{ aliasExists: boolean; }>

---

generateKey(...)

generateKey(options: { keyAlias: string; }) => Promise<void>

Generates a key that can be used for symmetric encryption / decryption. The underlying key material cannot be recovered, therefore encryption / decryption will only be possible on this device.

Param	Type
options	{ keyAlias: string; }

---

generateRecoverableSignatureKeyPair(...)

generateRecoverableSignatureKeyPair(options: KeyWrapParams) => Promise<{ recoverableKeyPair: RecoverableKeyPair; }>

Generates a key pair that can be used for signing and verifying strings. The private key will be wrapped with the provided key reference or password. The generated key pair is returned in a structure of base64-encoded strings that may later be used to recover the key into the key store.

Param	Type
options	KeyWrapParams

Returns: Promise<{ recoverableKeyPair: RecoverableKeyPair; }>

---

generateRecoverableAgreementKeyPair(...)

generateRecoverableAgreementKeyPair(options: KeyWrapParams) => Promise<{ recoverableKeyPair: RecoverableKeyPair; }>

Generates a key pair that can be used for deriving key agreement secrets. The private key will be wrapped with the provided key reference or password. The generated key pair is returned in a structure of base64-encoded strings that may later be used to recover the key into the key store.

Param	Type
options	KeyWrapParams

Returns: Promise<{ recoverableKeyPair: RecoverableKeyPair; }>

---

generateRecoverableKey(...)

generateRecoverableKey(options: KeyWrapParams) => Promise<{ recoverableKey: RecoverableKey; }>

Generates a key that can be used for symmetric encryption / decryption. The key will be wrapped with the provided key reference or password. The generated key is returned as a structure of base64-encoded strings that may later be used to recover the key into the key store.

Param	Type
options	KeyWrapParams

Returns: Promise<{ recoverableKey: RecoverableKey; }>

---

importPublicSignatureKey(...)

importPublicSignatureKey(options: { alias: string; publicKey: string; }) => Promise<void>

Imports a public key into the key store. The key may then be used for verifying signatures. The key is expected to be in base64-encoded spki format.

Param	Type
options	{ alias: string; publicKey: string; }

---

importPublicAgreementKey(...)

importPublicAgreementKey(options: { alias: string; publicKey: string; }) => Promise<void>

Imports a public key into the key store. The key may then be used to derive key agreement secrets. The key is expected to be in base64-encoded spki format.

Param	Type
options	{ alias: string; publicKey: string; }

---

rewrapSignatureKeyPair(...)

rewrapSignatureKeyPair(options: { recoverableKeyPair: RecoverableKeyPair; unwrapWith: KeyUnwrapParams; rewrapWith: KeyWrapParams; }) => Promise<{ recoverableKeyPair: RecoverableKeyPair; }>

Re-wraps a recoverable signature key pair with a new key reference or password.

Param	Type
options	{ recoverableKeyPair: RecoverableKeyPair; unwrapWith: KeyUnwrapParams; rewrapWith: KeyWrapParams; }

Returns: Promise<{ recoverableKeyPair: RecoverableKeyPair; }>

---

rewrapAgreementKeyPair(...)

rewrapAgreementKeyPair(options: { recoverableKeyPair: RecoverableKeyPair; unwrapWith: KeyUnwrapParams; rewrapWith: KeyWrapParams; }) => Promise<{ recoverableKeyPair: RecoverableKeyPair; }>

Re-wraps a recoverable agreement key pair with a new key reference or password.

Param	Type
options	{ recoverableKeyPair: RecoverableKeyPair; unwrapWith: KeyUnwrapParams; rewrapWith: KeyWrapParams; }

Returns: Promise<{ recoverableKeyPair: RecoverableKeyPair; }>

---

rewrapKey(...)

rewrapKey(options: { recoverableKey: RecoverableKey | RecoverableKeyPair; unwrapWith: KeyUnwrapParams; rewrapWith: KeyWrapParams; }) => Promise<{ recoverableKey: RecoverableKey; }>

Re-wraps a recoverable key with a new key reference or password.

Param	Type
options	{ recoverableKey: RecoverableKeyPair | RecoverableKey; unwrapWith: KeyUnwrapParams; rewrapWith: KeyWrapParams; }

Returns: Promise<{ recoverableKey: RecoverableKey; }>

---

recoverKey(...)

recoverKey(options: { importAlias: string; recoverableKey: RecoverableKey; unwrapWith: KeyUnwrapParams; }) => Promise<void>

Unwraps and imports a previously-generated recoverable key into the key store. It may then be used to encrypt and decrypt values.

Param	Type
options	{ importAlias: string; recoverableKey: RecoverableKey; unwrapWith: KeyUnwrapParams; }

---

recoverAgreementKeyPair(...)

recoverAgreementKeyPair(options: { importAlias: string; recoverableKeyPair: RecoverableKeyPair; unwrapWith: KeyUnwrapParams; }) => Promise<void>

Unwraps and imports a previously-generated recoverable agreement key pair into the key store. It may then be used to encrypt and decrypt values.

Param	Type
options	{ importAlias: string; recoverableKeyPair: RecoverableKeyPair; unwrapWith: KeyUnwrapParams; }

---

recoverSignatureKeyPair(...)

recoverSignatureKeyPair(options: { importAlias: string; recoverableKeyPair: RecoverableKeyPair; unwrapWith: KeyUnwrapParams; }) => Promise<void>

Unwraps and imports a previously-generated recoverable signature key pair into the key store. It may then be used to sign and verify values.

Param	Type
options	{ importAlias: string; recoverableKeyPair: RecoverableKeyPair; unwrapWith: KeyUnwrapParams; }

---

encrypt(...)

encrypt(options: { encryptWith: KeyReference; cleartext: string; }) => Promise<{ encryptedMessage: EncryptedMessage; }>

Encrypts a string with a previously generated / recovered key or key pair. The encrypted string is returned in a structure of base64-encoded strings.

Param	Type
options	{ encryptWith: KeyReference; cleartext: string; }

Returns: Promise<{ encryptedMessage: EncryptedMessage; }>

---

decrypt(...)

decrypt(options: { decryptWith: KeyReference; encryptedMessage: EncryptedMessage; }) => Promise<{ cleartext: string; }>

Decrypts a string with a previously generated / recovered key or key pair.

Param	Type
options	{ decryptWith: KeyReference; encryptedMessage: EncryptedMessage; }

Returns: Promise<{ cleartext: string; }>

---

sign(...)

sign(options: { keyAlias: string; cleartext: string; }) => Promise<{ signature: string; }>

Signs a string with a previously generated / recovered signature key pair.

Param	Type
options	{ keyAlias: string; cleartext: string; }

Returns: Promise<{ signature: string; }>

---

verify(...)

verify(options: { keyAlias: string; cleartext: string; signature: string; }) => Promise<{ isValid: boolean; }>

Verifies a signature with a previously generated / recovered signature key pair or imported public key.

Param	Type
options	{ keyAlias: string; cleartext: string; signature: string; }

Returns: Promise<{ isValid: boolean; }>

---

Type Aliases

RecoverableKeyPair

PasswordEncryptedRecoverableKeyPair | KeyEncryptedRecoverableKeyPair

PasswordEncryptedRecoverableKeyPair

{ privateKey: PasswordEncryptedRecoverableKey, publicKey: string }

PasswordEncryptedRecoverableKey

EncryptedMessage & { salt: string }

EncryptedMessage

{ ciphertext: string, iv: string }

KeyEncryptedRecoverableKeyPair

{ privateKey: KeyEncryptedRecoverableKey, publicKey: string }

KeyEncryptedRecoverableKey

EncryptedMessage

KeyWrapParams

PasswordParamsMaybeSalt | KeyReference

PasswordParamsMaybeSalt

{ password: string, salt?: string }

KeyReference

SymmetricKeyReference | DerivedKeyReference

SymmetricKeyReference

{ keyAlias: string }

DerivedKeyReference

SymmetricKeyReference & { publicKeyAlias: string, info?: string }

RecoverableKey

PasswordEncryptedRecoverableKey | KeyEncryptedRecoverableKey

KeyUnwrapParams

PasswordParams | KeyReference

PasswordParams

{ password: string }