Skip to content

HEX_VALIDATION_SOLUTION.md

Latest commit

 

History

History
255 lines (190 loc) · 8.19 KB

HEX_VALIDATION_SOLUTION.md

File metadata and controls

255 lines (190 loc) · 8.19 KB

KNet Package hex2bin() Error Solution

🚨 Problem Description

The KNet package was experiencing fatal errors when processing payment responses from the KNet gateway due to malformed or corrupted hexadecimal data being passed to PHP's hex2bin() function.

Error Flow

KNet Gateway → /knet/response → ResponseController → KnetResponseService::decryptAndParse() → KPayClient::decryptAES() → hex2ByteArray() → hex2bin()

Root Causes

  • KNet sending corrupted/incomplete response data
  • Network issues truncating the response
  • Invalid characters in the encrypted payload
  • Empty or null response data
  • Character encoding issues

✅ Solution Implementation

1. New Exception Class: InvalidHexDataException

Created a specialized exception class that extends KnetException to handle hex validation errors with detailed debugging information.

Location: src/Exceptions/InvalidHexDataException.php

Features:

  • Specific factory methods for different error types
  • Detailed error information for debugging
  • Hex data preservation for analysis
  • Structured error details for logging

2. Enhanced KPayClient.php

Completely rewrote the hex2ByteArray() method with robust validation:

Key Improvements:

  • ✅ Input validation (null, empty, whitespace)
  • ✅ Hex string length validation (must be even)
  • ✅ Character validation (only valid hex characters)
  • ✅ Minimum length validation for AES decryption
  • ✅ Comprehensive error handling with try-catch
  • ✅ Debug logging when enabled
  • ✅ Detailed error analysis and reporting

New Methods:

  • generateDebugInfo() - Creates detailed debug information
  • analyzeHexString() - Analyzes hex string for common issues
  • debugHexData() - Utility method for debugging malformed data
  • testHexConversion() - Tests conversion on small samples

3. Enhanced KnetResponseService.php

Improved error handling in the decryptAndParse() method:

Key Improvements:

  • ✅ Enhanced request validation
  • ✅ Specific handling for InvalidHexDataException
  • ✅ Detailed logging with request context
  • ✅ Debug mode support for raw data logging
  • ✅ Graceful exception chaining

4. Enhanced ResponseController.php

Updated the response controller to handle different exception types gracefully:

Key Improvements:

  • ✅ Specific handling for InvalidHexDataException
  • ✅ Specific handling for AccessDeniedHttpException
  • ✅ User-friendly error messages
  • ✅ Detailed logging with request context
  • ✅ Proper error code categorization

5. Enhanced Configuration

Added comprehensive debugging options to config/knet.php:

New Configuration Options:

// Debugging Configuration
'debug_hex_conversion' => env('KNET_DEBUG_HEX_CONVERSION', false),
'debug_response_data' => env('KNET_DEBUG_RESPONSE_DATA', false),
'debug_transactions' => env('KNET_DEBUG_TRANSACTIONS', false),
'debug_encryption' => env('KNET_DEBUG_ENCRYPTION', false),
'debug_validation_failures' => env('KNET_DEBUG_VALIDATION_FAILURES', true),
'debug_hex_preview_length' => env('KNET_DEBUG_HEX_PREVIEW_LENGTH', 200),
'debug_auto_hex_analysis' => env('KNET_DEBUG_AUTO_HEX_ANALYSIS', false),

// Error Handling Configuration
'retry_hex_conversion' => env('KNET_RETRY_HEX_CONVERSION', true),
'max_hex_retry_attempts' => env('KNET_MAX_HEX_RETRY_ATTEMPTS', 2),
'store_failed_hex_data' => env('KNET_STORE_FAILED_HEX_DATA', false),
'hex_validation_mode' => env('KNET_HEX_VALIDATION_MODE', 'strict'),

🔧 Usage Examples

Environment Configuration

Add these to your .env file for debugging:

# Enable hex conversion debugging
KNET_DEBUG_HEX_CONVERSION=true

# Enable response data debugging
KNET_DEBUG_RESPONSE_DATA=true

