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
- Request Arrival: For each HTTP/HTTPS request arriving at the API Gateway, the source IP address of the request is identified.
- 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?
- Execution of Encryption Definitions: For each
policyEncryptionDefentry, 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. - 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.
- 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 Infoentities and certificates fromCertificatemanagement, 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: 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 4: 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 5: 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 6: 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 7: 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 8: 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. |
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. |