/

Clock Tampering Detection

Protection Module: ClockTampering

Available For

PlatformVersionStatus
iOS12.0+✓ Full Support
iPadOS12.0+✓ Full Support
tvOS12.0+✓ Supported

How It Works

The Clock Tampering Detection module identifies attempts to manipulate device system time. It uses multiple techniques to detect both forward and backward time shifts:

Detection Techniques

  • HTTP Time APIs: Queries public time servers (worldtimeapi.org, timeapi.io, worldclockapi.com) to retrieve accurate current time and compare against device clock.
  • Monotonic Clock Comparison: Uses mach_absolute_time() or ProcessInfo.processInfo.systemUptime which cannot be manipulated by users, and compares against wall-clock time to detect tampering.
  • Cached Reference Time: Maintains a cached reference time point along with monotonic clock reading for offline detection of time shifts when network is unavailable.
  • Forward/Backward Detection: Identifies both forward time jumps (credential expiration bypass) and backward jumps (session replay attacks).

Detection Confidence:

  • Fresh HTTP comparison: 0.95 (95%)
  • Cached monotonic comparison: 0.85 (85%)

Default Threshold: 86400 seconds (24 hours)

Default Interval: 300 seconds (5 minutes)

JSON Configuration

JSON
{
  "protections": [
    {
      "type": "ClockTampering",
      "action": "close",
      "intervalMs": 300000,
      "threshold": 86400
    }
  ]
}

Code-Based Configuration

Swift

Swift
import ByteHideMonitor

BHMMonitor.configure { config in
    config.enableProtection(.clockTampering, action: .close, intervalMs: 300000)
}

Objective-C

OBJC
#import <ByteHideMonitor/ByteHideMonitor.h>

[BHMMonitor configure:^(BHMMonitorConfiguration *config) {
    [config enableProtection:BHMProtectionModuleTypeClockTampering
                      action:BHMActionTypeClose
                  intervalMs:300000];
}];

Available Actions

ActionBehaviorRecommended For
CloseTerminate application immediatelyProduction apps with critical IP
LogRecord incident and continueDevelopment, analytics
EraseSecurely delete data then terminateFinancial, healthcare apps
CustomExecute custom handlerEnterprise integrations
NoneDetect only, no actionTesting configurations

See Actions for detailed action documentation.

When to Use

  • Financial Apps: Prevent exploitation of time-based security mechanisms in trading apps
  • Session-Based Security: Detect session replay attacks enabled by time manipulation
  • Subscription Services: Prevent unauthorized access through certificate expiration bypass
  • Time-Sensitive APIs: Protect APIs that enforce time-based authentication windows
  • Credential Management: Ensure expired credentials are properly invalidated
  • Certificate Validation: Enhance X.509 certificate validation against time spoofing
  • Development: Use Log action to track time sync issues

Code Examples

Swift Basic Configuration

Swift
import ByteHideMonitor

// In your AppDelegate or app initialization
BHMMonitor.configure { config in
    config.enableProtection(.clockTampering, action: .close, intervalMs: 300000)
}

Swift with Custom Action

Swift
import ByteHideMonitor

BHMMonitor.configure { config in
    // Register custom handler for clock tampering detection
    config.registerCustomAction("clock-tampering-handler") { context in
        let threatType = context.threatType
        let description = context.threatDescription
        let metadata = context.metadata

        // Extract time deviation details
        if let evidence = context.detectionResult?.evidence {
            let timeDifference = evidence["time_difference_seconds"] as? Int ?? 0
            let direction = evidence["drift_direction"] as? String ?? "unknown"

            // Invalidate time-dependent credentials
            if timeDifference > 3600 { // More than 1 hour
                CredentialManager.invalidateAllCredentials()
                SessionManager.endAllSessions()
            }

            // Log time anomaly
            Analytics.log(event: "clock_tampering_detected", parameters: [
                "threat_type": threatType,
                "time_difference_seconds": timeDifference,
                "direction": direction,
                "timestamp": ISO8601DateFormatter().string(from: Date())
            ])
        }

        // Report to backend
        SecurityAPI.reportClockTampering(
            threatType: threatType,
            description: description,
            metadata: metadata
        )
    }

    config.enableProtection(.clockTampering, customAction: "clock-tampering-handler", intervalMs: 300000)
}

