Key Setup

Your server needs a 2048-bit RSA key pair. The public key goes in your flow's settings in the dashboard, and Monime uses it to encrypt the AES key in each request. The private key stays on your server, which uses it to decrypt that AES key.

Make a key pair

# Private key, in PKCS#8 format
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private_key.pem

# Public key, to paste in the dashboard
openssl pkey -in private_key.pem -pubout -out public_key.pem

The first line of private_key.pem must read -----BEGIN PRIVATE KEY-----. The code samples in these docs expect that format. If yours reads -----BEGIN RSA PRIVATE KEY-----, convert it:

openssl pkcs8 -topk8 -nocrypt -in old_private_key.pem -out private_key.pem

Make a separate key pair for each environment, such as development, staging and production. Then a leaked development key can't decrypt production traffic.

Add the public key to your flow

Paste the whole of public_key.pem into the Security section of your flow, including the -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY----- lines. Flow Security shows where to find it.

Use a key that starts with -----BEGIN PUBLIC KEY-----. A key that starts with -----BEGIN RSA PUBLIC KEY----- won't work.

Store the private key

Load the private key once when your server starts, from an environment variable or a secrets manager:

export MONIME_RSA_PRIVATE_KEY="$(cat private_key.pem)"

Don't put the key in your source code.

Key scope

One key pair covers every exchange and dynamic URL in one flow. Each flow has its own key pair.

If one server handles several flows, it needs each flow's private key. The request doesn't say which flow sent it, so give each flow its own URL path and pick the key from the path:

# https://api.kabalafarms.sl/ussd/payments/... uses this key
export MONIME_RSA_PRIVATE_KEY_PAYMENTS="$(cat payments_private_key.pem)"

# https://api.kabalafarms.sl/ussd/onboarding/... uses this key
export MONIME_RSA_PRIVATE_KEY_ONBOARDING="$(cat onboarding_private_key.pem)"

Rotate a key

After you save a new public key, live sessions can keep using the old one for up to 30 minutes. Your server must accept both keys during that time.

1. Make a new key pair.
2. Deploy the new private key next to the old one. Have your server try the new key first, and the old key if that fails.
3. Save the new public key in the dashboard.
4. Wait at least 30 minutes, then remove the old private key.

Rotate on a schedule, and straight away if a private key might have leaked.