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.