Objective-C Basic Configuration

OBJC
#import <ByteHideMonitor/ByteHideMonitor.h>

[BHMMonitor configure:^(BHMMonitorConfiguration *config) {
    [config enableProtection:BHMProtectionModuleTypeClockTampering
                      action:BHMActionTypeClose
                  intervalMs:300000];
}];

Objective-C with Custom Action

OBJC
#import <ByteHideMonitor/ByteHideMonitor.h>

[BHMMonitor configure:^(BHMMonitorConfiguration *config) {
    [config registerCustomAction:@"clock-tampering-handler" handler:^(BHMThreatContext *context) {
        NSString *threatType = context.threatType;
        NSString *description = context.threatDescription;
        NSDictionary *metadata = context.metadata;

        // Extract time details
        if (context.detectionResult && context.detectionResult.evidence) {
            NSNumber *timeDiff = context.detectionResult.evidence[@"time_difference_seconds"];
            NSString *direction = context.detectionResult.evidence[@"drift_direction"];

            // Invalidate credentials if significant drift
            if ([timeDiff intValue] > 3600) {
                [CredentialManager invalidateAllCredentials];
                [SessionManager endAllSessions];
            }

            // Log event
            [Analytics logEvent:@"clock_tampering_detected"
                    parameters:@{
                        @"threat_type": threatType,
                        @"time_difference_seconds": timeDiff ?: @0,
                        @"direction": direction ?: @"unknown"
                    }];
        }

        // Report threat
        [SecurityAPI reportClockTamperingWithType:threatType
                                      description:description
                                         metadata:metadata];
    }];

    [config enableProtection:BHMProtectionModuleTypeClockTampering
                customAction:@"clock-tampering-handler"
                  intervalMs:300000];
}];

Platform Compatibility

FeatureiOS 12-13iOS 14-15iOS 16+
HTTP Time APIs✓✓✓
Monotonic Clock Detection✓✓✓
Cached Reference Time✓✓✓
Forward/Backward Detection✓✓✓
Offline Detection✓✓✓
Continuous Monitoring✓✓✓

Performance Impact

  • CPU Usage: ~0.2-0.3% per check cycle (when using HTTP APIs)
  • Memory Overhead: <300 KB (cached reference points)
  • Battery Impact: Low with 5-minute intervals
  • Network Usage: One HTTP request per check (~1-2 KB), can be skipped if cached
  • First Detection: <50ms for monotonic comparison, <500ms with HTTP validation

Threat Detection Details

JSON
{
  "threat": {
    "moduleType": "ClockTampering",
    "threatType": "ClockTampered",
    "threatDescription": "Device system time has been manipulated - detected forward time jump of 2 hours",
    "detectionResult": {
      "isThreat": true,
      "category": "TimeIntegrity",
      "threatDescription": "System clock manipulation detected",
      "confidence": 0.95,
      "evidence": {
        "drift_direction": "forward",
        "time_difference_seconds": 7200,
        "detection_method": "http_time_api",
        "reference_time_source": "worldtimeapi.org",
        "monotonic_clock_uptime": 45000,
        "wall_clock_delta": 7200,
        "cache_status": "fresh"
      },
      "timestamp": "2026-03-03T10:30:45.123Z"
    },
    "metadata": {
      "detection_method": "http_comparison",
      "api_response_time_ms": 450,
      "drift_threshold_seconds": 86400,
      "check_duration_ms": 520,
      "interval_ms": 300000,
      "online_status": true
    }
  }
}

Next Steps

Previous
Simulator Detection
Next
Tampering Detection