Module crypto
Module crypto
Crypto functions.
Functions
factorize – Integer factorization
modular_power – Modular exponentiation
ton_crc16 – Calculates CRC16 using TON algorithm.
generate_random_bytes – Generates random byte array of the specified length and returns it in base64
format
convert_public_key_to_ton_safe_format – Converts public key to ton safe_format
generate_random_sign_keys – Generates random ed25519 key pair.
sign – Signs a data using the provided keys.
verify_signature – Verifies signed data using the provided public key. Raises error if verification is failed.
sha256 – Calculates SHA256 hash of the specified data.
sha512 – Calculates SHA512 hash of the specified data.
scrypt – Perform scrypt
encryption
nacl_sign_keypair_from_secret_key – Generates a key pair for signing from the secret key
nacl_sign – Signs data using the signer's secret key.
nacl_sign_open – Verifies the signature and returns the unsigned message
nacl_sign_detached – Signs the message using the secret key and returns a signature.
nacl_sign_detached_verify – Verifies the signature with public key and unsigned
data.
nacl_box_keypair – Generates a random NaCl key pair
nacl_box_keypair_from_secret_key – Generates key pair from a secret key
nacl_box – Public key authenticated encryption
nacl_box_open – Decrypt and verify the cipher text using the receivers secret key, the senders public key, and the nonce.
nacl_secret_box – Encrypt and authenticate message using nonce and secret key.
nacl_secret_box_open – Decrypts and verifies cipher text using nonce
and secret key
.
mnemonic_words – Prints the list of words from the specified dictionary
mnemonic_from_random – Generates a random mnemonic
mnemonic_from_entropy – Generates mnemonic from pre-generated entropy
mnemonic_verify – Validates a mnemonic phrase
mnemonic_derive_sign_keys – Derives a key pair for signing from the seed phrase
hdkey_xprv_from_mnemonic – Generates an extended master private key that will be the root for all the derived keys
hdkey_derive_from_xprv – Returns extended private key derived from the specified extended private key and child index
hdkey_derive_from_xprv_path – Derives the extended private key from the specified key and path
hdkey_secret_from_xprv – Extracts the private key from the serialized extended private key
hdkey_public_from_xprv – Extracts the public key from the serialized extended private key
chacha20 – Performs symmetric chacha20
encryption.
create_crypto_box – Creates a Crypto Box instance.
remove_crypto_box – Removes Crypto Box. Clears all secret data.
get_crypto_box_info – Get Crypto Box Info. Used to get encrypted_secret
that should be used for all the cryptobox initializations except the first one.
get_crypto_box_seed_phrase – Get Crypto Box Seed Phrase.
get_signing_box_from_crypto_box – Get handle of Signing Box derived from Crypto Box.
get_encryption_box_from_crypto_box – Gets Encryption Box from Crypto Box.
clear_crypto_box_secret_cache – Removes cached secrets (overwrites with zeroes) from all signing and encryption boxes, derived from crypto box.
register_signing_box – Register an application implemented signing box.
get_signing_box – Creates a default signing box implementation.
signing_box_get_public_key – Returns public key of signing key pair.
signing_box_sign – Returns signed user data.
remove_signing_box – Removes signing box from SDK.
register_encryption_box – Register an application implemented encryption box.
remove_encryption_box – Removes encryption box from SDK
encryption_box_get_info – Queries info from the given encryption box
encryption_box_encrypt – Encrypts data using given encryption box Note.
encryption_box_decrypt – Decrypts data using given encryption box Note.
create_encryption_box – Creates encryption box with specified algorithm
Types
EncryptionBoxInfo – Encryption box information.
EncryptionAlgorithmChaCha20Variant
EncryptionAlgorithmNaclBoxVariant
EncryptionAlgorithmNaclSecretBoxVariant
CryptoBoxSecretRandomSeedPhraseVariant – Creates Crypto Box from a random seed phrase. This option can be used if a developer doesn't want the seed phrase to leave the core library's memory, where it is stored encrypted.
CryptoBoxSecretPredefinedSeedPhraseVariant – Restores crypto box instance from an existing seed phrase. This type should be used when Crypto Box is initialized from a seed phrase, entered by a user.
CryptoBoxSecretEncryptedSecretVariant – Use this type for wallet reinitializations, when you already have encrypted_secret
on hands. To get encrypted_secret
, use get_crypto_box_info
function after you initialized your crypto box for the first time.
CryptoBoxSecret – Crypto Box Secret.
BoxEncryptionAlgorithmChaCha20Variant
BoxEncryptionAlgorithmNaclBoxVariant
BoxEncryptionAlgorithmNaclSecretBoxVariant
ParamsOfConvertPublicKeyToTonSafeFormat
ResultOfConvertPublicKeyToTonSafeFormat
ParamsOfNaclSignKeyPairFromSecret
ParamsOfNaclSignDetachedVerify
ResultOfNaclSignDetachedVerify
ParamsOfNaclBoxKeyPairFromSecret
ParamsOfMnemonicDeriveSignKeys
ParamsOfHDKeyDeriveFromXPrvPath
ResultOfHDKeyDeriveFromXPrvPath
ParamsOfAppPasswordProviderGetPasswordVariant
ParamsOfAppPasswordProvider – Interface that provides a callback that returns an encrypted password, used for cryptobox secret encryption
ResultOfAppPasswordProviderGetPasswordVariant
ResultOfGetCryptoBoxSeedPhrase
ParamsOfGetSigningBoxFromCryptoBox
ParamsOfGetEncryptionBoxFromCryptoBox
ParamsOfAppSigningBoxGetPublicKeyVariant – Get signing box public key
ParamsOfAppSigningBoxSignVariant – Sign data
ParamsOfAppSigningBox – Signing box callbacks.
ResultOfAppSigningBoxGetPublicKeyVariant – Result of getting public key
ResultOfAppSigningBoxSignVariant – Result of signing data
ResultOfAppSigningBox – Returning values from signing box callbacks.
ResultOfSigningBoxGetPublicKey
ParamsOfAppEncryptionBoxGetInfoVariant – Get encryption box info
ParamsOfAppEncryptionBoxEncryptVariant – Encrypt data
ParamsOfAppEncryptionBoxDecryptVariant – Decrypt data
ParamsOfAppEncryptionBox – Interface for data encryption/decryption
ResultOfAppEncryptionBoxGetInfoVariant – Result of getting encryption box info
ResultOfAppEncryptionBoxEncryptVariant – Result of encrypting data
ResultOfAppEncryptionBoxDecryptVariant – Result of decrypting data
ResultOfAppEncryptionBox – Returning values from signing box callbacks.
AppPasswordProvider – Interface that provides a callback that returns an encrypted password, used for cryptobox secret encryption
AppSigningBox – Signing box callbacks.
AppEncryptionBox – Interface for data encryption/decryption
Functions
factorize
Integer factorization
Performs prime factorization – decomposition of a composite number into a product of smaller prime integers (factors). See [https://en.wikipedia.org/wiki/Integer_factorization]
NOTE: Sync version is available only for lib-node
binding.
Parameters
composite
: string – Hexadecimal representation of u64 composite number.
Result
factors
: string[] – Two factors of composite or empty if composite can't be factorized.
modular_power
Modular exponentiation
Performs modular exponentiation for big integers (base
^exponent
mod modulus
). See [https://en.wikipedia.org/wiki/Modular_exponentiation]
NOTE: Sync version is available only for lib-node
binding.
Parameters
base
: string –base
argument of calculation.exponent
: string –exponent
argument of calculation.modulus
: string –modulus
argument of calculation.
Result
modular_power
: string – Result of modular exponentiation
ton_crc16
Calculates CRC16 using TON algorithm.
NOTE: Sync version is available only for lib-node
binding.
Parameters
data
: string – Input data for CRC calculation. Encoded withbase64
.
Result
crc
: number – Calculated CRC for input data.
generate_random_bytes
Generates random byte array of the specified length and returns it in base64
format
NOTE: Sync version is available only for lib-node
binding.
Parameters
length
: number – Size of random byte array.
Result
bytes
: string – Generated bytes encoded inbase64
.
convert_public_key_to_ton_safe_format
Converts public key to ton safe_format
NOTE: Sync version is available only for lib-node
binding.
Parameters
public_key
: string – Public key - 64 symbols hex string
Result
ton_public_key
: string – Public key represented in TON safe format.
generate_random_sign_keys
Generates random ed25519 key pair.
NOTE: Sync version is available only for lib-node
binding.
Result
public
: string – Public key - 64 symbols hex stringsecret
: string – Private key - u64 symbols hex string
sign
Signs a data using the provided keys.
NOTE: Sync version is available only for lib-node
binding.
Parameters
unsigned
: string – Data that must be signed encoded inbase64
.keys
: KeyPair – Sign keys.
Result
signed
: string – Signed data combined with signature encoded inbase64
.signature
: string – Signature encoded inhex
.
verify_signature
Verifies signed data using the provided public key. Raises error if verification is failed.
NOTE: Sync version is available only for lib-node
binding.
Parameters
signed
: string – Signed data that must be verified encoded inbase64
.public
: string – Signer's public key - 64 symbols hex string
Result
unsigned
: string – Unsigned data encoded inbase64
.
sha256
Calculates SHA256 hash of the specified data.
NOTE: Sync version is available only for lib-node
binding.
Parameters
data
: string – Input data for hash calculation. Encoded withbase64
.
Result
hash
: string – Hash of inputdata
. Encoded with 'hex'.
sha512
Calculates SHA512 hash of the specified data.
NOTE: Sync version is available only for lib-node
binding.
Parameters
data
: string – Input data for hash calculation. Encoded withbase64
.
Result
hash
: string – Hash of inputdata
. Encoded with 'hex'.
scrypt
Perform scrypt
encryption
Derives key from password
and key
using scrypt
algorithm. See [https://en.wikipedia.org/wiki/Scrypt].
Arguments
log_n
- The log2 of the Scrypt parameterN
r
- The Scrypt parameterr
p
- The Scrypt parameterp
Conditions
log_n
must be less than64
r
must be greater than0
and less than or equal to4294967295
p
must be greater than0
and less than4294967295
Recommended values sufficient for most use-cases
log_n = 15
(n = 32768
)r = 8
p = 1
NOTE: Sync version is available only for lib-node
binding.
Parameters
password
: string – The password bytes to be hashed. Must be encoded withbase64
.salt
: string – Salt bytes that modify the hash to protect against Rainbow table attacks. Must be encoded withbase64
.log_n
: number – CPU/memory cost parameterr
: number – The block size parameter, which fine-tunes sequential memory read size and performance.p
: number – Parallelization parameter.dk_len
: number – Intended output length in octets of the derived key.
Result
key
: string – Derived key. Encoded withhex
.
nacl_sign_keypair_from_secret_key
Generates a key pair for signing from the secret key
NOTE: In the result the secret key is actually the concatenation of secret and public keys (128 symbols hex string) by design of NaCL. See also the stackexchange question.
NOTE: Sync version is available only for lib-node
binding.
Parameters
secret
: string – Secret key - unprefixed 0-padded to 64 symbols hex string
Result
public
: string – Public key - 64 symbols hex stringsecret
: string – Private key - u64 symbols hex string
nacl_sign
Signs data using the signer's secret key.
NOTE: Sync version is available only for lib-node
binding.
Parameters
unsigned
: string – Data that must be signed encoded inbase64
.secret
: string – Signer's secret key - unprefixed 0-padded to 128 symbols hex string (concatenation of 64 symbols secret and 64 symbols public keys). Seenacl_sign_keypair_from_secret_key
.
Result
signed
: string – Signed data, encoded inbase64
.
nacl_sign_open
Verifies the signature and returns the unsigned message
Verifies the signature in signed
using the signer's public key public
and returns the message unsigned
.
If the signature fails verification, crypto_sign_open raises an exception.
NOTE: Sync version is available only for lib-node
binding.
Parameters
signed
: string – Signed data that must be unsigned. Encoded withbase64
.public
: string – Signer's public key - unprefixed 0-padded to 64 symbols hex string
Result
unsigned
: string – Unsigned data, encoded inbase64
.
nacl_sign_detached
Signs the message using the secret key and returns a signature.
Signs the message unsigned
using the secret key secret
and returns a signature signature
.
NOTE: Sync version is available only for lib-node
binding.
Parameters
unsigned
: string – Data that must be signed encoded inbase64
.secret
: string – Signer's secret key - unprefixed 0-padded to 128 symbols hex string (concatenation of 64 symbols secret and 64 symbols public keys). Seenacl_sign_keypair_from_secret_key
.
Result
signature
: string – Signature encoded inhex
.
nacl_sign_detached_verify
Verifies the signature with public key and unsigned
data.
NOTE: Sync version is available only for lib-node
binding.
Parameters
unsigned
: string – Unsigned data that must be verified. Encoded withbase64
.signature
: string – Signature that must be verified. Encoded withhex
.public
: string – Signer's public key - unprefixed 0-padded to 64 symbols hex string.
Result
succeeded
: boolean –true
if verification succeeded orfalse
if it failed
nacl_box_keypair
Generates a random NaCl key pair
NOTE: Sync version is available only for lib-node
binding.
Result
public
: string – Public key - 64 symbols hex stringsecret
: string – Private key - u64 symbols hex string
nacl_box_keypair_from_secret_key
Generates key pair from a secret key
NOTE: Sync version is available only for lib-node
binding.
Parameters
secret
: string – Secret key - unprefixed 0-padded to 64 symbols hex string
Result
public
: string – Public key - 64 symbols hex stringsecret
: string – Private key - u64 symbols hex string
nacl_box
Public key authenticated encryption
Encrypt and authenticate a message using the senders secret key, the receivers public key, and a nonce.
NOTE: Sync version is available only for lib-node
binding.
Parameters
decrypted
: string – Data that must be encrypted encoded inbase64
.nonce
: string – Nonce, encoded inhex
their_public
: string – Receiver's public key - unprefixed 0-padded to 64 symbols hex stringsecret
: string – Sender's private key - unprefixed 0-padded to 64 symbols hex string
Result
encrypted
: string – Encrypted data encoded inbase64
.
nacl_box_open
Decrypt and verify the cipher text using the receivers secret key, the senders public key, and the nonce.
NOTE: Sync version is available only for lib-node
binding.
Parameters
encrypted
: string – Data that must be decrypted. Encoded withbase64
.nonce
: string – Noncetheir_public
: string – Sender's public key - unprefixed 0-padded to 64 symbols hex stringsecret
: string – Receiver's private key - unprefixed 0-padded to 64 symbols hex string
Result
decrypted
: string – Decrypted data encoded inbase64
.
nacl_secret_box
Encrypt and authenticate message using nonce and secret key.
NOTE: Sync version is available only for lib-node
binding.
Parameters
decrypted
: string – Data that must be encrypted. Encoded withbase64
.nonce
: string – Nonce inhex
key
: string – Secret key - unprefixed 0-padded to 64 symbols hex string
Result
encrypted
: string – Encrypted data encoded inbase64
.
nacl_secret_box_open
Decrypts and verifies cipher text using nonce
and secret key
.
NOTE: Sync version is available only for lib-node
binding.
Parameters
encrypted
: string – Data that must be decrypted. Encoded withbase64
.nonce
: string – Nonce inhex
key
: string – Secret key - unprefixed 0-padded to 64 symbols hex string
Result
decrypted
: string – Decrypted data encoded inbase64
.
mnemonic_words
Prints the list of words from the specified dictionary
NOTE: Sync version is available only for lib-node
binding.
Parameters
dictionary
?: MnemonicDictionary – Dictionary identifier
Result
words
: string – The list of mnemonic words
mnemonic_from_random
Generates a random mnemonic
Generates a random mnemonic from the specified dictionary and word count
NOTE: Sync version is available only for lib-node
binding.
Parameters
dictionary
?: MnemonicDictionary – Dictionary identifierword_count
?: number – Mnemonic word count
Result
phrase
: string – String of mnemonic words
mnemonic_from_entropy
Generates mnemonic from pre-generated entropy
NOTE: Sync version is available only for lib-node
binding.
Parameters
entropy
: string – Entropy bytes. Hex encoded.dictionary
?: MnemonicDictionary – Dictionary identifierword_count
?: number – Mnemonic word count
Result
phrase
: string – Phrase
mnemonic_verify
Validates a mnemonic phrase
The phrase supplied will be checked for word length and validated according to the checksum specified in BIP0039.
NOTE: Sync version is available only for lib-node
binding.
Parameters
phrase
: string – Phrasedictionary
?: MnemonicDictionary – Dictionary identifierword_count
?: number – Word count
Result
valid
: boolean – Flag indicating if the mnemonic is valid or not
mnemonic_derive_sign_keys
Derives a key pair for signing from the seed phrase
Validates the seed phrase, generates master key and then derives the key pair from the master key and the specified path
NOTE: Sync version is available only for lib-node
binding.
Parameters
phrase
: string – Phrasepath
?: string – Derivation path, for instance "m/44'/396'/0'/0/0"dictionary
?: MnemonicDictionary – Dictionary identifierword_count
?: number – Word count
Result
public
: string – Public key - 64 symbols hex stringsecret
: string – Private key - u64 symbols hex string
hdkey_xprv_from_mnemonic
Generates an extended master private key that will be the root for all the derived keys
NOTE: Sync version is available only for lib-node
binding.
Parameters
phrase
: string – String with seed phrasedictionary
?: MnemonicDictionary – Dictionary identifierword_count
?: number – Mnemonic word count
Result
xprv
: string – Serialized extended master private key
hdkey_derive_from_xprv
Returns extended private key derived from the specified extended private key and child index
NOTE: Sync version is available only for lib-node
binding.
Parameters
xprv
: string – Serialized extended private keychild_index
: number – Child index (see BIP-0032)hardened
: boolean – Indicates the derivation of hardened/not-hardened key (see BIP-0032)
Result
xprv
: string – Serialized extended private key
hdkey_derive_from_xprv_path
Derives the extended private key from the specified key and path
NOTE: Sync version is available only for lib-node
binding.
Parameters
xprv
: string – Serialized extended private keypath
: string – Derivation path, for instance "m/44'/396'/0'/0/0"
Result
xprv
: string – Derived serialized extended private key
hdkey_secret_from_xprv
Extracts the private key from the serialized extended private key
NOTE: Sync version is available only for lib-node
binding.
Parameters
xprv
: string – Serialized extended private key
Result
secret
: string – Private key - 64 symbols hex string
hdkey_public_from_xprv
Extracts the public key from the serialized extended private key
NOTE: Sync version is available only for lib-node
binding.
Parameters
xprv
: string – Serialized extended private key
Result
public
: string – Public key - 64 symbols hex string
chacha20
Performs symmetric chacha20
encryption.
NOTE: Sync version is available only for lib-node
binding.
Parameters
data
: string – Source data to be encrypted or decrypted. Must be encoded withbase64
.key
: string – 256-bit key. Must be encoded withhex
.nonce
: string – 96-bit nonce. Must be encoded withhex
.
Result
data
: string – Encrypted/decrypted data. Encoded withbase64
.
create_crypto_box
Creates a Crypto Box instance.
Crypto Box is a root crypto object, that encapsulates some secret (seed phrase usually) in encrypted form and acts as a factory for all crypto primitives used in SDK: keys for signing and encryption, derived from this secret.
Crypto Box encrypts original Seed Phrase with salt and password that is retrieved from password_provider
callback, implemented on Application side.
When used, decrypted secret shows up in core library's memory for a very short period of time and then is immediately overwritten with zeroes.
NOTE: Sync version is available only for lib-node
binding.
Parameters
secret_encryption_salt
: string – Salt used for secret encryption. For example, a mobile device can use device ID as salt.secret
: CryptoBoxSecret – Cryptobox secretobj
: AppPasswordProvider – Interface that provides a callback that returns an encrypted password, used for cryptobox secret encryption
Result
handle
: CryptoBoxHandle
remove_crypto_box
Removes Crypto Box. Clears all secret data.
NOTE: Sync version is available only for lib-node
binding.
Parameters
handle
: CryptoBoxHandle
get_crypto_box_info
Get Crypto Box Info. Used to get encrypted_secret
that should be used for all the cryptobox initializations except the first one.
NOTE: Sync version is available only for lib-node
binding.
Parameters
handle
: CryptoBoxHandle
Result
encrypted_secret
: string – Secret (seed phrase) encrypted with salt and password.
get_crypto_box_seed_phrase
Get Crypto Box Seed Phrase.
Attention! Store this data in your application for a very short period of time and overwrite it with zeroes ASAP.
NOTE: Sync version is available only for lib-node
binding.
Parameters
handle
: CryptoBoxHandle
Result
phrase
: stringdictionary
: MnemonicDictionarywordcount
: number
get_signing_box_from_crypto_box
Get handle of Signing Box derived from Crypto Box.
NOTE: Sync version is available only for lib-node
binding.
Parameters
handle
: number – Crypto Box Handle.hdpath
?: string – HD key derivation path. By default, Everscale HD path is used.secret_lifetime
?: number – Store derived secret for this lifetime (in ms). The timer starts after each signing box operation. Secrets will be deleted immediately after each signing box operation, if this value is not set.
Result
handle
: SigningBoxHandle – Handle of the signing box.
get_encryption_box_from_crypto_box
Gets Encryption Box from Crypto Box.
Derives encryption keypair from cryptobox secret and hdpath and stores it in cache for secret_lifetime
or until explicitly cleared by clear_crypto_box_secret_cache
method. If secret_lifetime
is not specified - overwrites encryption secret with zeroes immediately after encryption operation.