cipherKeyValue.md

Symmetric key-value encryption

Cipher key value provides symmetric encryption in the Trezor device where the user might be forced to confirm the encryption/decryption on the display. The key for the encryption is constructed from the private key on the BIP address, the key displayed on the device, and the two informations about whether to ask for confirmation. It is constructed in such a way, that different path, key or the confirm information will get a different encryption key and IV. So, you cannot "skip" the confirmation by using different input. IV can be either manually set, or it is computed together with the key.The value must be divisible into 16-byte blocks. The application has to pad the blocks itself and ensure safety; for example, by using PKCS7.

More information can be found in SLIP-0011.

ES6

const result = await TrezorConnect.cipherKeyValue(params);

CommonJS

TrezorConnect.cipherKeyValue(params).then(function(result) {

});

Params

Optional common params
Common parameter useEmptyPassphrase - is always set to true and it will be ignored by this method

Encrypt single value

• path — required string | Array<number> minimum length is 1. read more
• key — optional string a message shown on device
• value — optional string hexadecimal value with length a multiple of 16 bytes (32 letters in hexadecimal). Value is what is actually being encrypted.
• askOnEncrypt - optional boolean should user confirm encrypt?
• askOnDecrypt - optional boolean should user confirm decrypt?
• iv - optional string initialization vector - keep unset if you don't know what it means, it will be computed automatically.

Encrypt multiple values

• bundle - Array of Objects with path, key, value, askOnEncrypt, askOnDecrypt fields

Example

Return encrypted value:

TrezorConnect.cipherKeyValue({
    path: "m/49'/0'/0'",
    key: "This text is displayed on Trezor during encrypt",
    value: "1c0ffeec0ffeec0ffeec0ffeec0ffee1",
    encrypt: true,
    askOnEncrypt: true,
    askOnDecrypt: true
});

Return a bundle of encrypted values:

TrezorConnect.cipherKeyValue({
    bundle: [
        { path: "m/49'/0'/0'", key: "1 text on Trezor", value: "1c0ffeec0ffeec0ffeec0ffeec0ffee1", encrypt: true  },
        { path: "m/49'/0'/1'", key: "2 text on Trezor", value: "1c0ffeec0ffeec0ffeec0ffeec0ffee1", encrypt: false },
        { path: "m/49'/0'/2'", key: "3 text on Trezor", value: "1c0ffeec0ffeec0ffeec0ffeec0ffee1" }
    ]
});

Result

Result with only one value

{
    success: true,
    payload: {
        value: string
    }
}

Result with bundle of values

{
    success: true,
    payload: [
        { value: string },
        { value: string },
        { value: string }
    ]
}

Error

{
    success: false,
    payload: {
        error: string // error message
    }
}

Migration from older version

version 4 and below:

TrezorConnect.cipherKeyValue(
    "m/49'/0'/0'",     // path
    "This is displayed on Trezor during encrypt", // key
    "1c0ffeec0ffeec0ffeec0ffeec0ffee1",           // value
    true,              // encrypt
    true,              // ask on encrypt
    true,              // ask on decrypt
    function(result) { // callback
        // result not changed
    }
);

version 5

// params are key-value pairs inside Object
TrezorConnect.cipherKeyValue({ 
    path: "m/49'/0'/0'",
    key: "This is displayed on Trezor during encrypt",
    value: "1c0ffeec0ffeec0ffeec0ffeec0ffee1",
    encrypt: true,
    askOnEncrypt: true,
    askOnDecrypt: true
}).then(function(result) {
    // result not changed
})