Cryptography
The Lisk Elements cryptography module provides all the cryptographic functionality necessary when interacting with the Lisk ecosystem.
Installation
This adds the Lisk client as a dependency of your project:
npm install @liskhq/lisk-cryptography@2.4.2
Usage
The lisk-cryptography
package can be used on both the server-side code and the client-side code.
In case the lisk-cryptography
is used server-side, it is beneficial to speed up the application by using the sodium-native library.
To perform this, expose NACL_FAST=enable
as the environment variable as shown below:
export NACL_FAST=enable
In order to switch back to the default library TweetNaCl.js, which is slower but can also be executed on the client-side, set it to disable
as shown below:
export NACL_FAST=disable
Alternatively, it can be unset completely by executing the following command:
unset NACL_FAST
Methods for converting between formats
Methods for converting between different formats.
intToBuffer
Converts an integer value to a buffer.
parseEncryptedPassphrase
This parses an encrypted passphrase string as an object.
Examples
const encryptedPassphrase = 'iterations=1000000&salt=bce40d3176e31998ec435ffc2993b280&cipherText=99bb7eff6755ecfe1dfa0368328c2d10589d7b85a23f75043497d7bdf7f14fb84e8caee1f9bc4b9543ba320e7f10801b0ff2065427d55c3139cf15e3b626b54f73b72a5b993323a6d60ec4aa407472ae&iv=51bcc76bbd0ab97b2292e305&tag=12e8fcfe7ad735fa9957baa48442e205&version=1';
cryptography.parseEncryptedPassphrase(encryptedPassphrase);
/* {
iterations: 1000000,
salt: 'bce40d3176e31998ec435ffc2993b280',
cipherText: '99bb7eff6755ecfe1dfa0368328c2d10589d7b85a23f75043497d7bdf7f14fb84e8caee1f9bc4b9543ba320e7f10801b0ff2065427d55c3139cf15e3b626b54f73b72a5b993323a6d60ec4aa407472ae',
iv: '51bcc76bbd0ab97b2292e305',
tag: '12e8fcfe7ad735fa9957baa48442e205',
version: '1',
} */
stringifyEncryptedPassphrase
This converts an encrypted passphrase object to a string for convenient storage.
Examples
const encryptedPassphrase = cryptography.encryptPassphraseWithPassword(
'robust swift grocery peasant forget share enable convince deputy road keep cheap',
'some secure password'
);
cryptography.stringifyEncryptedPassphrase(encryptedPassphrase); // 'iterations=1000000&salt=bce40d3176e31998ec435ffc2993b280&cipherText=99bb7eff6755ecfe1dfa0368328c2d10589d7b85a23f75043497d7bdf7f14fb84e8caee1f9bc4b9543ba320e7f10801b0ff2065427d55c3139cf15e3b626b54f73b72a5b993323a6d60ec4aa407472ae&iv=51bcc76bbd0ab97b2292e305&tag=12e8fcfe7ad735fa9957baa48442e205&version=1'
Methods for encrypting and decrypting
decryptMessageWithPassphrase
This decrypts a message that has been encrypted for a given public key using the corresponding passphrase as shown below:
Parameters
cipherHex
: The hex string representation of the encrypted message.
nonce
: The hex string representation of the nonce used during encryption.
passphrase
: The passphrase to be used in decryption.
senderPublicKey
: The public key of the message sender, (this is used to ensure the message was signed by the correct person).
Examples
const decryptedMessage = cryptography.decryptMessageWithPassphrase(
'7bef28e1ddb34902d2e006a36062805e597924c9885c142444bafb',
'5c29c9df3f041529a5f9ba07c444a86cbafbfd21413ec3a7',
'robust swift grocery peasant forget share enable convince deputy road keep cheap',
'9d3058175acab969f41ad9b86f7a2926c74258670fe56b37c429c01fca9f2f0f'
); // 'Hello Lisk!'
decryptPassphraseWithPassword
This decrypts a passphrase that has been encrypted using a password.
Parameters
-
encryptedPassphraseObject
: The output ofencryptPassphraseWithPassword
. Containsiterations
,cipherText
,iv
,salt
,tag
, andversion
. -
password
: The password to be used in decryption.
Examples
const encryptedPassphrase = {
iterations: 1000000,
salt: 'bce40d3176e31998ec435ffc2993b280',
cipherText: '99bb7eff6755ecfe1dfa0368328c2d10589d7b85a23f75043497d7bdf7f14fb84e8caee1f9bc4b9543ba320e7f10801b0ff2065427d55c3139cf15e3b626b54f73b72a5b993323a6d60ec4aa407472ae',
iv: '51bcc76bbd0ab97b2292e305',
tag: '12e8fcfe7ad735fa9957baa48442e205',
version: '1',
};
const decryptedPassphrase = cryptography.decryptPassphraseWithPassword(
encryptedPassphrase,
'some secure password'
); // 'robust swift grocery peasant forget share enable convince deputy road keep cheap'
encryptMessageWithPassphrase
This encrypts a message under a recipient’s public key, using a passphrase to create a signature.
Parameters
message
: The plaintext message to encrypt.
passphrase
: The passphrase used to sign the encryption and ensure message integrity.
recipientPublicKey
: The public key to be used in encryption.
Return value
object
: The result of encryption.
This contains the nonce
and encryptedMessage
, both in hex string format.
Examples
const encryptedMessage = cryptography.encryptMessageWithPassphrase(
'Hello Lisk!',
'robust swift grocery peasant forget share enable convince deputy road keep cheap',
'9d3058175acab969f41ad9b86f7a2926c74258670fe56b37c429c01fca9f2f0f'
);
/* {
encryptedMessage: '7bef28e1ddb34902d2e006a36062805e597924c9885c142444bafb',
nonce: '5c29c9df3f041529a5f9ba07c444a86cbafbfd21413ec3a7',
} */
encryptPassphraseWithPassword
This encrypts a passphrase under a password for secure storage.
Parameters
passphrase
: The passphrase in plaintext to encrypt.
password
: The password to be used in encryption.
iterations
: The number of iterations to use when deriving a key from the password using PBKDF2. (The default value if not provided is 1,000,000.)
Return value
object
: The result of encryption.
This contains the iterations
, cipherText
, iv
, salt
, tag
, and version
.
Examples
const encryptedPassphrase = cryptography.encryptPassphraseWithPassword(
'robust swift grocery peasant forget share enable convince deputy road keep cheap',
'some secure password',
);
/* {
iterations: 1000000,
salt: 'bce40d3176e31998ec435ffc2993b280',
cipherText: '99bb7eff6755ecfe1dfa0368328c2d10589d7b85a23f75043497d7bdf7f14fb84e8caee1f9bc4b9543ba320e7f10801b0ff2065427d55c3139cf15e3b626b54f73b72a5b993323a6d60ec4aa407472ae',
iv: '51bcc76bbd0ab97b2292e305',
tag: '12e8fcfe7ad735fa9957baa48442e205',
version: '1',
} */
Methods for hashing
getNetworkIdentifier
hash
Hashes an input using the SHA256 algorithm.
Parameters
-
data
: The data to hash provided as a buffer, or a string. -
format
: The format of the input data if provided as a string. This must be one ofhex
orutf8
.
Examples
cryptography.hash(Buffer.from([0xab, 0xcd, 0x12, 0x34])); // <Buffer 77 79 07 d5 4b 6a 45 02 bd 65 4c b4 ae 81 c5 f7 27 01 3b 5e 3b 93 cd 8b 53 d7 21 34 42 69 d3 b0>
cryptography.hash('abcd1234', 'hex'); // <Buffer 77 79 07 d5 4b 6a 45 02 bd 65 4c b4 ae 81 c5 f7 27 01 3b 5e 3b 93 cd 8b 53 d7 21 34 42 69 d3 b0>
cryptography.hash('abcd1234', 'utf8'); // <Buffer e9 ce e7 1a b9 32 fd e8 63 33 8d 08 be 4d e9 df e3 9e a0 49 bd af b3 42 ce 65 9e c5 45 0b 69 ae>
Methods for managing keys
getAddressAndPublicKeyFromPassphrase
This returns an object containing the address and public key for a provided passphrase.
getPrivateAndPublicKeyBytesFromPassphrase
This returns an object containing both the private and public keys as Uint8Array
s for a provided passphrase.
getPrivateAndPublicKeyFromPassphrase
This returns an object containing both the private and public keys as hex string
s for a provided passphrase.
Examples
cryptography.getPrivateAndPublicKeyFromPassphrase(
'robust swift grocery peasant forget share enable convince deputy road keep cheap'
);
/* {
privateKey: 'b092a6664e9eed658ff50fe796ee695b9fe5617e311e9e8a34eb340eb5b831549d3058175acab969f41ad9b86f7a2926c74258670fe56b37c429c01fca9f2f0f',
publicKey: '9d3058175acab969f41ad9b86f7a2926c74258670fe56b37c429c01fca9f2f0f',
} */
Methods for signing and verifying
printSignedMessage
This outputs a string representation of a signed message object which is suitable for printing.
Parameters
-
signedMessageObject
: The result of callingsignMessageWithPassphrase
orsignMessageWithTwoPassphrases
.
Examples
const stringToPrint = cryptography.printSignedMessage({
message: 'Hello Lisk!',
publicKey: '9d3058175acab969f41ad9b86f7a2926c74258670fe56b37c429c01fca9f2f0f',
signature: '125febe625b2d62381ff836c020de0b00297f7d2493fe6404bc6109fd70a55348555b7a66a35ac657d338d7fe329efd203da1602f4c88cc21934605676558401',
});
console.log(stringToPrint);
//-----BEGIN LISK SIGNED MESSAGE-----
//-----MESSAGE-----
//Hello Lisk!
//-----PUBLIC KEY-----
//9d3058175acab969f41ad9b86f7a2926c74258670fe56b37c429c01fca9f2f0f
//-----SIGNATURE-----
//125febe625b2d62381ff836c020de0b00297f7d2493fe6404bc6109fd70a55348555b7a66a35ac657d338d7fe329efd203da1602f4c88cc21934605676558401
//-----END LISK SIGNED MESSAGE-----
signAndPrintMessage
This signs a message with one or two passphrases and outputs a string representation which is suitable for printing.
Parameters
message
: The string message to sign.
passphrase
: The secret passphrase required in order to sign the message.
secondPassphrase
: The optional second secret passphrase used to sign the message.
Examples
const stringToPrint = cryptography.signAndPrintMessage('Hello Lisk!', 'robust swift grocery peasant forget share enable convince deputy road keep cheap');
console.log(stringToPrint);
// -----BEGIN LISK SIGNED MESSAGE-----
//-----MESSAGE-----
//Hello Lisk!
//-----PUBLIC KEY-----
//9d3058175acab969f41ad9b86f7a2926c74258670fe56b37c429c01fca9f2f0f
//-----SIGNATURE-----
//125febe625b2d62381ff836c020de0b00297f7d2493fe6404bc6109fd70a55348555b7a66a35ac657d338d7fe329efd203da1602f4c88cc21934605676558401
//-----END LISK SIGNED MESSAGE-----
signMessageWithPassphrase
Signs a message with a passphrase.
Parameters
message
: The string
message to sign.
passphrase
: The secret passphrase as string
used to sign the message.
Return value
object
: This contains the message
, the publicKey
corresponding to the passphrase, and the signature
as a hex string
.
Examples
cryptography.signMessageWithPassphrase('Hello Lisk!', 'robust swift grocery peasant forget share enable convince deputy road keep cheap');
/* {
message: 'Hello Lisk!',
publicKey: '9d3058175acab969f41ad9b86f7a2926c74258670fe56b37c429c01fca9f2f0f',
signature: '125febe625b2d62381ff836c020de0b00297f7d2493fe6404bc6109fd70a55348555b7a66a35ac657d338d7fe329efd203da1602f4c88cc21934605676558401',
} */
signMessageWithTwoPassphrases
This signs a message using a secret passphrase and a second secret passphrase.
Parameters
message
: The message to sign as a UTF8-encoded string or a buffer.
passphrase
: The secret passphrase to be used in signing.
secondPassphrase
: The second secret passphrase to be used in signing.
Return value
object
: This contains the message
(the original input), the publicKey
(for the passphrase as a hex string
), the secondPublicKey
(for the second passphrase as a hex string
), the signature
(as a hex string
), and finally the secondSignature
(as a hex string
).
Examples
cryptography.signMessageWithTwoPassphrases(
'Hello Lisk!',
'robust swift grocery peasant forget share enable convince deputy road keep cheap',
'weapon van trap again sustain write useless great pottery urge month nominee',
);
/* {
message: 'Hello Lisk!',
publicKey: '9d3058175acab969f41ad9b86f7a2926c74258670fe56b37c429c01fca9f2f0f',
secondPublicKey: '141b16ac8d5bd150f16b1caa08f689057ca4c4434445e56661831f4e671b7c0a',
signature: '125febe625b2d62381ff836c020de0b00297f7d2493fe6404bc6109fd70a55348555b7a66a35ac657d338d7fe329efd203da1602f4c88cc21934605676558401',
secondSignature: '97196d262823166ec9ae5145238479effe00204e763d43cc9539cc711277a6652e8266aace3622f9e8a08cd5de08115c06db15fee71a44a98172cfab58f91c01',
} */
verifyMessageWithPublicKey
This verifies that a signature for a given message matches the provided public key.
Examples
cryptography.verifyMessageWithPublicKey({
message: 'Hello Lisk!',
publicKey: '9d3058175acab969f41ad9b86f7a2926c74258670fe56b37c429c01fca9f2f0f',
signature: '125febe625b2d62381ff836c020de0b00297f7d2493fe6404bc6109fd70a55348555b7a66a35ac657d338d7fe329efd203da1602f4c88cc21934605676558401',
}); // true
verifyMessageWithTwoPublicKeys
This verifies that a signature and second signature for a given message match the provided public keys.
Examples
cryptography.verifyMessageWithTwoPublicKeys({
message: 'Hello Lisk!',
publicKey: '9d3058175acab969f41ad9b86f7a2926c74258670fe56b37c429c01fca9f2f0f',
secondPublicKey: '141b16ac8d5bd150f16b1caa08f689057ca4c4434445e56661831f4e671b7c0a',
signature: '125febe625b2d62381ff836c020de0b00297f7d2493fe6404bc6109fd70a55348555b7a66a35ac657d338d7fe329efd203da1602f4c88cc21934605676558401',
secondSignature: '97196d262823166ec9ae5145238479effe00204e763d43cc9539cc711277a6652e8266aace3622f9e8a08cd5de08115c06db15fee71a44a98172cfab58f91c01',
}); // true