Crypto

Creates a Hash object that can be used for the calculation of cryptographic hashes.

The objects allocates persistent memory in the JavaScript Runtime until the final function is called.

Parameters

Return value

var digest = Crypto.hash("SHA256").update("data1").update("data2").final();

Creates a Hmac object that can be used for the calculation of a hash-based message authentication code.

The objects allocates persistent memory in the JavaScript Runtime until the final function is called.

Parameters

Return value

var mac = Crypto.hmac("SHA256","password").update("data1").update("data2").final();

Creates a Cipher object that can be used for the encryption / decryption.

The objects allocates persistent memory in the JavaScript Runtime until close or crypt with last=true is called.

Note: Cryptography is non-trivial. It's easy to make small mistakes on application level that break security completely. Don't just use the library functions but make sure you have a good understanding how to use the specific algorithm and mode.

Parameters

Return value

var ciphertext = Crypto.cipher("RC4", null, "password").crypt("secretdata");
var decrypted = Crypto.cipher("RC4", null, "password").crypt(ciphertext);

Creates an Ecdh object that can be used for Diffie-Hellman key agreement using elliptic curves.

The supported curve is Secp256r1 also known as P-256.

The objects allocates persistent memory in the JavaScript Runtime until close or secret is called.

Return value

var ecdh = Crypto.ecdh();
var localPublicKey = ecdh.public();
var remotePublicKey = "aec36e41791fabfc2ddd3223a8ef59a658a9e30cd92a5d241bbf4c18684a4a61c9aa0d1d9d3181d3022d2f64c7663000915622d4e670cce86737bb00cab5de91";
var sharedSecret = ecdh.secret(remotePublicKey);

Creates an ECDSA object that can be used for the Elliptic Curve Digital Signature Algorithm.

The objects allocates persistent memory in the JavaScript Runtime until close is called.

Parameters

Remarks

If both privateKey and publicKey are omitted (or null), a new key pair will be generated. You can then retrieve them using the private() and public() methods.

Return value

// Generate a new key pair
var ecdsa = Crypto.ecdsa("ES256", null, null); 
var newPrivateKey = ecdsa.private(true);
var newPublicKey = ecdsa.public(true);
ecdsa.close();

// Create an object for verification only
var ecdsaVerify = Crypto.ecdsa("ES256", null, newPublicKey);

// Create an object for signing only
var ecdsaSign = Crypto.ecdsa("ES256", newPrivateKey, null);

Parameters

Return value

Parameters

Return value

Remarks

Calling this function will delete the object and free all associated memory in the JavaScript Runtime.

var digestHexString = Crypto.hash("SHA256").update("data1").update("data2").final();
var digestBinary = Crypto.hash("SHA256").update("data1").update("data2").final(true);

Parameters

Return value

Parameters

Return value

Remarks

Calling this function will delete the object and free all associated memory in the JavaScript Runtime.

var hacHexString = Crypto.hmac("SHA256","password").update("data1").update("data2").final();
var hmacBinary = Crypto.hmac("SHA256","password").update("data1").update("data2").final(true);

Sets an explicit initialization vector. If the function is never called, an IV consisting of null bytes is used.
The following modes of operation use an initialization vector: "CTR", "CFB", "CBC", "CTS", "GCM".
"AES" uses an initialization vector of 16 bytes, except in "GCM" mode, where it is 12 bytes
"DES" uses an initialization vecrot of 8 bytes

Parameters

Return value

Returns the current IV.

Parameters

Return value

Parameters

Return value

Remarks

In "GCM" mode the tag is verified on decryption. If it does not match, crypt returns null and the decrypted data is discarded - it is never handed out. Always check for null. Data that fails authentication has been modified and must not be used.

var key = "73757065727375706572736563726574";
var iv = "00000000000000000000000000000000";
var plaintext = "This is the secret text to be encrypted";

// encryption using AES-128 in CTR mode
var ciphertext = Crypto.cipher("AES", "CTR", key, true).iv(iv).crypt(plaintext);

// decryption using AES-128 in CTR mode
var decrypted = Crypto.cipher("AES", "CTR", key, false).iv(iv).crypt(ciphertext);

// now decrypted contains the plain text again

var key = "000102030405060708090a0b0c0d0e0f";
var iv = "0123456789ab0123456789ab";
var plaintext = "This is the secret plaintext";
var header = "message-header";

// encryption using AES-128 in GCM mode
var r = Crypto.cipher("AES", "GCM", key, true)
    .iv(iv)
    .crypt({ data: plaintext, additionalData: header });

