Why Encrypt Messages in an Integration Flow?
Most connections in CPI already use HTTPS, which encrypts the data while it travels between two systems. That is called transport-level security. But a message does not always stay inside one connection. It can be written to a file, dropped on an SFTP server, sent by email or handled by several systems before it reaches the final receiver. In those cases you can protect the message itself. That is message-level security, and it is what the Encryptor and Decryptor steps in CPI are for.
Typical examples are payroll or bank files sent to external providers, and messages that must stay unreadable for everyone except the intended partner.
How a "Digital Envelope" Works
Encrypting a large message directly with a public key would be slow. So the PKCS #7 / CMS standard (called enveloped data) uses two kinds of keys together:
- The content is encrypted with a fast symmetric key that is created on the fly.
- That symmetric key is encrypted with the receiver's public key and stored inside the message.
- Only the owner of the matching private key can unlock the symmetric key, and then the content.
The rule to remember: public key encrypts, private key decrypts. The sender needs only the receiver's public key (a certificate). The private key never leaves the receiver.
Security Elements in the Palette
| Step | What it does | Common types |
|---|---|---|
| Encryptor | Encrypts the message so only the receiver can read it. | PKCS7/CMS Enveloped Data, OpenPGP |
| Decryptor | Decrypts a message that was encrypted for you. | PKCS7/CMS Enveloped Data, OpenPGP |
| Signer | Adds a digital signature that proves who sent the message and that it was not changed. | PKCS7/CMS Signed Data, XML Signature, OpenPGP |
| Verifier | Checks a signature. | PKCS7/CMS Signed Data, XML Signature, OpenPGP |
In this article we use PKCS7/CMS Enveloped Data, because you can create the key pair directly in the CPI keystore and you do not need any extra tools. OpenPGP is widely used with banks and payroll vendors, but it needs separately prepared PGP key rings.
What You Will Build
You build two small flows, and test them with Postman:
- Encrypt flow at
/encrypt: plain text in, encrypted and Base64-encoded text out. - Decrypt flow at
/decrypt: that Base64 text in, original plain text out.
This article continues from article 3. You need the same service instance and service key for Postman, and you should already know how to create a flow with an HTTPS sender, deploy it and call it from Postman.
In this practice setup the same tenant can encrypt and decrypt. Never use real employee, salary or customer data for learning. Use harmless sample text.
Step 1: Create a Key Pair in the Keystore
- Open Monitor → Integrations and APIs and choose the Keystore tile under Manage Security.
- Choose Create → Key Pair.
- Enter an Alias, for example
sapwithsai_demo, and a Common Name (CN), for examplesapwithsai-demo. - Choose the key type RSA and a key size of at least 2048 bits, set a validity period, and choose Create.
You now have one key pair with a public part (the certificate) and a private part. The alias is the name that the Encryptor and Decryptor steps use to find them.
In this demo one key pair plays both roles, like writing a letter to yourself. In a real scenario the receiving partner creates the key pair and sends you only the certificate. You import it into your keystore and use it to encrypt. The partner keeps the private key and uses it to decrypt.
All integration flows on the tenant use the same keystore. Give your demo key a unique alias and never delete or overwrite entries you did not create, because other flows may depend on them.
Step 2: Build the Encrypt Flow
- In your package add a new integration flow, for example
Encrypt_Message_Demo, and choose Edit. - Delete the Receiver. Draw a line from the Sender to the Start event and choose the HTTPS adapter, as in article 3.
- Set Address to
/encrypt, keep User RoleESBMessaging.sendand untick CSRF Protected for this practice flow. - In the palette choose Security Elements → Encryptor → PKCS7/CMS Enveloped Data and drop it on the line between Start and End.
- In the Encryptor properties, on the Processing tab, set:
- Content Encryption Algorithm: an AES option, for example
AES/CBC/PKCS5Padding. - Secret Key Length: the longest value offered for your algorithm, for example 256 bits. The available lengths depend on the algorithm you pick.
- Receiver Public Key Alias: choose Add and enter your alias,
sapwithsai_demo.
- Content Encryption Algorithm: an AES option, for example
- Add an Encoder → Base64 Encode step after the Encryptor.
- Save and Deploy.
Why the Base64 step? The encrypted result is binary data. Postman and other text tools cannot display binary data properly. Base64 converts the binary data into plain text that you can copy and paste safely.
Step 3: Build the Decrypt Flow
- Add another integration flow, for example
Decrypt_Message_Demo, and choose Edit. - Delete the Receiver and connect the Sender to Start with an HTTPS adapter. Set Address to
/decryptand, as before, roleESBMessaging.sendand CSRF Protected off. - Add a Decoder → Base64 Decode step first. It turns the pasted text back into binary data.
- After it add Security Elements → Decryptor → PKCS7/CMS Enveloped Data.
- In the Decryptor properties enter the Private Key Alias: the same alias,
sapwithsai_demo. - Save and Deploy.
The order matters. When you encrypt you go Encrypt → Base64 Encode. When you decrypt you must reverse it: Base64 Decode → Decrypt.
Step 4: Test Both Flows in Postman
- Open Manage Integration Content and copy the endpoints of both flows. They end with
/http/encryptand/http/decrypt. - Create a Postman request POST to the
/encryptendpoint. Use the same OAuth 2.0 Client Credentials setup as in article 3. - In the body choose raw → Text and enter harmless text, for example:
Hello SAPwithSAI - this is a secret test message - Choose Send. The response is a long Base64 text. It is unreadable on purpose. Copy the whole response without extra spaces.
- Create a second POST request to the
/decryptendpoint with the same authorization. - Paste the Base64 text into the body (raw → Text) and choose Send.
The response of the second call should be exactly your original text. You have just encrypted and decrypted a message inside CPI.
Experiments that teach you a lot
- Change one character in the Base64 text and call
/decryptagain. Decryption should fail, because the message was altered. - Encrypt the same text twice. The two Base64 results differ, because a new symmetric key is generated each time, yet both decrypt to the same text.
- Remove the Base64 Decode step from the decrypt flow, redeploy and test. See which error you get, then restore it.
Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| Error about a missing key or alias | The alias is misspelled or the key pair does not exist. | Compare the alias in the flow with the Keystore tile. Aliases must match exactly. |
| Decryption fails | The text was changed, was copied with extra spaces or line breaks, or was encrypted with a different key pair. | Copy the whole response again. Use the same alias in both flows. Do not regenerate the key pair between the two calls. |
| Response is unreadable symbols | The Base64 Encode step is missing in the encrypt flow. | Add the encoder after the Encryptor and redeploy. |
| 401 or 403 | Authentication or role problem. | See the error table in article 3. |
| Changes have no effect | The flow was saved but not deployed. | Deploy again and wait until the status is Started. |
Option labels can differ slightly between releases. If a field is named differently on your tenant, use the context-sensitive help of the step in the editor.
How This Looks in a Real Project
- Outbound: your flow builds a file or message, the Encryptor uses the partner's public certificate from your keystore, and the result is sent by SFTP or another channel.
- Inbound: a partner encrypts with your public certificate. Your flow decrypts with your private key, which stays in the keystore.
- Integrity and origin: encryption keeps a message secret. To prove who sent it and that nobody altered it, add a Signer and, on the other side, a Verifier.
- Certificate expiry: certificates expire. Note the validity dates in the Keystore and plan the renewal with your partner before they end.
- Never expose a decrypt endpoint openly. The demo endpoint exists only to teach. In production, decryption happens inside a protected flow that processes the result, not behind an open URL.
- Sensitive data and logs: do not use Debug or Trace log levels with real personal data, because they can show message content.
Interview Questions
1. What is the difference between encryption and signing?
Encryption keeps the content secret so only the intended receiver can read it. Signing proves who sent the message and that it was not changed. They solve different problems and are often used together.
2. Which key encrypts and which key decrypts?
The receiver's public key encrypts. The receiver's private key decrypts. The private key never leaves the receiver.
3. Why do we use Base64 after the Encryptor?
Encrypted output is binary. Base64 converts it into text so that it can be displayed, copied and transported safely through text-based channels. The receiver must Base64-decode it before decrypting.
4. What is the difference between PKCS7/CMS and OpenPGP in CPI?
Both encrypt messages. PKCS7/CMS uses X.509 certificates and key pairs from the tenant keystore. OpenPGP uses PGP key rings that are deployed as security material, and is common with banks and payroll providers.
5. Where are keys and certificates stored in CPI?
Key pairs and certificates are stored in the tenant keystore (Monitor, Manage Security, Keystore). Credentials and PGP key rings are deployed as security material.
Frequently Asked Questions
Can I encrypt a file instead of a text message?
Yes. The Encryptor works on the message body, so a file read by an SFTP adapter or a payload built in the flow can be encrypted in the same way.
Do I need an extra tool to create the key?
Not for PKCS7/CMS. You can create the key pair directly in the CPI keystore, as in this article. OpenPGP needs key rings prepared with a PGP tool.
What happens if the certificate expires?
Encryption or decryption with that key can fail. Replace the certificate before it expires and coordinate the change with your partner.
Conclusion
You built two small flows that encrypt and decrypt a message with PKCS7/CMS, and tested them with Postman. You learned why Base64 is needed, how the keystore alias connects the steps, and how the same pattern appears in real projects with partners. From here you can move on to signing and verifying messages, to OpenPGP, and to mappings and error handling in larger flows.
- 1. SAP BTP and CPI basics: palette, adapters and the cockpit
- 2. Why SAP CPI is used: use cases and real-world examples
- 3. Your first SAP CPI integration flow with Postman
- 4. SAP CPI encryption and decryption with Postman (you are here)
- 5. Content Modifier: headers, properties and body