@substrate-system/keys
    Preparing search index...

    Class EccKeys

    Class for ECC keys

    Hierarchy (View Summary)

    Index
    _exchangeKey: CryptoKeyPair | null
    _writeKey: CryptoKeyPair | null
    destroyed: boolean

    Have these keys been deleted? A deleted keypair is terminal -- the key material is gone, and any use of it throws.

    DID: `did:key:z${string}`
    exchangeKeyName: string

    The indexedDB names this keypair was loaded from, and the names persist and delete will use.

    hasPersisted: boolean
    isSessionOnly: boolean
    writeKeyName: string
    _instance: any
    EXCHANGE_KEY_NAME: string = DEFAULT_ECC_EXCHANGE
    INFO: string = 'keys'
    TYPE: "ecc" | "rsa" = ...
    WRITE_KEY_NAME: string = DEFAULT_ECC_WRITE
    • get deviceName(): Promise<string>

      The machine-readable name for this keypair.

      Returns Promise<string>

    • get exchangeKey(): CryptoKeyPair

      Returns CryptoKeyPair

    • get privateExchangeKey(): CryptoKey

      Returns CryptoKey

    • get privateWriteKey(): CryptoKey

      Returns CryptoKey

    • get publicExchangeKey(): CryptoKey & {
          asString: (format?: SupportedEncodings) => Promise<string>;
      }

      Returns CryptoKey & { asString: (format?: SupportedEncodings) => Promise<string> }

    • get publicWriteKey(): CryptoKey & {
          asString: (format?: SupportedEncodings) => Promise<string>;
      }

      Returns CryptoKey & { asString: (format?: SupportedEncodings) => Promise<string> }

    • get writeKey(): CryptoKeyPair

      Returns CryptoKeyPair

    • Decrypt the given message. The encrypted message should be ephemeral public key + salt + iv + cipher text.

      The ephemeral public key is extracted from the beginning of the message and used with our private key to derive the AES decryption key.

      Parameters

      • msg: string | ArrayBuffer | Uint8Array<ArrayBufferLike>

        The encrypted content

      • OptionalaesAlgorithm: string | null

        The algorithm. Default is AES-GCM.

      • Optionalinfo: string | null

        Custom "info" parameter

      • OptionalaesKey: string | Uint8Array<ArrayBufferLike> | CryptoKey | null

        Use this exact AES key instead of deriving one from ECDH. Must match the aesKey passed to the corresponding encrypt call.

      Returns Promise<ArrayBuffer | Uint8Array<ArrayBufferLike>>

      The decrypted content.

    • Decrypt and return as string using ECIES. The encrypted message should be ephemeral public key + salt + iv + cipher text.

      The ephemeral public key is extracted from the beginning of the message and used with our private key to derive the AES decryption key.

      Parameters

      • msg: string | ArrayBuffer | Uint8Array<ArrayBufferLike>

        The encrypted content

      • OptionalaesAlgorithm: string | null

        The algorithm. Default is AES-GCM.

      • Optionalinfo: string | null

        Custom "info" parameter

      • OptionalaesKey: string | Uint8Array<ArrayBufferLike> | CryptoKey | null

      Returns Promise<string>

      The decrypted content as a string.

    • Delete this keypair. This deletes the keys from indexedDB, drops the in-memory key material, and clears the instance cache, so load will not hand out these keys again.

      After this, the instance is destroyed -- using it throws a KeysDeletedError.

      Returns Promise<void>

    • Encrypt the given content to the given public key, or encrypt to our own public key if a key is not passed in.

      This does ECIES style encryption -- a new ephemeral keypair is generated and used to encrypt the message with ephemeral private + recipient public. The public key from the ephemeral keypair is prefixed to the cipher text.

      Parameters

      • content: string | Uint8Array<ArrayBufferLike>

        Content to encrypt

      • Optionalrecipient: string | CryptoKey | null

        Their public key. Optional b/c we will use our own public key if not passed in. Can be a CryptoKey or a base64 encoded string.

      • Optionalinfo: string | null

        info tag for HKDF. Default is the class property.

      • OptionalaesKey: string | Uint8Array<ArrayBufferLike> | CryptoKey | null

        Use this exact AES key instead of deriving one from ECDH. Not relevant for most use cases. Pass the same key to decrypt to read it back.

      • Optionalkeysize: SymmKeyLength | null

        Default is 256

      Returns Promise<Uint8Array<ArrayBufferLike>>

      Buffer of ephemeral-public-key + salt + iv + cipher text

    • Encrypt and return as base64 string.

      Parameters

      • content: string | Uint8Array<ArrayBufferLike>
      • Optionalrecipient: string | CryptoKey | null
      • Optionalinfo: string | null
      • OptionalaesKey: string | Uint8Array<ArrayBufferLike> | CryptoKey | null
      • Optionalkeysize: SymmKeyLength | null

      Returns Promise<string>

    • Do DHKE, create a new AES-GCM key.

      The HKDF salt is either supplied by the caller (so both sides can re-derive the exact same key later) or generated at random, in which case it is returned as a .salt (base64) property on the key so the caller can persist it for later re-derivation.

      Parameters

      • OptionalpublicKey: string | CryptoKey | null

        Public key to use in DHKE. Will use our public key if it is not passed in.

      • Optionalinfo: string | null

        The info parameter for DHKE. Will use the class property INFO if it is not passed in.

      • Optionalsalt: string | ArrayBuffer | Uint8Array<ArrayBufferLike> | null

        Reuse this salt instead of generating a random one -- pass the same salt on both sides to re-derive the same key.

      Returns Promise<CryptoKey & { salt: string }>

      New AES key, with a .salt (base64) property

    • Serialize this keys instance. Will return an object of { DID, publicExchangeKey }, where DID is the public write key, and publicExchangeKey is the encryption key, base64 encoded.

      Parameters

      • Optionalformat: SupportedEncodings

      Returns Promise<{ DID: `did:key:z${string}`; publicExchangeKey: string }>

    • Unwrap a content key that another device wrapped for this device with wrap.

      The recipient device uses its private key + the ephemeral public key to rederive the KEK and decrypt the wrapped content key.

      The wrap's signature is always checked against signer before anything is decrypted, and this throws if the signature is missing or invalid. signer must be the DID of the device you expect the key from, obtained over a channel an attacker cannot tamper with. A DID that travels alongside the wrapped key proves nothing, since an attacker who can swap the wrapped key can swap the DID too.

      Parameters

      • wrapped: WrappedKey

        The { enc, wrappedKey, signature } object returned by wrap.

      • signer: `did:key:z${string}`

        The DID of the expected sender.

      • opts: { extractable?: boolean; info?: string } = {}
        • Optionalextractable?: boolean

          Can the returned key be exported with crypto.subtle.exportKey? Default true.

        • Optionalinfo?: string

          The HKDF info string. Must match what was passed to wrap. Defaults to 'key-wrap'.

      Returns Promise<CryptoKey>

      The unwrapped AES content key.

    • "Add a device," meaning, take an existing AES key and add the ability for a new keypair to decrypt/use the AES key.

      This implements HPKE-style key wrapping:

      1. Generate ephemeral X25519 keypair
      2. Do ECDH with recipient's public key -> shared secret
      3. Use HKDF to derive a KEK (key encryption key)
      4. AES-GCM encrypt the content
      5. Return the ephemeral public key (encapsulation) + wrapped key

      The result is signed with our Ed25519 write key, so the recipient can verify who created the wrap. unwrap requires our DID and rejects the wrap unless the signature matches it.

      Parameters

      • contentKey: string | Uint8Array<ArrayBufferLike> | CryptoKey

        The existing AES key used to encrypt the content. Can be a base64 encoded string.

      • newPublicKey: CryptoKey

        The new device's public X25519 key.

      • Optionalinfo: string

        Optional info parameter for HKDF. Defaults to 'key-wrap'.

      Returns Promise<WrappedKey>

      The ephemeral public key (base64), the wrapped AES key (base64), and a signature (base64) by our write key.

    • If the cached instance was loaded from the given names, then its keys are gone too. Destroy it, and clear the cache. Internal.

      Parameters

      • exchangeName: string
      • writeName: string

      Returns void

    • The indexedDB names for this class, optionally prefixed with dbKey. Pure -- never writes to the class statics.

      Parameters

      • OptionaldbKey: string

      Returns { exchangeKeyName: string; writeKeyName: string }

    • Factory function.

      Type Parameters

      Parameters

      • Optionalsession: boolean

        Session only? i.e., not saved in indexedDB. Default false.

      • Optionalextractable: boolean

        Can we extract the private keys? Default false.

      • Optionalkeys: {
            dbKey?: string;
            exchangeKeys?: CryptoKeyPair | null;
            writeKeys?: CryptoKeyPair | null;
        }

        Key options. dbKey prefixes the IndexedDB names used for both keypairs.

      Returns Promise<T>

      A new class instance.

    • Delete a stored keypair without loading it first. Deletes the keys from indexedDB, and destroys the cached instance, if there is one for these names.

      Parameters

      • Optionalopts: { encryptionKeyName?: string; writeKeyName?: string } = {}

        The indexedDB names to delete. Defaults to this class's names.

      Returns Promise<void>

    • Return a 32-character, DNS-friendly hash of the given DID.

      Parameters

      • did: `did:key:z${string}`

        A DID format string

      Returns Promise<string>

      32 character, base32 hash of the DID

    • Parameters

      • opts: { encryptionKeyName?: string; writeKeyName?: string } = {}

      Returns Promise<boolean>

    • Restore some keys from indexedDB, or create a new keypair if it doesn't exist yet. Overrides base class to use ECC-specific key names.

      Saves the keys to indexedDB before returning, unless you pass { persist: false }.

      Type Parameters

      Parameters

      • this: typeof EccKeys
      • Optionalopts: Partial<
            {
                dbKey: string;
                encryptionKeyName: string;
                extractable: boolean;
                persist: boolean;
                session: boolean;
                writeKeyName: string;
            },
        > = ...

        Prefix for both IndexedDB key names.

      Returns Promise<T>