// now r contains the encrypted data, the additional data and the authentication tag
// {
//     data:           "5da70146824c2370d9ba86dba5533d1f1d11e1906c37d0fddf54a2f6",
//     additionalData: "message-header",
//     tag:            "8ee868b4b1e8d5011dc3cface146c87d"
// }

// decryption using AES-128 in GCM mode
var d = Crypto.cipher("AES", "GCM", key, false)
    .iv(iv)
    .crypt({ data: r.data, additionalData: header, tag: r.tag });

// now d contains the plain text again, along with the verified additional data and tag
// {
//     data:           "This is the secret plaintext",
//     additionalData: "message-header",
//     tag:            "8ee868b4b1e8d5011dc3cface146c87d"
// }

// d is null if the ciphertext, the additional data or the tag was modified
log(d && d.data == plaintext ? "OK" : "NOK"); // OK

Returns the local 64 byte public key for the ECDHE key agreement. The public key is sent to the remote party.

Parameters

Return value

Calculates a 32 byte shared secret using the remote public key.

Parameters

Return value

// This example illustrates how two parties (A and B) can calculate a shared secret.
var a = Crypto.ecdh();
var b = Crypto.ecdh();

// A and B calculate their public key and send it to each other
var publicA = a.public();
var publicB = b.public();

// A and B calculate the same shared secret using the public key of the remote party
var secretA = a.secret(publicB);
var secretB = b.secret(publicA);

log(secretA == secretB); // true

Returns the public key from the ECDSA object. This is useful when a key pair has been generated automatically.

Parameters

Return value

Returns the private key from the ECDSA object. This is useful when a key pair has been generated automatically.

Parameters

Return value

// Generate a new key pair and retrieve the keys
var ecdsa = Crypto.ecdsa("ES256", null, null);
var privateKey = ecdsa.private(true); // get as Uint8Array
var publicKey = ecdsa.public(); // get as hex string
ecdsa.close();

Signs a chunk of data using the private key.

Parameters

Return value

// Example of creating a JWT signature
var header = "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9";
var payload = "eyJpc3MiOiJqd3QtdG9vbCIsInN1YiI6InVzZXIxMjMiLCJpYXQiOjE3NTEzNjY0MjksImV4cCI6MTc1MTM3MDAyOSwiZGF0YSI6IkhlbGxvLCBKV1QhIn0";
var textToSign = Encoding.stringToBin(header + "." + payload);
var privateKey = Encoding.hexToBin("fc7682132...4ce"); // Your private key

var ecdsa = Crypto.ecdsa("ES256", privateKey, null);
var signature = ecdsa.sign(textToSign, true); // Get signature as Uint8Array
var jwt_signature = Encoding.binToBase64Url(signature);
ecdsa.close();

var jwt = header + "." + payload + "." + jwt_signature;

Verifies a signature against a chunk of data using the public key.

Parameters

Return value

// Example of verifying a JWT
var jwt = "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJqd3QtdG9vbCIsInN1YiI6InVzZXIxMjMiLCJpYXQiOjE3NTExMjQ2NDUsImV4cCI6MTc1MTEyODI0NSwiZGF0YSI6IkhlbGxvLCBKV1QhIn0.JczPUqYLV0Cr3LzI5hnVrUjVgjO_-XeMrIlSxuXQGRn9t7s6FBXtNkO-8dl1YvSJGg4xC7gH_7smoan0bKPKAA";
var parts = jwt.split('.');
var text = Encoding.stringToBin(parts[0] + "." + parts[1]);
var signature = Encoding.base64UrlToBin(parts[2]);
var publicKey = Encoding.hexToBin("04d1dc4c38ad561530d4c53793ed6efba223cb1fe0c171104c2b03621cdd954c66bc2cfabcba8b4fb126c45973c47ef783fb5f3a39ac3a145e105911d062ca6197");

var ecdsa = Crypto.ecdsa("ES256", null, publicKey);
var valid = ecdsa.verify(signature, text); // returns true if valid
ecdsa.close();

log("JWT Signature is valid: " + valid);

• Serialize an object to a JSON string.
• Create a message authentication code for the string using HMAC-SHA256 and a secret passphrase.
• Encrypt the string using AES-256 in CTR mode with the secret passphrase.
• Construct an object that includes all information needed to decrypt again - except for the secret passphrase of course.

• Read all information from the object.
• Decrypt using AES-256 in CTR mode with the secret passphrase.
• Verify the decrypted data using HMAC-SHA256 and the secret passphrase.
• Restore the original object.