# Crypto Actions

#### crypto.asymmetric.decrypt(keypair: string, secret: string, data: string): string

Decrypts the given data with the given keypair and secret and returns the result. If the data was unable to be decrypted (e.g. if the secret was wrong or the data was tampered with),

`null`

will be returned.Use the

`crypto.asymmetric.encrypt(keypair, data)`

function to encrypt the data.The

*first parameter*is a string and is the keypair that should be used to decrypt the data.The

*second parameter*is a string and is the secret that should be used to decrypt the keypair's private key.The

*third parameter*is a string and is the data that should be decrypted.##### Examples

Decrypt the given data and toast it.`const keypair = 'vEK1.UoNnUjLz7FdgjJ52P+f/sNw1VDsKwyX0kI+Bt7ivoF4=.djEuZmFvL0tOa1RJL3ByVm8wZ2QxYTk5clV4OXZUTk0wMnUuUHpZQUM1aVlYOUUra09vZ2hmamdyNll6T0tJS0ZjQjUuMGx2VGR5UmR2dloxUklWam5OODMrN09ibnk0c2MzbjNKYzZtSmFPYzc0ZXJXMlhHQzJsWW1vWGdFdzBRM2xkSg==';`

const encrypted = 'vA1.3CC1r0fJP2tPS09C8YrTDQCJmgFczxprNEcMOzY4JD4=.3oiC7nG6N4jblFhBd4usrdid/w4Phwg/.X/9mbZYOGBjRX7YAO4D2zYJvZ3c=';

const decrypted = crypto.asymmetric.decrypt(keypair, 'password', encrypted);

os.toast(decrypted);#### crypto.asymmetric.encrypt(keypair: string, data: string): string

Encrypts the given data using the given keypair's public key and returns the result.

Use the

`crypto.asymmetric.decrypt(keypair, secret, data)`

function to decrypt the data.This method will return a string of encrypted data that is confidential (unreadable without the keypair and secret used to encrypt it), reliable (the encrypted data cannot be changed without making it unreadable), and authentic (decryptability proves that the keypair was used to encrypt the data).

As a consequence, encrypting the same data with the same keypair will produce different results. This is to ensure that an attacker cannot correlate different pieces of data to potentially deduce the original plaintext.

Encrypts the given data using an asymmetric authenticated encryption mechanism based on x25519 (A key-exchange mechanism), XSalsa20 (An encryption cipher) and Poly1305 (A message authentication code).

You may notice that this function does not need a secret to decrypt the keypair. This is because the public key of the keypair is used to encrypt the data. Due to how asymmetric encryption works, only the encrypted private key will be able to decrypt the data.

Encrypts the given data using an authenticated encryption mechanism based on x25519, XSalsa20 (An encryption cipher) and Poly1305 (A message authentication code).

The

*first parameter*is a string and is the keypair that should be used to encrypt the data.The

*second parameter*is a string and is the string data that should be encrypted.##### Examples

Encrypt the given data and toast it.`const keypair = 'vEK1.UoNnUjLz7FdgjJ52P+f/sNw1VDsKwyX0kI+Bt7ivoF4=.djEuZmFvL0tOa1RJL3ByVm8wZ2QxYTk5clV4OXZUTk0wMnUuUHpZQUM1aVlYOUUra09vZ2hmamdyNll6T0tJS0ZjQjUuMGx2VGR5UmR2dloxUklWam5OODMrN09ibnk0c2MzbjNKYzZtSmFPYzc0ZXJXMlhHQzJsWW1vWGdFdzBRM2xkSg==';`

const encrypted = crypto.asymmetric.encrypt(keypair, "hello, world");

os.toast(encrypted);#### crypto.asymmetric.isEncrypted(cyphertext: string): boolean

Determines if the given value was encrypted using

`crypto.asymmetric.encrypt(keypair, data)`

. Returns`true`

if the data is a keypair and`false`

otherwise.The

*first parameter*is a string and is the value that should be tested to see if it is encrypted.##### Examples

Determine if a value is encrypted with asymmetric encryption.`const encrypted = crypto.asymmetric.isEncrypted("hello, world");`

os.toast('Is it encrypted? ' + encrypted);#### crypto.asymmetric.isKeypair(keypair: string): boolean

Determines if the given value is a keypair generated using

`crypto.asymmetric.keypair(secret)`

. Returns true if the data is a keypair and false otherwise.The

*first parameter*is a string and is the value that should be tested to see if it is a keypair.##### Examples

Determine if a value is a keypair.`const encrypted = crypto.asymmetric.isKeypair("hello, world");`

os.toast('Is it a keypair? ' + encrypted);#### crypto.asymmetric.keypair(secret: string): string

Creates a keypair that can be used to encrypt and decrypt data.

