Bring Your Own Key to ServiceNow KMF — Part 1: Preparing the Instance

 

If you need to encrypt an outbound integration payload so a third party can decrypt it, you'll quickly hit a wall: KMF never releases key material. That is the entire point of the framework — but it means a key generated inside ServiceNow can never be shared with the partner who needs to read your messages.

The answer is to bring your own key. It is supported, it is undocumented in places, and it fails silently in about five different spots.

 

This is a three-part series covering the whole path:

 

• Part 1 (this post) — the mental model, the role you need, and setting up the instance to accept imported keys
• Part 2 — creating your module and getting your own key into it
• Part 3 — encrypting from script, decoding the output envelope, and a reusable Script Include

 

By the end, you will have your own AES key living inside KMF, encrypting payloads that an external system can decrypt.

 

The mental model

KMF nests four objects:

 

Object	What it is
Module	The labelled box your script names
Specification	The recipe — algorithm, mode, key size
Key	The secret. Goes in, never comes out
Module Access Policy	Which scripts may use the box

 

Your code names the module. KMF resolves that to whichever key is currently active. There is no key parameter anywhere in the API — deliberately, so key material can never leak through a code review or a logged variable.

 

Get the right role

 

You need sn_kmf.cryt*graphic_manager. admin is not enough — the ACLs exclude it by design, for separation of duties. Without the role the Key Management menus do not render at all, which looks exactly like KMF not being installed.

⚠️ Log out and back in after granting it. Record access re-checks the database, so browsing works immediately — but the import call checks the session token. You will see "Security restricted: importKeyFromKeystore() restricted to sn_kmf.crypt*graphic_manager role" while demonstrably holding the role.

 

Give the instance an unwrapping key

 

ServiceNow will not accept a bare symmetric key. It only accepts keys that arrive encrypted, which means it needs an RSA pair to decrypt them. There is a pre-built module for exactly this at Key Management > Import Settings > Key Import Settings — RSA 4096, origin Import from PKCS12. If its key version reads -1, nobody has set it up yet.

openssl genrsa -out kmf_import.pem 4096
openssl req -new -x509 -key kmf_import.pem -out kmf_import.crt \
  -days 3650 -subj "/CN=kmf-import"
openssl pkcs12 -export -inkey kmf_import.pem -in kmf_import.crt \
  -out kmf_import.p12

Vault the .pem — without it no future import works. This is one-time setup; the same pair serves every key you ever import.

⚠️ The paperclip attachment is not the import. Attaching the .p12 to the record parks the file and does nothing else. The real import is the Import Key link on the Key Creation stage, which asks for the password and the file together. This is where most people get stuck, because nothing fails — it just quietly does not happen.

⚠️ The Key alias must match the alias inside the .p12 — not a name you choose:

openssl pkcs12 -in kmf_import.p12 -nokeys -info 2>/dev/null | grep -i friendlyName

Otherwise: "Keyalias with name X is not found in the keystore".

⚠️ Keep OpenSSL's legacy PBE (the default). Do not re-export with -certpbe/-keypbe AES-256 — KMF is Java-based and reads the legacy encoding reliably.

---

Part 2 here covers creating your module and importing your own key.