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
​CryptoErrorCode​
​SigningBoxHandle​
​EncryptionBoxHandle​
​EncryptionBoxInfo – Encryption box information.
​EncryptionAlgorithmAESVariant​
​EncryptionAlgorithmChaCha20Variant​
​EncryptionAlgorithmNaclBoxVariant​
​EncryptionAlgorithmNaclSecretBoxVariant​
​EncryptionAlgorithm​
​CipherMode​
​AesParamsEB​
​AesInfo​
​ChaCha20ParamsEB​
​NaclBoxParamsEB​
​NaclSecretBoxParamsEB​
​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.
​CryptoBoxHandle​
​BoxEncryptionAlgorithmChaCha20Variant​
​BoxEncryptionAlgorithmNaclBoxVariant​
​BoxEncryptionAlgorithmNaclSecretBoxVariant​
​BoxEncryptionAlgorithm​
​ChaCha20ParamsCB​
​NaclBoxParamsCB​
​NaclSecretBoxParamsCB​
​MnemonicDictionary​
​ParamsOfFactorize​
​ResultOfFactorize​
​ParamsOfModularPower​
​ResultOfModularPower​
​ParamsOfTonCrc16​
​ResultOfTonCrc16​
​ParamsOfGenerateRandomBytes​
​ResultOfGenerateRandomBytes​
​ParamsOfConvertPublicKeyToTonSafeFormat​
​ResultOfConvertPublicKeyToTonSafeFormat​
​KeyPair​
​ParamsOfSign​
​ResultOfSign​
​ParamsOfVerifySignature​
​ResultOfVerifySignature​
​ParamsOfHash​
​ResultOfHash​
​ParamsOfScrypt​
​ResultOfScrypt​
​ParamsOfNaclSignKeyPairFromSecret​
​ParamsOfNaclSign​
​ResultOfNaclSign​
​ParamsOfNaclSignOpen​
​ResultOfNaclSignOpen​
​ResultOfNaclSignDetached​
​ParamsOfNaclSignDetachedVerify​
​ResultOfNaclSignDetachedVerify​
​ParamsOfNaclBoxKeyPairFromSecret​
​ParamsOfNaclBox​
​ResultOfNaclBox​
​ParamsOfNaclBoxOpen​
​ResultOfNaclBoxOpen​
​ParamsOfNaclSecretBox​
​ParamsOfNaclSecretBoxOpen​
​ParamsOfMnemonicWords​
​ResultOfMnemonicWords​
​ParamsOfMnemonicFromRandom​
​ResultOfMnemonicFromRandom​
​ParamsOfMnemonicFromEntropy​
​ResultOfMnemonicFromEntropy​
​ParamsOfMnemonicVerify​
​ResultOfMnemonicVerify​
​ParamsOfMnemonicDeriveSignKeys​
​ParamsOfHDKeyXPrvFromMnemonic​
​ResultOfHDKeyXPrvFromMnemonic​
​ParamsOfHDKeyDeriveFromXPrv​
​ResultOfHDKeyDeriveFromXPrv​
​ParamsOfHDKeyDeriveFromXPrvPath​
​ResultOfHDKeyDeriveFromXPrvPath​
​ParamsOfHDKeySecretFromXPrv​
​ResultOfHDKeySecretFromXPrv​
​ParamsOfHDKeyPublicFromXPrv​
​ResultOfHDKeyPublicFromXPrv​
​ParamsOfChaCha20​
​ResultOfChaCha20​
​ParamsOfCreateCryptoBox​
​RegisteredCryptoBox​
​ParamsOfAppPasswordProviderGetPasswordVariant​
​ParamsOfAppPasswordProvider – Interface that provides a callback that returns an encrypted password, used for cryptobox secret encryption
​ResultOfAppPasswordProviderGetPasswordVariant​
​ResultOfAppPasswordProvider​
​ResultOfGetCryptoBoxInfo​
​ResultOfGetCryptoBoxSeedPhrase​
​ParamsOfGetSigningBoxFromCryptoBox​
​RegisteredSigningBox​
​ParamsOfGetEncryptionBoxFromCryptoBox​
​RegisteredEncryptionBox​
​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​
​ParamsOfSigningBoxSign​
​ResultOfSigningBoxSign​
​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.
​ParamsOfEncryptionBoxGetInfo​
​ResultOfEncryptionBoxGetInfo​
​ParamsOfEncryptionBoxEncrypt​
​ResultOfEncryptionBoxEncrypt​
​ParamsOfEncryptionBoxDecrypt​
​ResultOfEncryptionBoxDecrypt​
​ParamsOfCreateEncryptionBox​
​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]
type ParamsOfFactorize = {
    composite: string
}
​
type ResultOfFactorize = {
    factors: string[]
}
​
function factorize(
    params: ParamsOfFactorize,
): Promise<ResultOfFactorize>;
​
function factorize_sync(
    params: ParamsOfFactorize,
): ResultOfFactorize;
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]
type ParamsOfModularPower = {
    base: string,
    exponent: string,
    modulus: string
}
​
type ResultOfModularPower = {
    modular_power: string
}
​
function modular_power(
    params: ParamsOfModularPower,
): Promise<ResultOfModularPower>;
​
function modular_power_sync(
    params: ParamsOfModularPower,
): ResultOfModularPower;
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.
type ParamsOfTonCrc16 = {
    data: string
}
​
type ResultOfTonCrc16 = {
    crc: number
}
​
function ton_crc16(
    params: ParamsOfTonCrc16,
): Promise<ResultOfTonCrc16>;
​
function ton_crc16_sync(
    params: ParamsOfTonCrc16,
): ResultOfTonCrc16;
NOTE: Sync version is available only for lib-node binding.
Parameters
data: string – Input data for CRC calculation.
Encoded with base64.
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
type ParamsOfGenerateRandomBytes = {
    length: number
}
​
type ResultOfGenerateRandomBytes = {
    bytes: string
}
​
function generate_random_bytes(
    params: ParamsOfGenerateRandomBytes,
): Promise<ResultOfGenerateRandomBytes>;
​
function generate_random_bytes_sync(
    params: ParamsOfGenerateRandomBytes,
): ResultOfGenerateRandomBytes;
NOTE: Sync version is available only for lib-node binding.
Parameters
length: number – Size of random byte array.
Result
bytes: string – Generated bytes encoded in base64.
convert_public_key_to_ton_safe_format
Converts public key to ton safe_format
type ParamsOfConvertPublicKeyToTonSafeFormat = {
    public_key: string
}
​
type ResultOfConvertPublicKeyToTonSafeFormat = {
    ton_public_key: string
}
​
function convert_public_key_to_ton_safe_format(
    params: ParamsOfConvertPublicKeyToTonSafeFormat,
): Promise<ResultOfConvertPublicKeyToTonSafeFormat>;
​
function convert_public_key_to_ton_safe_format_sync(
    params: ParamsOfConvertPublicKeyToTonSafeFormat,
): ResultOfConvertPublicKeyToTonSafeFormat;
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.
type KeyPair = {
    public: string,
    secret: string
}
​
function generate_random_sign_keys(): Promise<KeyPair>;
​
function generate_random_sign_keys_sync(): KeyPair;
NOTE: Sync version is available only for lib-node binding.
Result
public: string – Public key - 64 symbols hex string
secret: string – Private key - u64 symbols hex string
sign
Signs a data using the provided keys.
type ParamsOfSign = {
    unsigned: string,
    keys: KeyPair
}
​
type ResultOfSign = {
    signed: string,
    signature: string
}
​
function sign(
    params: ParamsOfSign,
): Promise<ResultOfSign>;
​
function sign_sync(
    params: ParamsOfSign,
): ResultOfSign;
NOTE: Sync version is available only for lib-node binding.
Parameters
unsigned: string – Data that must be signed encoded in base64.
keys: KeyPair – Sign keys.
Result
signed: string – Signed data combined with signature encoded in base64.
signature: string – Signature encoded in hex.
verify_signature
Verifies signed data using the provided public key. Raises error if verification is failed.
type ParamsOfVerifySignature = {
    signed: string,
    public: string
}
​
type ResultOfVerifySignature = {
    unsigned: string
}
​
function verify_signature(
    params: ParamsOfVerifySignature,
): Promise<ResultOfVerifySignature>;
​
function verify_signature_sync(
    params: ParamsOfVerifySignature,
): ResultOfVerifySignature;
NOTE: Sync version is available only for lib-node binding.
Parameters
signed: string – Signed data that must be verified encoded in base64.
public: string – Signer's public key - 64 symbols hex string
Result
unsigned: string – Unsigned data encoded in base64.
sha256
Calculates SHA256 hash of the specified data.
type ParamsOfHash = {
    data: string
}
​
type ResultOfHash = {
    hash: string
}
​
function sha256(
    params: ParamsOfHash,
): Promise<ResultOfHash>;
​
function sha256_sync(
    params: ParamsOfHash,
): ResultOfHash;
NOTE: Sync version is available only for lib-node binding.
Parameters
data: string – Input data for hash calculation.
Encoded with base64.
Result
hash: string – Hash of input data.
Encoded with 'hex'.
sha512
Calculates SHA512 hash of the specified data.
type ParamsOfHash = {
    data: string
}
​
type ResultOfHash = {
    hash: string
}
​
function sha512(
    params: ParamsOfHash,
): Promise<ResultOfHash>;
​
function sha512_sync(
    params: ParamsOfHash,
): ResultOfHash;
NOTE: Sync version is available only for lib-node binding.
Parameters
data: string – Input data for hash calculation.
Encoded with base64.
Result
hash: string – Hash of input data.
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 parameter N
r - The Scrypt parameter r
p - The Scrypt parameter p
Conditions
log_n must be less than 64
r must be greater than 0 and less than or equal to 4294967295
p must be greater than 0 and less than 4294967295
Recommended values sufficient for most use-cases
log_n = 15 (n = 32768)
r = 8
p = 1
type ParamsOfScrypt = {
    password: string,
    salt: string,
    log_n: number,
    r: number,
    p: number,
    dk_len: number
}
​
type ResultOfScrypt = {
    key: string
}
​
function scrypt(
    params: ParamsOfScrypt,
): Promise<ResultOfScrypt>;
​
function scrypt_sync(
    params: ParamsOfScrypt,
): ResultOfScrypt;
NOTE: Sync version is available only for lib-node binding.
Parameters
password: string – The password bytes to be hashed. Must be encoded with base64.
salt: string – Salt bytes that modify the hash to protect against Rainbow table attacks. Must be encoded with base64.
log_n: number – CPU/memory cost parameter
r: 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 with hex.
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.
type ParamsOfNaclSignKeyPairFromSecret = {
    secret: string
}
​
type KeyPair = {
    public: string,
    secret: string
}
​
function nacl_sign_keypair_from_secret_key(
    params: ParamsOfNaclSignKeyPairFromSecret,
): Promise<KeyPair>;
​
function nacl_sign_keypair_from_secret_key_sync(
    params: ParamsOfNaclSignKeyPairFromSecret,
): KeyPair;
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 string
secret: string – Private key - u64 symbols hex string
nacl_sign
Signs data using the signer's secret key.
type ParamsOfNaclSign = {
    unsigned: string,
    secret: string
}
​
type ResultOfNaclSign = {
    signed: string
}
​
function nacl_sign(
    params: ParamsOfNaclSign,
): Promise<ResultOfNaclSign>;
​
function nacl_sign_sync(
    params: ParamsOfNaclSign,
): ResultOfNaclSign;
NOTE: Sync version is available only for lib-node binding.
Parameters
unsigned: string – Data that must be signed encoded in base64.
secret: string – Signer's secret key - unprefixed 0-padded to 128 symbols hex string (concatenation of 64 symbols secret and 64 symbols public keys). See nacl_sign_keypair_from_secret_key.
Result
signed: string – Signed data, encoded in base64.
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.
type ParamsOfNaclSignOpen = {
    signed: string,
    public: string
}
​
type ResultOfNaclSignOpen = {
    unsigned: string
}
​
function nacl_sign_open(
    params: ParamsOfNaclSignOpen,
): Promise<ResultOfNaclSignOpen>;
​
function nacl_sign_open_sync(
    params: ParamsOfNaclSignOpen,
): ResultOfNaclSignOpen;
NOTE: Sync version is available only for lib-node binding.
Parameters
signed: string – Signed data that must be unsigned.
Encoded with base64.
public: string – Signer's public key - unprefixed 0-padded to 64 symbols hex string
Result
unsigned: string – Unsigned data, encoded in base64.
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.
type ParamsOfNaclSign = {
    unsigned: string,
    secret: string
}
​
type ResultOfNaclSignDetached = {
    signature: string
}
​
function nacl_sign_detached(
    params: ParamsOfNaclSign,
): Promise<ResultOfNaclSignDetached>;
​
function nacl_sign_detached_sync(
    params: ParamsOfNaclSign,
): ResultOfNaclSignDetached;
NOTE: Sync version is available only for lib-node binding.
Parameters
unsigned: string – Data that must be signed encoded in base64.
secret: string – Signer's secret key - unprefixed 0-padded to 128 symbols hex string (concatenation of 64 symbols secret and 64 symbols public keys). See nacl_sign_keypair_from_secret_key.
Result
signature: string – Signature encoded in hex.
nacl_sign_detached_verify
Verifies the signature with public key and unsigned data.
type ParamsOfNaclSignDetachedVerify = {
    unsigned: string,
    signature: string,
    public: string
}
​
type ResultOfNaclSignDetachedVerify = {
    succeeded: boolean
}
​
function nacl_sign_detached_verify(
    params: ParamsOfNaclSignDetachedVerify,
): Promise<ResultOfNaclSignDetachedVerify>;
​
function nacl_sign_detached_verify_sync(
    params: ParamsOfNaclSignDetachedVerify,
): ResultOfNaclSignDetachedVerify;
NOTE: Sync version is available only for lib-node binding.
Parameters
unsigned: string – Unsigned data that must be verified.
Encoded with base64.
signature: string – Signature that must be verified.
Encoded with hex.
public: string – Signer's public key - unprefixed 0-padded to 64 symbols hex string.
Result
succeeded: boolean – true if verification succeeded or false if it failed
nacl_box_keypair
Generates a random NaCl key pair
type KeyPair = {
    public: string,
    secret: string
}
​
function nacl_box_keypair(): Promise<KeyPair>;
​
function nacl_box_keypair_sync(): KeyPair;
NOTE: Sync version is available only for lib-node binding.
Result
public: string – Public key - 64 symbols hex string