Use

`crypto.asymmetric.encrypt(keypair, data)`

and`crypto.asymmetric.decrypt(keypair, secret, data)`

to encrypt and decrypt the data.Always use a strong and unique secret key. Use a password manager such as LastPass or 1Password to help you create and keep track of them.

Keypairs are made up of a private key and a public key The public key is a special value that can be used to encrypt data and the private key is a related value that can be used to decrypt data that was encrypted by the private key.

The private key is called "private" because it is encrypted using the given secret while the public key is called "public" because it is not encrypted so anyone can use it if they have access to it.

Note that both the private and public keys are randomly generated, so while the public is unencrypted, it won't be able to be used by someone else unless they have access to it.

The

*first parameter*is a string and is the secret that should be used to encrypt the private key of the keypair.##### Examples

Create a keypair and toast it.`const keypair = crypto.asymmetric.keypair("my secret");`

os.toast(keypair);#### crypto.encrypt(secret: string, data: string): string

Encrypts the given data using the given secret key (also commonly known as a password) and returns the result.

Use the crypto.decrypt function to decrypt the data.

*Always use a strong and unique secret key.*Use a password manager such as LastPass or 1Password to help you create and keep track of them.The

*first parameter*is a string and is the secret that should be used to encrypt the data. Use a strong an unique secret for maximum security.The

*second parameter*is a string and is the string data that should be encrypted.##### Examples

Encrypt the given data and toast it.`const encrypted = crypto.encrypt("key", "hello, world");`

os.toast(encrypted);#### crypto.hash(algorithm: ("sha256" | "sha512" | "sha1"), format: "raw", ...data: unknown[]): Uint8Array

Calculates the hash of the given data using the specified algorithm and returns the result as a raw array of bytes. Returns a hexadecimal string, Base64 string, or Uint8Array based on the specified format.

Hashes are generally useful for validating that a piece of data did not change or for checking to see if two values are the same thing.

Supports calculating hashes of strings, numbers, booleans, objects, arrays, and bots.

The

*first parameter*is a ("sha256" | "sha512" | "sha1") and a string indicating which algorithm should be used for calculating the hash. The following algorithms are supported:`"sha256"`

(equivalent to`crypto.sha256(...data)`

)`"sha512"`

(equivalent to`crypto.sha512(...data)`

)`"sha1"`

(not recommended unless needed for compatability with external software)

The

*second parameter*is a "raw" and a string indicating which format the hash should be output as. The following formats are supported:`"raw"`

- The output should be a Uint8Array

*Each other parameter*is a unknown and are the pieces of data that should be included in the hash. If multiple pieces of data are included, they will be concatenated before hashing.##### Examples

Calculate the SHA-256 raw hash of a string`const hash = crypto.hash("sha256", "raw", "hello, world");`

console.log(hash);#### crypto.hash(algorithm: ("sha256" | "sha512" | "sha1"), format: ("hex" | "base64"), ...data: unknown[]): string

Calculates the hash of the given data using the specified algorithm and returns the result in the specified format. Returns a hexadecimal string, Base64 string, or Uint8Array based on the specified format.

Hashes are generally useful for validating that a piece of data did not change or for checking to see if two values are the same thing.

Supports calculating hashes of strings, numbers, booleans, objects, arrays, and bots.

The

*first parameter*is a ("sha256" | "sha512" | "sha1") and a string indicating which algorithm should be used for calculating the hash. The following algorithms are supported:`"sha256"`

(equivalent to`crypto.sha256(...data)`

)`"sha512"`

(equivalent to`crypto.sha512(...data)`

)`"sha1"`

(not recommended unless needed for compatability with external software)

The

*second parameter*is a ("hex" | "base64") and a string indicating which format the hash should be output as. The following formats are supported:`"hex"`

- The output should be a hexadecimal string.`"base64"`

- The output should be a Base64 string.

*Each other parameter*is a unknown and are the pieces of data that should be included in the hash. If multiple pieces of data are included, they will be concatenated before hashing.##### Examples

Calculate the SHA-256 hex hash of a string`const hash = crypto.hash("sha256", "hex", "hello, world");`

os.toast(hash);Calculate the SHA-256 base64 hash of a string`const hash = crypto.hash("sha256", "base64", "hello, world");`

os.toast(hash);Calculate the SHA-512 hex hash of a string`const hash = crypto.hash("sha512", "hex", "hello, world");`

os.toast(hash);Calculate the SHA-1 hex hash of a string`const hash = crypto.hash("sha1", "hex", "hello, world");`

os.toast(hash);#### crypto.hmac(algorithm: ("sha256" | "sha512" | "sha1"), format: "raw", key: string, ...data: unknown[]): Uint8Array

