Skip to main content
Version: Current

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:

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

    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:

    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:

    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.

    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:

    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.

    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.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.

    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.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);