# Enable validation failure logging
KNET_DEBUG_VALIDATION_FAILURES=true

# Set hex validation mode (strict, lenient, fallback)
KNET_HEX_VALIDATION_MODE=strict

Manual Hex Data Debugging

use Asciisd\Knet\KPayClient;

// Debug malformed hex data
$debugInfo = KPayClient::debugHexData($suspiciousHexString);
logger()->info('Hex Debug Analysis:', $debugInfo);

// Generate debug information for errors
$debugInfo = KPayClient::generateDebugInfo($hexString, 'Manual analysis');

Exception Handling

use Asciisd\Knet\Exceptions\InvalidHexDataException;
use Asciisd\Knet\Services\KnetResponseService;

try {
    $payload = KnetResponseService::decryptAndParse($request);
} catch (InvalidHexDataException $e) {
    // Handle hex validation errors
    logger()->error('Hex validation failed:', $e->getErrorDetails());
    
    // Get detailed debug information
    $debugInfo = $e->getDebugInfo();
    $hexData = $e->getHexData();
    
    // Handle gracefully...
}

📊 Benefits

✅ Graceful Error Handling

  • No more fatal errors from hex2bin()
  • Proper exception handling with detailed context
  • User-friendly error messages

✅ Better Debugging

  • Detailed logging helps identify root causes
  • Hex data analysis for troubleshooting
  • Request context preservation

✅ Input Validation

  • Prevents invalid data from causing crashes
  • Multiple validation layers
  • Character-by-character analysis

✅ Backward Compatibility

  • Existing functionality remains unchanged
  • Non-breaking changes
  • Graceful degradation

✅ Production Ready

  • Handles edge cases effectively
  • Meaningful error messages
  • Comprehensive logging

🧪 Testing

Comprehensive unit tests have been created to verify the solution:

Test Coverage:

  • ✅ Valid hex string conversion
  • ✅ Empty/null input handling
  • ✅ Odd length validation
  • ✅ Invalid character detection
  • ✅ Minimum length validation
  • ✅ Whitespace trimming
  • ✅ Debug utility functions
  • ✅ Exception detail verification
  • ✅ Case sensitivity handling

Run Tests:

php artisan test tests/Unit/KPayClientHexValidationTest.php

🚀 Deployment Checklist

Before Deployment

  • Update package version in composer.json
  • Update CHANGELOG.md with new features
  • Test with actual KNet responses
  • Verify logging configuration
  • Review error handling flows

After Deployment

  • Monitor logs for hex validation issues
  • Verify error handling works as expected
  • Check user experience with error messages
  • Analyze debugging data if issues occur

📝 Error Types Handled

Error Type Description Exception User Message
Empty Data Null or empty hex string InvalidHexDataException::emptyData() No response from gateway
Invalid Characters Non-hex characters in string InvalidHexDataException::invalidCharacters() Corrupted response data
Odd Length Hex string has odd number of chars InvalidHexDataException::oddLength() Malformed response format
Too Short Hex string shorter than minimum InvalidHexDataException::corruptedData() Incomplete response data
Conversion Failed hex2bin() returned false InvalidHexDataException::invalidCharacters() Data processing failed

🔍 Troubleshooting

Common Issues

  1. Still getting hex2bin errors?

    • Check if the new code is deployed
    • Verify exception handling is working
    • Enable debug logging to see detailed errors

  2. Too much logging?

    • Disable debug options in production
    • Use KNET_DEBUG_VALIDATION_FAILURES=false to reduce noise
    • Adjust KNET_DEBUG_HEX_PREVIEW_LENGTH to limit log size

  3. Need to analyze failed hex data?

    • Enable KNET_STORE_FAILED_HEX_DATA=true
    • Use KPayClient::debugHexData() for analysis
    • Check logs for detailed hex analysis

Performance Considerations

  • Debug logging can impact performance in high-traffic scenarios
  • Disable unnecessary debug options in production
  • The hex validation adds minimal overhead to normal operations
  • Exception handling is only triggered on actual errors

📚 References

This solution transforms a fatal hex2bin() error into a manageable exception with proper logging and user feedback, making your KNet package much more robust and production-ready.