Encryption

You can encrypt request or response content with selected algorithms through defined variables

This document explains the detailed usage of a specific policy. If you are using Apinizer policy structure for the first time or want to learn the general working principles of policies, we recommend reading the What is Policy? page first.

Overview

What is its Purpose?

• Encryption policy increases data transmission and storage security by encrypting sensitive data in API Proxy (API Proxy Server) flow with standard algorithms.
• Writes data from source variables to target variables in encrypted form and prevents access to unmasked data.
• Provides consistent security configuration by centralizing secret key and certificate management.
• Encryption is applied only when specified endpoint or header criteria are met through condition-based activation.

Working Principle

1. Request Arrival: For each HTTP/HTTPS request arriving at the API Gateway, the source IP address of the request is identified.
2. Policy Check: If the Encryption policy is active, the system checks in the following order:
   • Is a Condition defined? If so, is the condition met?
   • Is the policy active (active=true)?
   • Is a Variable used or is Apinizer default?
3. Execution of Encryption Definitions: For each policyEncryptionDef entry, source variable is read, encryption is applied with selected algorithm and key/certificate, result is stored in target variable, and IV and algorithm information are written to relevant variables if necessary.
4. Decision Making:
   • Match Found: All definitions are processed successfully, flow is routed to next policy or endpoint.
   • No Match: Policy is skipped when condition is not met, no changes are made to data.
5. Error Handling: Customizable HTTP status code and error message are returned for requests that do not comply with the policy rule.

Features and Capabilities

Basic Features

• Multiple Encryption Step Management: Separate algorithm and target variables are defined for different data fields by creating multiple encryption definitions in a single policy.
• Algorithm Flexibility: Different mode and padding options such as AES, DES, Triple DES, and RSA are supported; dynamic selection can be made at runtime with algorithm variable.
• Key/Certificate Integration: Secret keys are selected from Crypto Key Info entities and certificates from Certificate management, integrating with centralized secret management system.
• Active/Passive Status Control: Easily change the active or passive status of the policy (active/passive toggle). In passive state, the policy is not applied but its configuration is preserved.
• Condition-Based Application: Determine when the policy will be applied by creating complex conditions with Query Builder (e.g., only for specific endpoints or header values).

Advanced Features

• IV Management: IV generation or retrieval from external variable is provided for algorithms requiring IV, IV format is determined as BASE64 or HEX.
• Variable Update Dialogs: Selection of correct variables is facilitated with separate dynamic selection windows for source, target, algorithm, and IV variables.
• Localization and Global Mode: Global policies can be converted to local copies; local policies can be added to global repository for centralized management.
• Export/Import Feature: Export policy configuration as a ZIP file. Import to different environments (Development, Test, Production). Version control and backup capability.
• Policy Group and Proxy Group Support: Manage multiple policies within Policy Group. Bulk policy assignment to Proxy Groups. Centralized update and deployment operations.
• Deploy and Versioning: Deploy policy changes to live environment. See which API Proxies use it (Policy Usage). Proxy Group and Policy Group usage reports.

Usage Scenarios

Scenario	Situation	Solution (Policy Application)	Expected Behavior / Result
Customer Data Encryption	Customer ID number field comes as plain text	sourceVar=request.body.customerId, targetVar=request.body.customerIdEnc, AES_CBC_PKCS5Padding, BASE64 output.	Plain text is hidden, encrypted value is routed to API.
Token Storage with RSA	Private key should be used in JWT generation	RSA_ECB_PKCS1Padding, enumKeyCertificateType=KEY, cryptoKeyInfoId selected.	Key management is secure, correct algorithm is used when creating token.
Certificate-Based Encryption	Partner system requires certificate	RSA_ECB_OAEPWithSHA_256AndMGF1Padding, enumKeyCertificateType=CERTIFICATE, certificate selection.	Request is encrypted with partner certificate, other party can decrypt.
Dynamic Algorithm Selection	Algorithm type changes according to header	cipherAlgorithmVar selected, algorithm name is read from header.	Algorithm is changed at runtime, flexible policy is applied.
Flow Requiring IV Generation	IV is expected in NoPadding mode	createIV=true, ivVar=response.headers.iv, HEX format.	Policy generates IV and writes to output variable, target system can read.
Local Policy Test	Testing needs to be done on a single API	Copy global policy with Localize, edit in local mode.	Encryption scenario is tested in test environment without affecting live.
(Optional) SOAP Envelopes	SOAP envelope content should be encrypted	sourceVar=request.body.soapPayload, Triple DES algorithm, BASE64.	SOAP body is encrypted, remains secret until target service decrypts.