Calculates the HMAC hash of the given data using the specified algorithm and returns the result in the specified format. Returns a hexadecimal string, Base64 string, or Uint8Array based on the specified format.

HMAC hashes are generally useful for validating that a piece of data was sent from someone else who has a particular secret key.

Supports calculating hashes of strings, numbers, booleans, objects, arrays, and bots.

The

*first parameter*is a ("sha256" | "sha512" | "sha1") and a string indicating which algorithm should be used for calculating the hash. The following algorithms are supported:`"hmac-sha256"`

(equivalent to`crypto.hmacSha256(key, ...data)`

)`"hmac-sha512"`

(equivalent to`crypto.hmacSha512(key, ...data)`

)`"hmac-sha1"`

(not recommended unless needed for compatability with external software)

The

*second parameter*is a "raw" and a string indicating which format the hash should be output as. The following formats are supported:`"hex"`

- The output should be a hexadecimal string.`"base64"`

- The output should be a Base64 string.

The

*third parameter*is a string and is the secret key that should be used to create the HMAC.*Each other parameter*is a unknown and are the pieces of data that should be included in the hash. If multiple pieces of data are included, they will be concatenated before hashing.##### Examples

Calculate the raw HMAC-SHA256 of a string with a key`const hash = crypto.hmac("hmac-sha256", "raw", "key", "hello, world");`

console.log(hash);#### crypto.hmac(algorithm: ("sha256" | "sha512" | "sha1"), format: ("hex" | "base64"), key: string, ...data: unknown[]): string

Calculates the HMAC hash of the given data using the specified algorithm and returns the result in the specified format. Returns a hexadecimal string, Base64 string, or Uint8Array based on the specified format.

HMAC hashes are generally useful for validating that a piece of data was sent from someone else who has a particular secret key.

Supports calculating hashes of strings, numbers, booleans, objects, arrays, and bots.

*first parameter*is a ("sha256" | "sha512" | "sha1") and a string indicating which algorithm should be used for calculating the hash. The following algorithms are supported:`"hmac-sha256"`

(equivalent to`crypto.hmacSha256(key, ...data)`

)`"hmac-sha512"`

(equivalent to`crypto.hmacSha512(key, ...data)`

)`"hmac-sha1"`

(not recommended unless needed for compatability with external software)

The

*second parameter*is a ("hex" | "base64") and a string indicating which format the hash should be output as. The following formats are supported:`"hex"`

- The output should be a hexadecimal string.`"base64"`

- The output should be a Base64 string.

The

*third parameter*is a string and is the secret key that should be used to create the HMAC.*Each other parameter*is a unknown and are the pieces of data that should be included in the hash. If multiple pieces of data are included, they will be concatenated before hashing.##### Examples

Calculate the hexadecimal HMAC-SHA256 of a string with a key`const hash = crypto.hmac("hmac-sha256", "hex", "key", "hello, world");`

os.toast(hash);Calculate the Base64 HMAC-SHA256 of a string with a key`const hash = crypto.hmac("hmac-sha256", "base64", "key", "hello, world");`

os.toast(hash);Calculate the hexadecimal HMAC-SHA512 of a string with a key`const hash = crypto.hmac("hmac-sha512", "hex", "key", "hello, world");`

os.toast(hash);Calculate the hexadecimal HMAC-SHA1 of a string with a key`const hash = crypto.hmac("hmac-sha1", "hex", "key", "hello, world");`

os.toast(hash);#### crypto.hmacSha256(key: string, ...data: unknown[]): string

Calculates the HMAC SHA-256 hash of the given data. Returns a hexadecimal string that represents the computed hash.

HMAC hashes are generally useful for validating that a piece of data was sent from someone else who has a particular secret key.

Supports calculating hashes of strings, numbers, booleans, objects, arrays, and bots.

The

*first parameter*is a string and is the secret key that should be used to create the HMAC.*Each other parameter*is a unknown and are the data that should be included in the hash. If multiple pieces of data are included, they will be concatenated before hashing.##### Examples

Calculate the HMAC of a string with a key.`const hash = crypto.hmacSha256("key", "hello, world");`

os.toast(hash);Calculate the HMAC of an object.`const hash = crypto.hmacSha256("key", {`

abc: "def"

});

os.toast(hash);#### crypto.hmacSha512(key: string, ...data: unknown[]): string

Calculates the HMAC SHA-215 hash of the given data. Returns a hexadecimal string that represents the computed hash.

Supports calculating hashes of strings, numbers, booleans, objects, arrays, and bots.

The

*first parameter*is a string and is the secret key that should be used to create the HMAC.*Each other parameter*is a unknown and are the data that should be included in the hash. If multiple pieces of data are included, they will be concatenated before hashing.##### Examples

