Expo Mutual TLS

Overview

expo-mutual-tls is a production-ready Expo module that provides secure, hardware-backed mutual TLS (mTLS) client certificate authentication for mobile applications. Built with native implementations for both iOS (Swift) and Android (Kotlin), it offers enterprise-grade security features with a developer-friendly API.

Key Achievements

• 🔐 Hardware-backed security using iOS Keychain & Android Keystore
• 📱 Cross-platform native implementations (iOS Swift + Android Kotlin)
• 🎯 Simple, intuitive API design with TypeScript support
• 📋 Multi-format certificate support (P12/PKCS#12 and PEM)
• 🔒 Optional biometric authentication integration
• 📊 Comprehensive event system for debugging and monitoring
• ⚡ Production-optimized performance
• 🛡️ Enterprise-ready with certificate validation

View on GitHub | NPM Package

Technical Architecture

System Design

The module follows Expo's native module architecture pattern with three distinct layers:

┌─────────────────────────────────────────┐
│     JavaScript/TypeScript Layer         │
│  (ExpoMutualTls Utility Wrapper)        │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│       Expo Module Bridge Layer          │
│   (ExpoModulesCore Integration)         │
└──────┬───────────────────────┬──────────┘
       │                       │
┌──────▼────────┐     ┌────────▼─────────┐
│  iOS Native   │     │ Android Native   │
│    (Swift)    │     │    (Kotlin)      │
└───────────────┘     └──────────────────┘

Core Components

TypeScript Layer (src/)

1. ExpoMutualTls.ts - Main utility class providing simplified API

• Static methods for configuration and certificate management
• Event handling utilities
• Wrapper around raw module for better DX

2. ExpoMutualTls.types.ts - TypeScript type definitions

• Strong typing for all API methods
• Event payload interfaces
• Configuration types
• Request/Response types

3. ExpoMutualTlsModule.ts - Raw module exports

• Direct bridge to native implementations
• Auto-generated by Expo Module Scripts

iOS Native Layer (ios/)

1. ExpoMutualTlsModule.swift - Main iOS module

// Thread-safe state management
private let stateQueue = DispatchQueue(label: "com.expo.mutualtls.state")
private var _isConfigured: Bool = false
private var _currentConfig: MutualTlsConfig?
 
// Core components initialization
private let keychainManager = KeychainManager.shared
private let certificateParser = CertificateParser.shared
internal let networkManager = NetworkManager()

2. KeychainManager.swift - Secure certificate storage

• iOS Keychain integration
• Hardware-backed encryption
• Biometric authentication support

3. CertificateParser.swift - Certificate format handling

• P12/PKCS#12 parsing
• PEM certificate parsing
• X.509 validation
• Extended Key Usage (EKU) verification

4. SSLContextManager.swift - TLS context management

• SSL/TLS context creation
• Client certificate binding
• Trust chain validation

5. NetworkManager.swift - HTTP networking

• URLSession integration
• Custom SSL delegate
• Request/response handling

6. ExpoMutualTlsTypes.swift - Swift type definitions

• Configuration structures
• Result types
• State enumerations

7. ExpoMutualTlsErrors.swift - Error handling

• Typed error definitions
• Error propagation to JS layer

Android Native Layer (android/)

1. ExpoMutualTlsModule.kt - Main Android module

companion object {
    private const val MODULE_NAME = "ExpoMutualTls"
    @Volatile private var isConfigured = false
    @Volatile private var sslSocketFactory: SSLSocketFactory? = null
    @Volatile private var trustManager: X509TrustManager? = null
}
 
private val keychain by lazy { KeychainManager(ctx) }
private val pemParser by lazy { PemCertificateParser() }

2. KeychainManager.kt - Android secure storage

• Android Keystore integration
• Hardware-backed keys when available
• Biometric API integration

3. PemCertificateParser.kt - Certificate parsing

• BouncyCastle integration
• PEM format parsing
• Certificate chain construction

Build Flow & Development Pipeline

Build Architecture

Source Files (TypeScript + Native)
        ↓
┌───────────────────────────────┐
│   expo-module-scripts         │
│   - TypeScript compilation    │
│   - Type generation          │
│   - Build orchestration       │
└───────────┬───────────────────┘
            │
    ┌───────┴────────┐
    ▼                ▼
┌─────────┐    ┌──────────┐
│   iOS   │    │ Android  │
│ (Xcode) │    │ (Gradle) │
└────┬────┘    └────┬─────┘
     │              │
     └──────┬───────┘
            ▼
    NPM Package (.tgz)

Build Process Details

1. TypeScript Compilation

Configuration (tsconfig.json):

{
  "extends": "expo-module-scripts/tsconfig.base",
  "compilerOptions": {
    "outDir": "./build"
  },
  "include": ["./src"],
  "exclude": ["**/__tests__/*"]
}

Build Steps:

# 1. Clean previous builds
npm run clean  # → expo-module clean
 
# 2. Compile TypeScript to JavaScript
npm run build  # → expo-module build
# Outputs: build/index.js, build/index.d.ts
 
# 3. Generate type definitions
# Auto-generated from .types.ts files

2. iOS Native Build

CocoaPods Integration (ExpoMutualTls.podspec):

Pod::Spec.new do |s|
  s.name           = 'ExpoMutualTls'
  s.version        = '1.0.3'
  s.summary        = 'Expo Mutual TLS module'
  s.license        = 'MIT'
  s.authors        = 'A-Cube S.r.l.'
  s.homepage       = 'https://github.com/a-cube-io/expo-mutual-tls'
  s.platform       = :ios, '13.0'
  s.swift_version  = '5.4'
  s.source         = { git: 'https://github.com/a-cube-io/expo-mutual-tls.git' }
  s.source_files   = 'ios/**/*.{h,m,swift}'
 
  s.dependency 'ExpoModulesCore'
end

Build Process:

1. Swift files compiled via Xcode
2. Linked against iOS Security Framework
3. Integrated with ExpoModulesCore
4. Bundled into framework

Key iOS Frameworks Used:

• Security - Keychain and certificate management
• Foundation - Core utilities
• Network - TLS configuration
• CryptoKit - Cryptographic operations

3. Android Native Build

Gradle Integration (android/build.gradle):

dependencies {
    implementation project(':expo-modules-core')
    implementation 'org.bouncycastle:bcpkix-jdk15on:1.70'
    implementation 'com.squareup.okhttp3:okhttp:4.11.0'
}
 
android {
    compileSdkVersion 33
    defaultConfig {
        minSdkVersion 24
        targetSdkVersion 33
    }
    kotlinOptions {
        jvmTarget = '1.8'
    }
}

Build Process:

1. Kotlin files compiled via Gradle
2. BouncyCastle integrated for cryptography
3. OkHttp for networking
4. Android Keystore integration
5. Bundled into AAR

Key Android Dependencies:

• expo-modules-core - Expo module framework
• bouncycastle - Certificate parsing and crypto
• okhttp3 - HTTP client with SSL support
• Android Keystore API - Secure storage

4. Module Configuration

Expo Module Config (expo-module.config.json):

{
  "platforms": ["apple", "android", "web"],
  "apple": {
    "modules": ["ExpoMutualTlsModule"]
  },
  "android": {
    "modules": ["expo.modules.mutualtls.ExpoMutualTlsModule"]
  }
}

This configuration tells Expo how to link native modules on each platform.

NPM Package Scripts

{
  "scripts": {
    "build": "expo-module build",
    "clean": "expo-module clean",
    "lint": "expo-module lint",
    "test": "expo-module test",
    "prepare": "expo-module prepare",
    "prepublishOnly": "expo-module prepublishOnly"
  }
}

Script Purposes:

• build - Compile TypeScript and generate types
• clean - Remove build artifacts
• lint - Run ESLint checks
• test - Execute test suite
• prepare - Pre-installation setup (auto-runs on install)
• prepublishOnly - Final checks before NPM publish

Feature Deep Dive

1. Certificate Format Support

P12/PKCS#12 Format

• Industry standard for certificate + private key bundles
• Password-protected archives
• Single file deployment
• Wide compatibility

Implementation Flow:

Base64 P12 Data + Password
        ↓
iOS: Security Framework Parser
Android: KeyStore.getInstance("PKCS12")
        ↓
Extract Certificate + Private Key
        ↓
Store in Secure Storage
        ↓
Create SSL Context

PEM Format

• Human-readable text format
• Separate certificate and key files
• Standard for many enterprise systems

Implementation Flow:

PEM Certificate + PEM Private Key
        ↓
iOS: CertificateParser (SecCertificateCreateWithData)
Android: BouncyCastle PEMParser
        ↓
Parse X.509 Certificate
        ↓
Parse PKCS#8 Private Key
        ↓
Store Separately in Keychain
        ↓
Create SSL Context

2. Hardware-Backed Security

iOS Keychain Integration

// Keychain storage with hardware backing
let query: [String: Any] = [
    kSecClass as String: kSecClassGenericPassword,
    kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlock,
    kSecAttrService as String: serviceIdentifier,
    kSecValueData as String: certificateData
]
 
// Biometric protection (optional)
if requireBiometric {
    query[kSecAttrAccessControl] =
        SecAccessControlCreateWithFlags(
            nil,
            kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly,
            .biometryCurrentSet,
            nil
        )
}

Android Keystore Integration

// Generate wrapping key in hardware
val keyGenerator = KeyGenerator.getInstance(
    KeyProperties.KEY_ALGORITHM_AES,
    "AndroidKeyStore"
)
 
val keyGenSpec = KeyGenParameterSpec.Builder(
    keyAlias,
    KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT
)
.setBlockModes(KeyProperties.BLOCK_MODE_GCM)
.setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
.setUserAuthenticationRequired(requireBiometric)
.setUserAuthenticationValidityDurationSeconds(validitySeconds)
.build()
 
keyGenerator.init(keyGenSpec)
val secretKey = keyGenerator.generateKey()

3. SSL/TLS Context Management

iOS URLSession Integration

func urlSession(
    _ session: URLSession,
    didReceive challenge: URLAuthenticationChallenge,
    completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void
) {
    // Load client certificate from keychain
    let identity = loadClientIdentity()
    let credential = URLCredential(
        identity: identity,
        certificates: [certificate],
        persistence: .forSession
    )
 
    completionHandler(.useCredential, credential)
}

Android OkHttp Integration

val sslContext = SSLContext.getInstance("TLS")
val keyManagerFactory = KeyManagerFactory.getInstance(
    KeyManagerFactory.getDefaultAlgorithm()
)
keyManagerFactory.init(keyStore, password.toCharArray())
 
sslContext.init(
    keyManagerFactory.keyManagers,
    trustManagerFactory.trustManagers,
    SecureRandom()
)
 
val client = OkHttpClient.Builder()
    .sslSocketFactory(sslContext.socketFactory, trustManager)
    .build()

4. Event System Architecture

The module provides three event channels for comprehensive monitoring:

Debug Logging Events

ExpoMutualTls.onDebugLog((event) => {
  // event.type: 'certificate_storage' | 'network_request' |
  //             'keychain_operation' | 'tls_handshake'
  // event.message, event.url, event.statusCode, event.duration
})

Error Events

ExpoMutualTls.onError((event) => {
  // event.message, event.code
  // Codes: 'CERTIFICATE_NOT_FOUND', 'SSL_HANDSHAKE_FAILED', etc.
})

Certificate Expiry Warnings

ExpoMutualTls.onCertificateExpiry((event) => {
  // event.subject, event.expiry, event.warning
  // Automatic warnings N days before expiry
})

Security Implementation

Certificate Validation Pipeline

1. Format Validation
   ↓ Verify P12/PEM structure
2. Date Validation
   ↓ Check notBefore/notAfter
3. EKU Validation
   ↓ Verify clientAuth usage
4. Key Pair Validation
   ↓ Ensure private key matches certificate
5. Chain Validation
   ↓ Verify certificate chain integrity
6. Storage Validation
   ✓ Confirm secure storage success

Cryptographic Operations

iOS Security Framework:

• AES-256 for keychain encryption (hardware-backed)
• RSA/ECDSA for certificate keys
• TLS 1.2+ enforced
• Perfect Forward Secrecy support

Android Keystore:

• AES-256-GCM for wrapping keys (hardware when available)
• RSA/ECDSA key storage
• TLS 1.2+ enforced
• StrongBox backed storage on supported devices

Performance Characteristics

Benchmarks

Memory Footprint

• Module overhead: ~2-5MB (native code + crypto libs)
• Per-certificate: ~5-15KB (storage)
• Active SSL context: ~1-3MB (per connection)

Optimization Strategies

1. Lazy Loading: Components initialized only when needed
2. Connection Reuse: SSL sessions cached and reused
3. Thread Safety: Lock-free data structures where possible
4. Memory Management: Automatic cleanup of sensitive data

Development Workflow

Local Development Setup

# 1. Clone repository
git clone https://github.com/a-cube-io/expo-mutual-tls.git
cd expo-mutual-tls
 
# 2. Install dependencies
npm install
 
# 3. Build the module
npm run build
 
# 4. Run example app (iOS)
cd example
npx expo prebuild --platform ios
npx expo run:ios
 
# 5. Run example app (Android)
npx expo prebuild --platform android
npx expo run:android

Testing Strategy

Unit Tests (TypeScript):

• API surface validation
• Type checking
• Error handling

Integration Tests (Native):

• Certificate parsing
• Keychain operations
• SSL context creation

E2E Tests (Example App):

• Full mTLS flow
• Real network requests
• Error scenarios

Release Process

# Automated via scripts/release.sh
./scripts/release.sh patch  # 1.0.3 → 1.0.4
./scripts/release.sh minor  # 1.0.3 → 1.1.0
./scripts/release.sh major  # 1.0.3 → 2.0.0
 
# Steps performed:
# 1. Run tests
# 2. Update version in package.json
# 3. Build module
# 4. Git tag
# 5. NPM publish
# 6. GitHub release

Integration Example

Complete Implementation

import React, { useEffect, useState } from 'react'
import ExpoMutualTls from '@a-cube-io/expo-mutual-tls'
import { Asset } from 'expo-asset'
import * as FileSystem from 'expo-file-system'
 
export default function SecureApiClient() {
  const [status, setStatus] = useState('initializing')
 
  useEffect(() => {
    setupMtls()
  }, [])
 
  const setupMtls = async () => {
    try {
      // 1. Configure module
      await ExpoMutualTls.

Lessons Learned & Best Practices

Architecture Decisions

✅ What Worked Well:

• Native-first approach for security-critical operations
• Simplified utility wrapper over raw module API
• Event-driven debugging and monitoring
• Hardware-backed storage as default

📚 Key Takeaways:

• Platform-specific crypto APIs require careful abstraction
• Certificate lifecycle management needs comprehensive events
• Biometric integration varies significantly by platform
• SSL context caching crucial for performance

Security Considerations

1. Never Log Sensitive Data: Certificate data, passwords, keys
2. Validate Certificates Thoroughly: Dates, usage, chain
3. Use Hardware Backing: Always prefer hardware keystore
4. Implement Auto-Rotation: Monitor expiry, alert users
5. Fail Securely: Default to deny on validation failure

Performance Optimization

1. Lazy Initialize: Load components only when needed
2. Cache SSL Contexts: Reuse validated contexts
3. Async All Operations: Never block UI thread
4. Monitor Memory: Clean up sensitive data promptly

Future Enhancements

Planned Features

• Certificate Pinning: Additional security layer
• Multi-Certificate Support: Manage multiple client certs
• Certificate Renewal: Automated rotation workflows
• Cloud Backup: Encrypted certificate cloud sync
• Web Support: WebCrypto API implementation
• React Hooks: useMtls() custom hooks
• Certificate Health Monitoring: Proactive alerts

Community Contributions

The project welcomes contributions in:

• Additional certificate formats (JKS, etc.)
• Enhanced error recovery
• Performance optimizations
• Documentation improvements
• Example implementations

Technical Stack Summary

Languages & Frameworks

• TypeScript (4.9+) - Type-safe API surface
• Swift (5.4+) - iOS native implementation
• Kotlin (1.8+) - Android native implementation
• React Native (0.72+) - JavaScript runtime
• Expo (49+) - Module framework

Build Tools

• expo-module-scripts - Build orchestration
• Xcode - iOS compilation
• Gradle - Android compilation
• CocoaPods - iOS dependency management
• NPM - Package distribution

Libraries & Dependencies

• ExpoModulesCore - Native bridge
• BouncyCastle (Android) - Certificate parsing
• OkHttp (Android) - HTTP client
• iOS Security Framework - Keychain & crypto
• Android Keystore API - Secure storage

Conclusion

expo-mutual-tls demonstrates production-ready implementation of complex security features in a cross-platform mobile environment. The project successfully balances security requirements with developer experience, achieving:

• ✅ Enterprise-grade security through hardware-backed storage
• ✅ Simple, intuitive API hiding complexity
• ✅ Comprehensive monitoring and debugging capabilities
• ✅ Production-proven stability and performance
• ✅ Active maintenance and community support

The module serves as an excellent reference for:

• Expo native module development
• Cross-platform security implementation
• Certificate-based authentication
• Hardware security integration
• Event-driven architecture in mobile apps

Repository: github.com/a-cube-io/expo-mutual-tls Package: @a-cube-io/expo-mutual-tls License: MIT