iOS Holder SDK v5.0.0 Migration Guide

Overview

This guide provides a comprehensive overview of the changes introduced in MobileCredentialHolderSDK v5.0.0 for iOS, including breaking changes, new features, and migration steps.

Key Features

• Seamless, OS-native credential presentation (DC API support): The iOS Holder SDK now integrates with the Digital Credentials API, allowing credentials to be presented via an OS overlay without launching your holder app. The OS automatically surfaces only matching credentials across installed holders — reducing friction, avoiding dead ends, and significantly improving the user experience.
• Clearer OID4VCI interoperability (v1.0 alignment): The iOS Holder SDK now aligns with the finalized OID4VCI v1.0 specification (upgraded from draft-12). This alignment improves interoperability across the ecosystem, enabling other systems to clearly identify your supported version and feature set, ensuring smoother integrations and consistent behavior across platforms.
• Improved reliability in contactless flows: Enhanced BLE performance delivers more consistent proximity credential exchanges and faster engagements.
• Stronger cryptography and standards alignment: Updated COSE algorithms (as per RFC 9864) strengthen cryptographic compatibility and ensure continued compliance with evolving standards.
• General stability and performance improvements: Multiple refinements reduce integration friction, increase consistency across mobile environments, and improve overall user experience.

For a detailed list of changes included in this release, refer to the SDK Changelog.

Breaking Changes

This section outlines the breaking changes introduced in v5.0.0 that require updates to your existing implementation:

The following methods are unavailable in App Extensions:

• Initialization and lifecycle:
  • initialize
  • deinitialize
  • destroy
• Credential claiming:
  • discoverCredentialOffer
  • createAuthorizationSession
  • retrieveCredentials
• Credential management:
  • addCredential
  • deleteCredential
  • getCredentials
  • getCredential
• Key and certificate management:
  • generateDeviceKey
  • addTrustedIssuerCertificates
  • getTrustedIssuerCertificates
  • deleteTrustedIssuerCertificate
  • addTrustedVerifierCertificates
  • getTrustedVerifierCertificates
  • deleteTrustedVerifierCertificate
• Presentation sessions:
  • createProximityPresentationSession
  • getCurrentProximityPresentationSession
  • createOnlinePresentationSession
  • ProximityPresentationSession.sendResponse
  • terminateSession
  • OnlinePresentationSession.sendResponse
• Logging:
  • getCurrentLogFilePath

New Additions

Types (iOS 26+)

Methods

Enum Cases

Protocol Conformances

Framework Imports

import IdentityDocumentServices      // iOS 26+
import IdentityDocumentServicesUI    // iOS 26+

Backwards Compatible Changes

Deprecations

No new deprecations. Existing deprecations unchanged:

@available(*, deprecated, message: "Use .userPresence instead")
case biometricOrPasscode

@available(*, deprecated, message: "Use .biometryCurrentSet instead")
case biometricOnly

Bug Fixes

• Fixed intermittent "unable to initialize storage" errors during app launch. The issue was caused by using UserDefaults for keyId storage, which does not guarantee persistence—particularly during iOS app prewarming when protected data may be unavailable. The SDK now stores the keyId in the Keychain and performs explicit availability checks before initialization, throwing a new storageInitializedInBackground error when the keychain is inaccessible.
• Fixed a crash that could occur when getCredentials() or updateMobileCredentialStatus() were called concurrently from multiple threads. The crash was caused by unsafe concurrent access to internal state. The SDK now properly serializes access to shared resources during credential operations.

Minimum Requirements

• iOS 15+ for core SDK functionality
• iOS 26+ for Digital Credentials API (DC API) features

Dependencies

Third party dependencies

• CBORCoding (MIT license)
• swift-certificates 1.7.0 (Apache-2.0 License)
• swift-asn1 1.3.1 (Apache-2.0 License)

Apple frameworks

• Security
• CryptoKit
• LocalAuthentication
• AuthenticationServices
• CoreBluetooth
• Combine
• OSLog
• UIKit
• AppKit (on macOS)
• IdentityDocumentServices
• IdentityDocumentServicesUI

Toolchain dependencies

• Swift 5.10.
• iOS support: The SDK functionality is only available for devices from iOS 15 onwards.
• Xcode: The SDK requires Xcode 26.0.0 (17A324) or later. Our CI builds use the latest stable Xcode available in GitHub Actions (setup-xcode action with the latest-stable label). Ensure that your development environment and CI pipelines meet or exceed this minimum to avoid build failures.
• macOS 15 or later.

Migration Steps

- let credential = try await holder.getCredential(credentialId: id, skipStatusCheck: true)
+ let credential = try await holder.getCredential(credentialId: id, fetchUpdatedStatusList: false)

- await MobileCredentialHolder.shared.deinitialize()
+ MobileCredentialHolder.shared.deinitialize()

  struct OfferedCredential: Decodable {
+     let credentialConfigurationId: String
      let docType: String
      let claims: [Claim]
      let name: String?
  }

  switch verifierAuthenticationResult {
  case .authenticated(let verifierInfo):
      // Handle authenticated verifier
  case .failed(let error):
      // Handle authentication failure
+ case .unsigned(let origin):
+     // Handle unsigned/unauthenticated request (new in v5.0.0)
+     // origin contains the requesting website origin if available
  }

// In main app initialization
if #available(iOS 26.0, *) {
    let dcConfig = DCConfiguration(
        appGroup: "group.com.yourcompany.app",
        supportedDocTypes: [.mDL, .eudi]
    )
    try MobileCredentialHolder.shared.initialize(
        instanceID: instanceID,
        dcConfiguration: dcConfig
    )
} else {
    try MobileCredentialHolder.shared.initialize(instanceID: instanceID)
}

// In your IdentityDocumentProviderExtension
@available(iOS 26.0, *)
func handleRequest(_ context: ISO18013MobileDocumentRequestContext) async throws {
    // Initialize for extension context
    try MobileCredentialHolder.shared.initializeAppExtension(
        appGroup: "group.com.yourcompany.app"
    )
    
    // Create presentation session
    let session = try MobileCredentialHolder.shared.createDcPresentationSession(from: context)
    
    // Handle request...
    try await session.sendResponse(credentialIDs: selectedCredentialIDs)
}