From 7660d0298433e59b71e9bc85f39624aa23d0899c Mon Sep 17 00:00:00 2001 From: mahmishr Date: Fri, 17 Oct 2025 15:13:11 +0530 Subject: [PATCH] Update MLE.md --- MLE.md | 436 +++++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 390 insertions(+), 46 deletions(-) diff --git a/MLE.md b/MLE.md index bfbbba1d..71b18583 100644 --- a/MLE.md +++ b/MLE.md @@ -4,83 +4,349 @@ This feature provides an implementation of Message Level Encryption (MLE) for APIs provided by CyberSource, integrated within our SDK. This feature ensures secure communication by encrypting messages at the application level before they are sent over the network. +MLE supports both **Request Encryption** (encrypting outgoing request payloads) and **Response Decryption** (decrypting incoming response payloads). + +## Authentication Requirements + +- **Request MLE**: Only supported with `JWT (JSON Web Token)` authentication type +- **Response MLE**: Only supported with `JWT (JSON Web Token)` authentication type + ## Configuration -### Global MLE Configuration +## 1. Request MLE Configuration + +#### 1.1 Global Request MLE Configuration + +Configure global settings for request MLE using these properties in your `merchantConfig`: + +##### (i) Primary Configuration + +- **Variable**: `enableRequestMLEForOptionalApisGlobally` +- **Type**: `Boolean` +- **Default**: `false` +- **Description**: Enables request MLE globally for all APIs that have optional MLE support when set to `true`. + +--- + +##### (ii) Deprecated Configuration (Backward Compatibility) + +- **Variable**: `useMLEGlobally` ⚠️ **DEPRECATED** +- **Type**: `Boolean` +- **Default**: `false` +- **Description**: **DEPRECATED** - Use `enableRequestMLEForOptionalApisGlobally` instead. This field is maintained for backward compatibility and will be used as an alias for `enableRequestMLEForOptionalApisGlobally`. + +--- + +##### (iii) Advanced Configuration + +- **Variable**: `disableRequestMLEForMandatoryApisGlobally` +- **Type**: `Boolean` +- **Default**: `false` +- **Description**: Disables request MLE for APIs that have mandatory MLE requirement when set to `true`. + +--- + +#### 1.2 Request MLE Certificate Configuration [Optional Params] + +##### (i) Certificate File Path (Optional) + +- **Variable**: `mleForRequestPublicCertPath` +- **Type**: `String` +- **Optional**: `true` +- **Description**: Path to the public certificate file used for request encryption. Supported formats: `.pem`, `.crt`. + - **Note**: This parameter is optional when using JWT authentication. If not provided, the request MLE certificate will be automatically fetched from the JWT authentication P12 file using the `requestMleKeyAlias`. + +--- + +##### (ii) Key Alias Configuration (Optional) + +- **Variable**: `requestMleKeyAlias` +- **Type**: `String` +- **Optional**: `true` +- **Default**: `CyberSource_SJC_US` +- **Description**: Key alias used to retrieve the MLE certificate from the certificate file. When `mleForRequestPublicCertPath` is not provided, this alias is used to fetch the certificate from the JWT authentication P12 file. If not specified, the SDK will automatically use the default value `CyberSource_SJC_US`. + +--- + +##### (iii) Deprecated Key Alias (Backward Compatibility) (Optional) + +- **Variable**: `mleKeyAlias` ⚠️ **DEPRECATED** +- **Type**: `String` +- **Optional**: `true` +- **Default**: `CyberSource_SJC_US` +- **Description**: **DEPRECATED** - Use `requestMleKeyAlias` instead. This field is maintained for backward compatibility and will be used as an alias for `requestMleKeyAlias`. + +## 2. Response MLE Configuration -In the `merchantConfig` object, set the `useMLEGlobally` variable to enable or disable MLE for all supported APIs for the Rest SDK. +### Global Response MLE Configuration -- **Variable**: `useMLEGlobally` +- **Variable**: `enableResponseMleGlobally` - **Type**: `boolean` - **Default**: `false` -- **Description**: Enables MLE globally for all APIs when set to `true`. If set to `true`, it will enable MLE for all API calls that support MLE by CyberSource, unless overridden by `mapToControlMLEonAPI`. +- **Description**: Enables response MLE globally for all APIs that support MLE responses when set to `true`. -### API-level MLE Control +### Response MLE Private Key Configuration -Optionally, you can control the MLE feature at the API level using the `mapToControlMLEonAPI` variable in the `merchantConfig` object. +You have two options for providing the private key for response decryption: -- **Variable**: `mapToControlMLEonAPI` -- **Type**: `map = [string, boolean]` -- **Description**: Overrides the global MLE setting for specific APIs. The key is the function name of the API in the SDK, and the value is a boolean indicating whether MLE should be enabled (`true`) or disabled (`false`) for that specific API call. +#### Option 1: Provide Private Key File Path + +- **Variable**: `responseMlePrivateKeyFilePath` +- **Type**: `string` +- **Description**: Path to the private key file. Supported formats: `.p12`, `.pfx`, `.pem`, `.key`, `.p8`. Recommendation: use encrypted private key (password protection) for MLE response. -### MLE Key Alias +#### Option 2: Provide Private Key Object -Another optional parameter for MLE is `mleKeyAlias`, which specifies the key alias used to retrieve the MLE certificate from the JWT P12 file. +- **Variable**: `responseMlePrivateKey` +- **Type**: `OpenSSLAsymmetricKey` +- **Description**: Direct private key object for response decryption. -- **Variable**: `mleKeyAlias` +### Response MLE Private Key Password + +- **Variable**: `responseMlePrivateKeyFilePassword` - **Type**: `string` -- **Default**: `CyberSource_SJC_US` -- **Description**: By default, CyberSource uses the `CyberSource_SJC_US` public certificate to encrypt the payload. However, users can override this default value by setting their own key alias. +- **Description**: Password for the private key file (required for `.p12/.pfx` files or encrypted private keys and encrypted files). + +### Response MLE Key ID (KID) + +- **Variable**: `responseMleKID` +- **Type**: `string` +- **Description**: Key ID used in JWT header for response MLE. This identifies which private key should be used for decryption. + +## 3. API-level MLE Control for Request and Response MLE + +### Map Configuration + +- **Variable**: `mapToControlMLEonAPI` +- **Type**: `Map` +- **Description**: Overrides global MLE settings for specific APIs. The key is the API function name, and the value controls both request and response MLE. +- **Example**: `Map<'apiFunctionName', 'true::true'>` + +#### Structure of Values in Map: + +(i) **"requestMLE::responseMLE"** - Control both request and response MLE + - `"true::true"` - Enable both request and response MLE + - `"false::false"` - Disable both request and response MLE + - `"true::false"` - Enable request MLE, disable response MLE + - `"false::true"` - Disable request MLE, enable response MLE + - `"::true"` - Use global setting for request, enable response MLE + - `"true::"` - Enable request MLE, use global setting for response + - `"::false"` - Use global setting for request, disable response MLE + - `"false::"` - Disable request MLE, use global setting for response + +(ii) **"requestMLE"** - Control request MLE only (response uses global setting) + - `"true"` - Enable request MLE + - `"false"` - Disable request MLE ## Notes -- If `useMLEGlobally` is set to true, it will enable MLE for all API calls that support MLE by CyberSource, unless overridden by mapToControlMLEonAPI. + +### Request MLE Notes +- If `useMLEGlobally` or enableRequestMLEForOptionalApis is set to true, it will enable Request MLE for all API calls that support MLE by CyberSource, unless overridden by mapToControlMLEonAPI. - If `mapToControlMLEonAPI` is not provided or does not contain a specific API function name, the global useMLEGlobally setting will be applied. - The `mleKeyAlias` parameter is optional and defaults to CyberSource_SJC_US if not specified by the user. Users can override this default value by setting their own key alias. +### Response MLE Notes +- Response MLE automatically detects and decrypts MLE-encrypted responses when enabled. +- If `enableResponseMleGlobally` is set to true, it will enable Response MLE for all API calls that support Response MLE. +- Either `responseMlePrivateKeyFilePath` or `responseMlePrivateKey` must be configured for Response MLE to work. +- The `responseMleKID` parameter is required when Response MLE is enabled. + ## Example Configuration +### (i) Minimal Request MLE Configuration + ```php -// Enable MLE globally for all supported APIs -$merchantConfig->setUseMLEGlobally(true); +// Array-based configuration - Uses defaults (most common scenario) +$merchantConfig = new MerchantConfiguration(); +$merchantConfig->setEnableRequestMLEForOptionalApisGlobally(true); +// Both mleForRequestPublicCertPath and requestMleKeyAlias are optional +// SDK will use JWT P12 file with default alias "CyberSource_SJC_US" ``` -Or +### (ii) Request MLE with Deprecated Parameters (Backward Compatibility) ```php -// Enable MLE globally for all supported APIs -$merchantConfig->setUseMLEGlobally(true); +// Using deprecated parameters - still supported but not recommended +$merchantConfig = new MerchantConfiguration(); +$merchantConfig->setUseMLEGlobally(true); // Deprecated - use setEnableRequestMLEForOptionalApisGlobally +$merchantConfig->setMleKeyAlias('Custom_Key_Alias'); // Deprecated - use setRequestMleKeyAlias +``` -// Optionally, control MLE at the API level -$merchantConfig->setMapToControlMLEonAPI([ - 'apiFunctionName1' => false, // Disable MLE for this specific API - 'apiFunctionName2' => true // Enable MLE for this specific API -]); +### (iii) Request MLE with Custom Key Alias -// Optionally, set a custom MLE key alias -$merchantConfig->setMleKeyAlias('Custom_Key_Alias'); +```php +// Configuration - With custom key alias only +$merchantConfig = new MerchantConfiguration(); +$merchantConfig->setEnableRequestMLEForOptionalApisGlobally(true); +$merchantConfig->setRequestMleKeyAlias('Custom_Key_Alias'); +// Will fetch from JWT P12 file using custom alias ``` -Or +### (iv) Request MLE with Separate Certificate File ```php -// Disable MLE globally for all supported APIs -$merchantConfig->setUseMLEGlobally(false); +// Configuration - With separate MLE certificate file +$merchantConfig = new MerchantConfiguration(); +$merchantConfig->setEnableRequestMLEForOptionalApisGlobally(true); +$merchantConfig->setMleForRequestPublicCertPath('/path/to/public/cert.pem'); +$merchantConfig->setRequestMleKeyAlias('Custom_Key_Alias'); -// Optionally, enable MLE for some APIs -$merchantConfig->setMapToControlMLEonAPI([ - 'apiFunctionName1' => true, // Enable MLE for this specific API - 'apiFunctionName2' => true // Enable MLE for this specific API -]); +// API-specific control +$mleControlMap = [ + 'createPayment' => 'true', // Enable request MLE for this API + 'capturePayment' => 'false' // Disable request MLE for this API +]; +$merchantConfig->setMapToControlMLEonAPI($mleControlMap); +``` + +### (v) Response MLE Configuration with Private Key File + +```php +// Configuration with private key file +$merchantConfig = new MerchantConfiguration(); +$merchantConfig->setEnableResponseMleGlobally(true); +$merchantConfig->setResponseMlePrivateKeyFilePath('/path/to/private/key.p12'); +$merchantConfig->setResponseMlePrivateKeyFilePassword('password'); +$merchantConfig->setResponseMleKID('your-key-id'); -// Optionally, set a custom MLE key alias -$merchantConfig->setMleKeyAlias('Custom_Key_Alias'); +// API-specific control +$mleControlMap = [ + 'createPayment' => '::true' // Enable response MLE only for this API +]; +$merchantConfig->setMapToControlMLEonAPI($mleControlMap); ``` -In the above examples: -- MLE is enabled/disabled globally (`useMLEGlobally` is true/false). -- `apiFunctionName1` will have MLE disabled/enabled based on value provided. -- `apiFunctionName2` will have MLE enabled. -- `mleKeyAlias` is set to `Custom_Key_Alias`, overriding the default value. +### (vi) Response MLE Configuration with Private Key Object + +```php +// Load private key programmatically +$privateKey = openssl_pkey_get_private(file_get_contents('/path/to/private/key.pem'), 'password'); + +// Create MerchantConfig with private key object +$merchantConfig = new MerchantConfiguration(); +$merchantConfig->setEnableResponseMleGlobally(true); +$merchantConfig->setResponseMleKID('your-key-id'); +$merchantConfig->setResponseMlePrivateKey($privateKey); +``` + +### (vii) Both Request and Response MLE Configuration + +```php +// Complete configuration for both request and response MLE +$merchantConfig = new MerchantConfiguration(); + +// Request MLE settings (minimal - uses defaults) +$merchantConfig->setEnableRequestMLEForOptionalApisGlobally(true); + +// Response MLE settings +$merchantConfig->setEnableResponseMleGlobally(true); +$merchantConfig->setResponseMlePrivateKeyFilePath('/path/to/private/key.p12'); +$merchantConfig->setResponseMlePrivateKeyFilePassword('password'); +$merchantConfig->setResponseMleKID('your-key-id'); + +// API-specific control for both request and response +$mleControlMap = [ + 'createPayment' => 'true::true', // Enable both request and response MLE for this API + 'capturePayment' => 'false::true', // Disable request, enable response MLE for this API + 'refundPayment' => 'true::false', // Enable request, disable response MLE for this API + 'createCredit' => '::true' // Use global request setting, enable response MLE for this API +]; +$merchantConfig->setMapToControlMLEonAPI($mleControlMap); +``` + +### (viii) Mixed Configuration (New and Deprecated Parameters) + +```php +// Example showing both new and deprecated parameters (deprecated will be used as aliases) +$merchantConfig = new MerchantConfiguration(); + +// If both are set with same value, it works fine +$merchantConfig->setEnableRequestMLEForOptionalApisGlobally(true); +$merchantConfig->setUseMLEGlobally(true); // Deprecated but same value + +// If both are set with different values, it will cause ConfigException +// $merchantConfig->setEnableRequestMLEForOptionalApisGlobally(true); +// $merchantConfig->setUseMLEGlobally(false); // This would cause an error + +// Key alias - new parameter takes precedence if both are provided +$merchantConfig->setRequestMleKeyAlias('New_Alias'); +$merchantConfig->setMleKeyAlias('Old_Alias'); // This will be ignored +``` + +## JSON Configuration Examples + +### (i) Minimal Request MLE + +```json +{ + "merchantConfig": { + "enableRequestMLEForOptionalApisGlobally": true + } +} +``` + +### (ii) Request MLE with Deprecated Parameters + +```json +{ + "merchantConfig": { + "useMLEGlobally": true, + "mleKeyAlias": "Custom_Key_Alias" + } +} +``` + +### (iii) Request MLE with Custom Configuration + +```json +{ + "merchantConfig": { + "enableRequestMLEForOptionalApisGlobally": true, + "mleForRequestPublicCertPath": "/path/to/public/cert.pem", + "requestMleKeyAlias": "Custom_Key_Alias", + "mapToControlMLEonAPI": { + "createPayment": "true", + "capturePayment": "false" + } + } +} +``` + +### (iv) Response MLE Only + +```json +{ + "merchantConfig": { + "enableResponseMleGlobally": true, + "responseMlePrivateKeyFilePath": "/path/to/private/key.p12", + "responseMlePrivateKeyFilePassword": "password", + "responseMleKID": "your-key-id", + "mapToControlMLEonAPI": { + "createPayment": "::true" + } + } +} +``` + +### (v) Both Request and Response MLE + +```json +{ + "merchantConfig": { + "enableRequestMLEForOptionalApisGlobally": true, + "enableResponseMleGlobally": true, + "responseMlePrivateKeyFilePath": "/path/to/private/key.p12", + "responseMlePrivateKeyFilePassword": "password", + "responseMleKID": "your-key-id", + "mapToControlMLEonAPI": { + "createPayment": "true::true", + "capturePayment": "false::true", + "refundPayment": "true::false", + "createCredit": "::true" + } + } +} +``` Please refer given link for sample codes with MLE: https://github.com/CyberSource/cybersource-rest-samples-php/tree/master/Samples/MLEFeature @@ -88,12 +354,90 @@ https://github.com/CyberSource/cybersource-rest-samples-php/tree/master/Samples/ ## Additional Information ### API Support -- MLE is initially designed to support a few APIs. -- It can be extended to support more APIs in the future based on requirements and updates. +- Request MLE is initially designed to support a few APIs and can be extended to support more APIs in the future based on requirements and updates. +- Response MLE is automatically applied to APIs that return MLE-encrypted responses when enabled. + ### Authentication Type -- MLE is only supported with `JWT (JSON Web Token)` authentication type within the SDK. +- Both Request MLE and Response MLE are only supported with `JWT (JSON Web Token)` authentication type within the SDK. + +### Private Key Management (Response MLE) +- **Supported Formats**: PKCS#12 (.p12, .pfx), PEM (.pem), KEY (.key), PKCS#8 (.p8) +- **Security**: Use password-protected private keys and store them securely + ### Using the SDK -To use the MLE feature in the SDK, configure the `merchantConfig` object as shown above and pass it to the SDK initialization. +To use the MLE features in the SDK: +1. Configure JWT authentication in the `merchantConfig` object +2. Enable Request MLE and/or Response MLE as needed +3. Configure appropriate certificates and private keys +4. Pass the configured `merchantConfig` object to the SDK initialization + +### Automatic Behavior +- **Request MLE**: When enabled, automatically encrypts request payloads before sending to CyberSource APIs +- **Response MLE**: When enabled, automatically detects and decrypts MLE-encrypted responses from CyberSource APIs + +## Usage Examples + +### Basic Payment with Request and Response MLE + +```php +createPayment($paymentRequest); + + // Access response data (already decrypted if applicable) + echo "Payment ID: " . $response->getId() . "\n"; + echo "Status: " . $response->getStatus() . "\n"; + +} catch (Exception $e) { + echo "Error: " . $e->getMessage() . "\n"; +} +``` + +## Troubleshooting + +### Common Issues + +1. **"Response MLE private key not available for decryption"** + - Ensure `responseMlePrivateKeyFilePath` is set and file exists + - Verify file permissions allow reading the private key file + - Check that `responseMlePrivateKeyFilePassword` is correct for encrypted keys + +2. **"Failed to extract Response MLE token"** + - Enable debug logging to inspect response format + - Verify the response is actually MLE-encrypted + +3. **Request MLE not working** + - Confirm JWT authentication is properly configured + - Verify `enableRequestMLEForOptionalApisGlobally` is set to `true` or specific APIs are enabled in `mapToControlMLEonAPI` + - Check that the API supports Request MLE + +### Debug Logging + +Enable detailed logging to troubleshoot MLE issues: + +```php +use CyberSource\Logging\LogConfiguration; + +$logConfig = new LogConfiguration(); +$logConfig->setLogLevel('debug'); +$logConfig->setLogDirectory('./logs'); +$logConfig->setLogFilename('cybersource-mle.log'); +$logConfig->setMaskingEnabled(true); // Mask sensitive data + +$merchantConfig->setLogConfiguration($logConfig); +``` ## Contact For any issues or further assistance, please open an issue on the GitHub repository or contact our support team. \ No newline at end of file