The functions available in the Forward API domain-specific language (DSL). The DSL has been kept intentionally minimal, fill out this form if you find yourself needing a new function.
aes-gcm
bytes
["aes-gcm", keyid, nonce, data]
Encrypts data
using the key referenced by keyid
(an integer) and a nonce
created by aes-gcm-nonce
. Returns a byte array.
keyid
is a 0-indexed reference into the keys array of keys provided by the config. The key must be 16, 24, or 32 bytes in length, hex-encoded.
Examples:
["aes-gcm", 0, ["aes-gcm-nonce"], "$number"]
⇒ Some byte array (In a real example you would want to store the result of callingaes-gcm-nonce
in an intermediate variable so it can be included in the body of the destination request)
aes-gcm-nonce
bytes
["aes-gcm-nonce"]
Returns a byte array filled with 12 random bytes.
Examples:
["hex", ["aes-gcm-nonce"]]
⇒ "s8tIW/oPqPkkN1OY"
array
array
JSON arrays form the s-expressions of the Forward API DSL. array
allows you to create literal arrays.
Examples:
["array", "braintree", "payments"]
⇒ ["braintree", "payments"]["array", ["base64", "braintree"], "payments"]
⇒ ["YnJhaW50cmVl", "payments"]
base64
string
["base64", value]
base 64 encodes the result of evaluating value
.
Examples:
["base64", "braintree"]
⇒ "YnJhaW50cmVl"["base64", ["md5", "braintree"]]
⇒ "cC5vUPvGgxD8+vLvjq7GIQ=="
concat
bytes
Given some number of byte array args, returns the byte array result of concatenating each of those args.
encode
bytes
["encode", charset, input]
returns the byte array result of applying the encoding charset
to the input. The default charset is UTF-8.
Examples:
["base64", ["encode", "UTF-16", "braintree"]]
⇒ "/v8AYgByAGEAaQBuAHQAcgBlAGU="["hex", ["encode", "UTF-32", "abc"]]
⇒ "000000610000006200000063"
format_expiration
string
["format_expiration", format_string]
the format string may include any combination of the following: %Y
, %y
, %m
, %-m
, %%
.
Directives:
%Y
- Year with century%y
- Year modulo 100%m
- Month of the year, zero-padded (01..12)%-m
- Month of the year, no padding (1..12)%%
- Literal "%"
Examples:
["format_expiration", "%m/%Y"]
⇒ "10/2015" (assuming an expiration month of October in the year 2015)["format_expiration", "%m/%y"]
⇒ "07/15" (assuming an expiration month of July in the year 2015)
hex
string
["hex", value]
hexadecimal encodes the result of evaluating value
.
Examples:
["hex", "braintree"]
⇒ "627261696e74726565"["hex", ["md5", "braintree"]]
⇒ "702e6f50fbc68310fcfaf2ef8eaec621"
hmac-sha1
bytes
["hmac-sha1", keyid, data]
generates the keyed-hash message authentication code of data
using the key referenced by keyid
in the (0-indexed) array of keys provided by the config. Returns a byte array; wrap in hex
or base64
to make a string.
Examples:
["hex", ["hmac-sha1", 0, "The quick brown fox jumps over the lazy dog"]]
⇒ "de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9", with"keys": ["6b6579"]
(the hex encoding of the ASCII string "key").
hmac-sha256
bytes
["hmac-sha256", keyid, data]
generates the keyed-hash message authentication code of data
using the key referenced by keyid
in the (0-indexed) array of keys provided by the config. Returns a byte array; wrap in hex
or base64
to make a string.
Examples:
["hex", ["hmac-sha256", 0, "The quick brown fox jumps over the lazy dog"]]
⇒ "f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8", with"keys": ["6b6579"]
(the hex encoding of the ASCII string "key").
hmac-sha512
bytes
["hmac-sha512", keyid, data]
generates the keyed-hash message authentication code of data
using the key referenced by keyid
in the (0-indexed) array of keys provided by the config. Returns a byte array; wrap in hex
or base64
to make a string.
Examples:
["hex", ["hmac-sha512", 0, "The quick brown fox jumps over the lazy dog"]]
⇒ "b42af09057bac1e2d41708e48a902e09b5ff7f12ab428a4fe86653c73dd248fb82f948a549f7b791a5b41915ee4d1ec3935357e4e2317250d0372afa2ebeeb3a", with"keys": ["6b6579"]
(the hex encoding of the ASCII string "key").
integer
string
["integer", value]
attempts to cast value
to an integer. Returns transformation error if string can't be cast.
Examples:
["integer", "1"]
⇒ 1
join
string
["join", separator, value]
returns a string created by converting each element of the evaluated expression value
to a string, separated by the result of evaluating separator
.
Examples:
["join", ":", ["array", "braintree", "payments"]]
⇒ "braintree:payments"
last_n
string or array
["last_n", n, value]
returns the last n
characters of the string resulting from evaluating value
, or the last n
elements if value
is an array.
Examples:
["last_n", 4, "braintree"]
⇒ "tree"["last_n", 1, ["array", "braintree", "payments"]]
⇒ "payments"
md5
bytes
["md5", value]
MD5 the result of evaluating value
. Returns a byte array; use hex
or base64
to make a string.
Examples:
["hex", ["md5", "braintree"]]
"702e6f50fbc68310fcfaf2ef8eaec621"
percent-encode
string
["percent-encode", value]
returns the result of applying percent-encoding replacements on the specified value.
Examples:
["percent-encode", "braintree payments"]
⇒ "braintree%20payments"
replace
string
["replace", replacement_map_index, value]
returns the result of applying the string replacements specified by the (0-indexed) config's replacement_map.
Examples with replacement_maps: [{"a": "@", "e": "$!"}, {"e": "3"}]
:
* ["replace", 0, "braintree"]
⇒ "br@intr$!$!"
* ["replace", 1, "braintree"]
⇒ "braintr33"
rsa-oaep-sha1
bytes
["rsa-oaep-sha1", ["rsa-public-key", "$PEM_encoded_public_key"], "value to encrypt"]
encrypts the specified value using a given RSA public key, with OAEP padding (using a SHA1 message digest and MGF1 mask generation function). Returns a byte array; wrap in hex
or base64
to make a string.
rsa-pkcs1
bytes
["rsa-pkcs1", ["rsa-public-key", "$PEM_encoded_public_key"], "value to encrypt"]
encrypts the specified value using a given RSA public key, with PKCS1 padding. Returns a byte array; wrap in hex
or base64
to make a string.
Examples:
["base64", ["rsa-pkcs1", ["rsa-public-key", "$public_key"], "value to encrypt"]]
⇒ "dA0KkYFXykS5L2bPPecFBmXuEMxst+E6gQ6/i+w2+PYxCBserUIc21gW5eCXcca6kjhevo5371OfOivy+pIoY0HOgThB3DTQV+cEqxN9tb0U7ZJXXsMOVuIKXzkGofKeAI1CJVzwVh6lK5Cy7EDtYd8dUPLt+QuozWGtm7zaWfn6HWycRS0WG7GMbON2A+BiWv+fehv1jFB4nArHMiXbR1tdY10hLXsNrXHhwuft99LyCx0sIE7R6fdXi/WckdTeyVDeCmBiSX41CEjjgqGFj0KibjMYkzSNY+XO4k5Amvge4ha0YLv5bx38GhooshU0QqjzKRiz6dbJVP1ikzd49w==" Using the example RSA public key
rsa-pkcs15-sha256
bytes
["rsa-pkcs15-sha256", keyid, data]
encrypts the SHA256 digest using a given (PEM encoded) RSA private key in the config's keys array, with PKCS1 v1.5 padding. Returns a byte array; wrap in hex
or base64
to make a string.
Examples:
["base64", ["rsa-pkcs16-sha256", 0, "Data to digest and encrypt"]]
⇒ "zyhOjvWCcTxf1CtBVK2BdS1Djfv8FReCuRhQ7WPd3qUp2Hw89A2oj1oQr43THGcD+i0dWiVlcObEshPwKEXqns0bNRbKoBRVKNWCFUfmoJuNLuqOBDQMMeRxFwf91zbeYSAz6x3FwY7BcD713422jYRvTcawezKCB8QKGP9LUs4nJNZ9B5VGC0L9fTzsWJbv6ra7KNSQRGPYug9kK1/Y5dcTozaTiBJvYj22TBd2L4Gfr7pazQgGjiLzAA+qAg4/YPLHGv9EL39yJQZ2FM5Uuds6PhJAT3KjzKmqGkZr/QK0tIlax/3SZ3pnQ/LSHWRnczMdBC/FN0gVFl/FcxNlxw==" Using the example RSA private key
rsa-public-key
bytes
["rsa-public-key", "$PEM_encoded_public_key"]
reads the provided PEM-encoded RSA public key.
sha1
bytes
["sha1", value]
SHA1 the result of evaluating value
. Returns a byte array; use hex
or base64
to make a string.
Examples:
["hex", ["sha1", "braintree"]]
⇒ "984214838d0fc4b1eab0dbca61160867c9878041"["base64", ["sha1", "braintree"]]
⇒ "mEIUg40PxLHqsNvKYRYIZ8mHgEE="
sha256
bytes
["sha256", value]
SHA256 the result of evaluating value
. Returns a byte array; use hex
or base64
to make a string.
Examples:
["hex", ["sha256", "braintree"]]
⇒ "e2d67f41fee239d12faf598242412e25b357740b9a20a5b14c9795dcae320bf5"["base64", ["sha256", "braintree"]]
⇒ "4tZ/Qf7iOdEvr1mCQkEuJbNXdAuaIKWxTJeV3K4yC/U="
sha512
bytes
["sha512", value]
SHA512 the result of evaluating value
. Returns a byte array; use hex
or base64
to make a string.
Examples:
["hex", ["sha512", "braintree"]]
⇒ "4bdd950f340870714a8c6b58209e2a3b2b7df78c995835e34a66e7de2c213040a1ba0ad5d7e0342db8411467b3051a1470ec9ac13569cd5b8a47e7030b60d63b"["base64", ["sha512", "braintree"]]
⇒ ""S92VDzQIcHFKjGtYIJ4qOyt994yZWDXjSmbn3iwhMEChugrV1+A0LbhBFGezBRoUcOyawTVpzVuKR+cDC2DWOw=="
Example RSA keypair
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4c/yKBAkD8wbX7nNfDXL
hL9pMKwBZhEnbPprRjeAX/lelso424gFSZtq4X3LFamrDN59cN2RHqj7so/aK7rW
JJzj9y+lYxocJaNbyFXlZ9ctC0OcoqyqaTlKT0VmAa7EyQXtOsUy0r3nT1emdKTs
vpz/3sFZPyWVIQ2oG/ea+QjzQvUTt8njp3l7D1txGJ+XdtGKrxJ0EuhLJNirDjlY
et33agZOQJTnUzhYA2TJsZNo9zCj9b6DyIfNVeCN0o00r/Hm5d6zlKemKbOKWtSS
dY0wGqSZB+sew+tMZaWfSzij1FzGsfkVaG/VEeMgxZq7fYu+hCcFDDQlElwf1SwJ
qwIDAQAB
-----END PUBLIC KEY-----
-----BEGIN RSA PRIVATE KEY-----
MIIEpQIBAAKCAQEA4c/yKBAkD8wbX7nNfDXLhL9pMKwBZhEnbPprRjeAX/lelso4
24gFSZtq4X3LFamrDN59cN2RHqj7so/aK7rWJJzj9y+lYxocJaNbyFXlZ9ctC0Oc
oqyqaTlKT0VmAa7EyQXtOsUy0r3nT1emdKTsvpz/3sFZPyWVIQ2oG/ea+QjzQvUT
t8njp3l7D1txGJ+XdtGKrxJ0EuhLJNirDjlYet33agZOQJTnUzhYA2TJsZNo9zCj
9b6DyIfNVeCN0o00r/Hm5d6zlKemKbOKWtSSdY0wGqSZB+sew+tMZaWfSzij1FzG
sfkVaG/VEeMgxZq7fYu+hCcFDDQlElwf1SwJqwIDAQABAoIBAQCLAg/4SbdpYiSX
0TGF/TfECHEg3UIfKwAyPhY7q38Dled8vBA0VI+suFgbZ+zU8RWzXmOqTzs+vJf1
XEjaErIw58QOLu6JC1G4ec/Oi9IlEnlQLdcG7XQaQoJUOkyJTKUnetaHD04yHWV/
ml2GAOEcllmNL0lZbjFXn6iVTt+/3XIz+PieA600+0pkqffkbDhfkLPjM4j49vrC
fZvtHliGTPqSJrZJg1mgUJTcROC5evKXNrffA+QBzbCIPWmdc5mdtj42OH+2lzGW
jVqxSkcZS/WxQqGSj3LQQ96ixR1jCrMLyzSuVT1EuQAAwZ/DzbOnfyCgS7yGStKi
4cNB40eBAoGBAP14CAkwWslKVKGY6yK+jFCsCWPB+j8Xpn/mfBaGzY/CA04gy2UL
WlpmUXvSwVUZ5X9PwJgmzVf0OSWft0FMua8DHjs9yKhImNR4HAOfA5+7gkZKXV2l
NCx9p2uJ5QQ00YufJShrFJKWpCdrAtS+j4oO1WQpgqwpfCzYMkEk6K9zAoGBAOQR
NpF29ZsLg1/8bS46k2x8PnWvrKnccaPkgg28GVv1E07HxnT1TqIFDRpYLBQ0AeZ+
NZ+LWiF8+75dfZrvIJZENEyZX3YO8hX8HoyUfmeCvelf1c75BMiMerW31rzYHYzs
LgVeIU2BZbciK5Nqz1iwvOaQ+2A7wwe5gEfy377pAoGAQQ9sUJ9+zigsLQaJZHOw
pIxkJJ0H1OYHMNFCjK2xWfMc0hMM4jTVzlpxE+12/pcVF2arMuLS1n6zpHqomTRO
fSO5wM8NEFUCFZd26V8JmRiSSeSQrpbXG4xtSucsR7YfC02gRg2mTDIqlIudQGph
gbhpAbq99d74JrKfw6TrrQ0CgYEA2XTwKtLaa/MWWLc/Aw0m9BGjHGNcprliQXrn
5mCrbVrIBh3FxE8BospeK/hWTw0norZEOtOMJNIe1uwdj1TiJWTy2PaEZvTpLr0u
A6yyuc+XdKXEH4ygWvhXKF0ZiwYlZvDrEIMoDdaLPYp/Mhhti4s5Ej668I8K7pqZ
DgEuBcECgYEAjFP0UjJWQuBV2z9zPJTltWw6e/KMmz+AIOqz4l3iUaNmhInLk5pK
iiliknXVNHjygimJS6GkZPO7QkncKag5s/lUFGf87OzfU46AM6qBBMofH7G3STWs
9G32FtR2tTCk5vBedGi2clwHWMV1+Cu8gwrI4GJ/BLbKVp/yQUOTBp4=
-----END RSA PRIVATE KEY-----