Calculate the HMAC of a string with a key.`const hash = crypto.hmacSha512("key", "hello, world");`

os.toast(hash);Calculate the HMAC of an object.`const hash = crypto.hmacSha512("key", {`

abc: "def"

});

os.toast(hash);#### crypto.isEncrypted(cyphertext: string): boolean

Determines if the given value has been encrypted using

`crypto.encrypt(secret, data)`

. Returns true if the data is encrypted and false otherwise.The

*first parameter*is a string and is the value that should be tested to see if it has been encrypted.##### Examples

Determine if a value is encrypted.`const encrypted = crypto.isEncrypted("hello, world");`

os.toast('Is it encrypted? ' + encrypted);#### crypto.keypair(secret: string): string

Creates a keypair that can be used to digitially sign and verify data.

Digital signatures are generally useful for verifying that a piece of data was sent from someone who had access to the keypair.

Use

`crypto.sign(keypair, secret, data)`

and crypto.verify to sign and verify the data.Keypairs are made up of a private key and a public key. The private key is a special value that can be used to create digital signatures and the public key is a related value that can be used to verify that a digitital signature was created by the private key.

The private key is called "private" because it is encrypted using the given secret while the public key is called "public" because it is not encrypted so anyone can use it if they have access to it.

Note that both the private and public keys are randomly generated, so while the public is unencrypted, it won't be able to be used by someone else unless they have access to it.

The

*first parameter*is a string and is the secret that should be used to encrypt the private key of the keypair.##### Examples

Create a keypair and toast it.`const keypair = crypto.keypair("my secret");`

os.toast(keypair);#### crypto.sha256(...data: unknown[]): string

Calculates the SHA-256 hash of the given data. Returns a hexadecimal string that represents the computed hash.

Hashes are generally useful for validating that a piece of data did not change or for checking to see if two values are the same thing.

Supports calculating hashes of strings, numbers, booleans, objects, arrays, and bots.

*Each parameter*is a unknown and are a piece of data that should be included in the hash. If multiple pieces of data are included, they will be concatenated before hashing.##### Examples

Calculate the hash of a string.`const hash = crypto.sha256("hello, world");`

os.toast(hash);Calculate the hash of an object.`const hash = crypto.sha256({`

abc: "def"

});

os.toast(hash);#### crypto.sha512(...data: unknown[]): string

Calculates the SHA-512 hash of the given data. Returns a hexadecimal string that represents the computed hash.

Supports calculating hashes of strings, numbers, booleans, objects, arrays, and bots.

*Each parameter*is a unknown and are a piece of data that should be included in the hash. If multiple pieces of data are included, they will be concatenated before hashing.##### Examples

Calculate the hash of a string.`const hash = crypto.sha512("hello, world");`

os.toast(hash);Calculate the hash of an object.`const hash = crypto.sha512({`

abc: "def"

});

os.toast(hash);#### crypto.sign(keypair: string, secret: string, data: string): string

Calculates the digital signature for the given data using the given keypair and secret (also commonly known as a password).

Use

`crypto.keypair(secret)`

to create a keypair that can be used to create signatures.Use crypto.verify to validate signatures.

Digital signatures are used to verify the authenticity and integrity of data.

This works by leveraging asymmetric encryption but in reverse.

If we can encrypt some data such that only the public key of a keypair can decrypt it, then we can prove that the data was encrypted (i.e. signed) by the corresponding private key.

And since the public key is available to everyone but the private key is only usable when you have the secret, we can use this to prove that a particular piece of data was signed by whoever knows the secret.

Note that because of how digital signatures work, signing the same data with the same keypair will produce the same signature.

The

*first parameter*is a string and is the keypair that should be used to sign the data.The

*second parameter*is a string and is the secret that was used to encrypt the private key of the keypair.The

*third parameter*is a string and is the string data that should be signed.##### Examples

Create a signature for the string "hello".`// Returned from crypto.keypair()`

const keypair = "vK1.ugqz8HzhaQhfORc8Coc6WVHTciMrcmfSUuw99KLRJYk=.djEuak1QNkF5MHFzMTBFMXRHamR1ZFhqTmRTV3AycjVyZUsudzFjSWZWVUFQVUdqK3hTM000NUduYUlNQ094SUhCTUEuanYrZEQwNVJFVGo3UzRPSklQQUkxc3U0anZjUmxrTEM2OW1BajkyMkxxdTFZd2sxNzV5QW9Dc3gwU3RENlQ0cmtNTVk4b2Zna2JRVTIrQmp5OUIrTTJsaFI2ajcyb0lJdmdSWkRXRU9lZE09";

const signature = crypto.sign(keypair, "my secret", "hello");

os.toast(signature);