Configuring Policy Parameters

At this step, users can create a new policy or configure existing policy parameters to define access rules. The defined parameters directly affect how the policy works (e.g., which IPs will be allowed, geographical restrictions, conditional activations, etc.). This way, the policy can be customized according to organization-specific requirements and managed centrally.

Creating a New Encryption Policy

Configuration Steps

Step	Description / Operation
Step 1: Going to Creation Page	- Go to Development → Global Settings → Global Policies → Encryption Policy section from the left menu. - Click the [+ Create] button at the top right.
Step 2: Entering Basic Information	Policy Status: Shows Active/Passive status. New policies are active by default. Name (Required): Example: Production_Encryption - Enter a unique name, it cannot start with a space. - System automatically checks. Green checkmark: available. Red cross: existing name. Description: Example: “Encrypts customer sensitive data with AES” - Max. 1000 characters. - Explain the purpose of the policy.
Step 3: Variable Usage	- In the action button area at the top of the page, you can use the [<> Variable] button to select dynamic values. - Using context/global variable expressions, you can manage policy parameters with variable-based values instead of fixed values. - This reduces manual update effort when values change and provides operational convenience. - For detailed information, review Dynamic Variables.
Step 4: Creating Encryption Definitions	- Add policyEncryptionDef with Add button. - Select source (sourceVar) and target (targetVar) variables. - Determine algorithm (cipherAlgorithm) and output format (outputEncodingType). - Define algorithm variable if needed (cipherAlgorithmVar).
Step 5: Key/Certificate and IV Configuration (If Any)	- For RSA algorithms, select KEY or CERTIFICATE, determine relevant cryptoKeyInfoId or certificateId value. - If IV is required in CBC mode, fill in createIV, ivEncodingType, and ivVar fields.
Step 6: Encryption Definition Management (If Any)	- Provide maintenance ease by entering description for each definition. - Use pencil icon in row to edit definition, trash icon to remove. - Order determines execution order of encryption operations.
Step 7: Defining Condition (Optional)	- Go to the Condition tab. - Conditions determine when the policy will be active. Examples: - Environment-based: Header = X-Environment, Operator = Equals, Value = production - API Key-based: Header = X-API-Key, Starts With = PROD - Endpoint-based: Path = /api/admin/* If no condition is defined, the policy is always active
Step 8: Customizing Error Message (Optional)	- Go to the Error Message Customization tab. - Customize the message to be returned when access is denied. Default: { "statusCode": 403, "message": "[Default error message]" } Custom: { "statusCode": 403, "errorCode": "[CUSTOM_ERROR_CODE]", "message": "[Custom message]" }
Step 9: Saving	- Click the [Save] button at the top right. Checklist: Unique name. Required fields filled. At least one encryption definition exists Result: - Policy is added to the list. - Can be linked to APIs. - If it’s a global policy, it is automatically applied.

For the description of Conditions and Error Message Customization panels, you can review the Conditions and Error Message Customization sections on the What is Policy? page.

For a complete guide on all layers, priority order and scenario examples of the error message configuration system, see the Error Message Configuration Guide page.

Deleting the Policy

For the deletion steps of this policy and the operations to be applied when it is in use, you can refer to the Removing Policy from Flow section on the Policy Management page.

Exporting/Importing the Policy

For the export and import steps of this policy, you can refer to the Export/Import page.

Linking the Policy to API

For the process of how this policy will be linked to APIs, you can refer to the Linking Policy to API section on the Policy Management page.

Advanced Features

Feature	Description and Steps
Runtime Algorithm Selection	- Select variable for cipherAlgorithmVar. - Provide algorithm name from header/body during request. - Ensure it is one of the supported fixed values, otherwise default algorithm is not applied.
IV Injection Management	- Enable createIV field or select existing ivVar variable. - Determine IV encoding as BASE64 or HEX. - Ensure it is compatible with target system’s IV format.
Certificate Cycle Control	- Select enumKeyCertificateType=CERTIFICATE in RSA mode. - Select valid (not revoked) certificate from list. - Update policy and redeploy when certificate is renewed.

Best Practices

Things to Do and Best Practices

Category	Description / Recommendations
Variable Management	Bad: Using same variable as both source and target. Good: Keeping source and target in separate variables. Best: Using target variable only for encrypted value, clearing plain data after policy.
Algorithm Selection	Bad: Sending unsupported algorithm names at runtime. Good: Selecting fixed algorithm and testing. Best: Keeping supported algorithms in central template, avoiding unnecessary variations.
Key/Certificate Cycle	Bad: Keeping expired certificate in policy. Good: Updating policy when certificate is renewed. Best: Creating certificate renewal plan, performing quick deploy after update.
Error Message Management	Bad: Leaving default message and giving technical details to users. Good: Defining general error message. Best: Returning customized JSON message containing error code and tracking ID.
Test Process	Bad: Testing directly in live. Good: Executing manual scenario in test environment. Best: Verifying encryption/decryption compatibility with automated tests and getting approval before Production Environment.

Security Best Practices

Security Area	Description / Warnings
Key Storage	Manage secret keys only through Crypto Key Info, do not write to configuration in plain text.
Certificate Validity	Revoked certificates are marked in list, do not use in production and upload current certificate.
IV Usage	Do not encrypt without IV in NoPadding modes, make IV generation mandatory.
Algorithm Strength	Use weak algorithms (DES) only for backward compatibility, prefer AES or RSA OAEP if possible.
Condition Control	Narrow policy conditions to run only on necessary endpoints, unnecessary encryption creates CPU load.

Things to Avoid

Category	Description / Warnings
Wrong Variable Assignment	Why avoid: You may lose source data and write encrypted value to same field. Alternative: Use separate target variable and do not log original when needed.
Revoked Certificate Usage	Why avoid: Encryption fails or partner system rejects. Alternative: Select current certificate, clear revoked ones.
Untested Algorithm Changes	Why avoid: Decryption errors occur in production. Alternative: Perform bidirectional test in development environment.
CBC Usage Without IV	Why avoid: Encryption becomes deterministic, security weakens. Alternative: Manage IV with createIV or ivVar.

Performance Tips

Criterion	Recommendation / Impact
Number of Definitions	Recommendation: Avoid creating unnecessarily many encryption definitions in the same policy. Impact: Lower CPU usage and faster gateway response.
Algorithm Selection	Recommendation: Optimize payload size when using AES_CBC as AES_GCM modes are not supported. Impact: Encryption time shortens.
Key Management	Recommendation: Cache Crypto Key Info objects, avoid recreating on every request. Impact: Secret management I/O load decreases.
Condition Filters	Recommendation: Define narrow conditions with Query Builder. Impact: Unnecessary triggering of policy is prevented.
IV Calculation	Recommendation: If createIV=true, ensure IV is not reused in target variable. Impact: Memory and processing cost is kept minimum.

Frequently Asked Questions (FAQ)

Category	Question	Answer
General	On which data types does Encryption policy work?	Works on variables selected from structured payloads such as JSON, XML, or form-data; any content compatible with variable definition can be encrypted.
General	Are my definitions deleted when I make the policy passive?	No, configuration is preserved in passive state and applied the same way when reactivated.
Technical	Should I choose key or certificate for RSA algorithm?	Select certificate if service provider expects encryption with public key; use Crypto Key Info if you have your own private key.
Technical	Is IV variable mandatory?	IV variable is mandatory in CBC and createIV=true cases; otherwise policy validation fails.
Usage	Can I use the same policy on multiple API Proxies?	Yes in global mode, same configuration works on all linked API Proxy instances after deploy.
Usage	Does converting policy to local affect global version?	No, Localize operation creates a copy of global policy, original policy remains unchanged.