iOS File Protection Reference

Purpose: Comprehensive reference for file encryption and data protection APIs Availability: iOS 4.0+ (all protection levels), latest enhancements in iOS 26 Context: Built on iOS Data Protection architecture using hardware encryption

When to Use This Skill

Use this skill when you need to:

• Protect sensitive user data at rest
• Choose appropriate FileProtectionType for files
• Understand when files are accessible/encrypted
• Debug "file not accessible" errors after device lock
• Implement secure file storage
• Compare Keychain vs file protection approaches
• Handle background file access requirements

Overview

iOS Data Protection provides hardware-accelerated file encryption tied to the device passcode. When a user sets a passcode, every file can be encrypted with keys protected by that passcode.

Key concepts:

• Files are encrypted automatically when protection is enabled
• Encryption keys are derived from device hardware + user passcode
• Files become inaccessible when device is locked (depending on protection level)
• No performance cost (hardware AES encryption)

---

Protection Levels Comparison

Level	Encrypted Until	Accessible When	Use For	Background Access
complete	Device unlocked	Only while unlocked	Sensitive data (health, finances)	❌ No
completeUnlessOpen	File closed	After first unlock, while open	Large downloads, videos	✅ If already open
completeUntilFirstUserAuthentication	First unlock after boot	After first unlock	Most app data	✅ Yes
none	Never	Always	Public caches, temp files	✅ Yes

Detailed Level Descriptions

.complete

Full Description:

"The file is stored in an encrypted format on disk and cannot be read from or written to while the device is locked or booting."

Use For:

• User health data
• Financial information
• Password vaults
• Sensitive documents
• Personal photos (if app requires maximum security)

Behavior:

• Encrypted: ✅ Always
• Accessible: Only when device unlocked
• Background access: ❌ No (app can't read while locked)
• Available after boot: ❌ No (until user unlocks)

Code Example:

// ✅ CORRECT: Maximum security for sensitive data
func saveSensitiveData(_ data: Data, to url: URL) throws {
    try data.write(to: url, options: .completeFileProtection)
}

// Or set on existing file
try FileManager.default.setAttributes(
    [.protectionKey: FileProtectionType.complete],
    ofItemAtPath: url.path
)

Tradeoffs:

• ✅ Maximum security
• ❌ Can't access in background
• ❌ User sees errors if app tries to access while locked

.completeUnlessOpen

Full Description:

"The file is stored in an encrypted format on disk after it is closed."

Use For:

• Large file downloads (continue in background)
• Video files being played
• Documents being edited
• Any file that needs background access while open

Behavior:

• Encrypted: ✅ When closed
• Accessible: After first unlock, remains accessible while open
• Background access: ✅ Yes (if file was already open)
• Available after boot: ❌ No (until first unlock)

Code Example:

// ✅ CORRECT: Download in background, but encrypted when closed
func startBackgroundDownload(url: URL, destination: URL) throws {
    try Data().write(to: destination, options: .completeFileProtectionUnlessOpen)

    // Open file handle for writing
    let fileHandle = try FileHandle(forWritingTo: destination)

    // Download continues in background
    // File remains accessible because it's open
    // When closed, file becomes encrypted

    // Later, when download complete:
    try fileHandle.close()  // Now encrypted until next unlock
}

Tradeoffs:

• ✅ Good security (encrypted when not in use)
• ✅ Background access (if already open)
• ⚠️ Vulnerable while open

.completeUntilFirstUserAuthentication

Full Description:

"The file is stored in an encrypted format on disk and cannot be accessed until after the device has booted."

Use For:

• Most application data
• User preferences
• Downloaded content
• Database files
• Anything that needs background access

Behavior:

• Encrypted: ✅ Always
• Accessible: After first unlock following boot
• Background access: ✅ Yes (after first unlock)
• Available after boot: ❌ No (until user unlocks once)

This is the recommended default for most files.

Code Example:

// ✅ CORRECT: Balanced security for most app data
func saveAppData(_ data: Data, to url: URL) throws {
    try data.write(
        to: url,
        options: .completeFileProtectionUntilFirstUserAuthentication
    )
}

// ✅ This file can be accessed in background after first unlock
func backgroundTaskCanAccessFile() {
    // This works even if device is locked (after first unlock)
    let data = try? Data(contentsOf: url)
}

Tradeoffs:

• ✅ Protected during boot (device stolen while off)
• ✅ Background access (normal operation)
• ⚠️ Accessible while locked (less protection than .complete)

.none

Full Description:

"The file has no special protections associated with it."

Use For:

• Public cache data
• Temporary files
• Non-sensitive downloads
• Thumbnails
• Only when absolutely necessary

Behavior:

• Encrypted: ❌ Never
• Accessible: ✅ Always
• Background access: ✅ Always
• Available after boot: ✅ Always

Code Example:

// ⚠️ USE SPARINGLY: Only for truly non-sensitive data
func cachePublicThumbnail(_ data: Data, to url: URL) throws {
    try data.write(to: url, options: .noFileProtection)
}

Tradeoffs:

• ✅ Always accessible
• ❌ No encryption
• ❌ Vulnerable if device is stolen

---

Setting File Protection

At File Creation

// ✅ RECOMMENDED: Set protection when writing
let sensitiveData = userData.jsonData()
try sensitiveData.write(
    to: fileURL,
    options: .completeFileProtection
)

On Existing Files

// ✅ CORRECT: Change protection on existing file
try FileManager.default.setAttributes(
    [.protectionKey: FileProtectionType.complete],
    ofItemAtPath: fileURL.path
)

Default Protection for Directory

// ✅ CORRECT: Set default protection for directory
// New files inherit this protection
try FileManager.default.setAttributes(
    [.protectionKey: FileProtectionType.completeUntilFirstUserAuthentication],
    ofItemAtPath: directoryURL.path
)

Checking Current Protection

// ✅ Check file's current protection level
func checkFileProtection(at url: URL) throws -> FileProtectionType? {
    let attributes = try FileManager.default.attributesOfItem(atPath: url.path)
    return attributes[.protectionKey] as? FileProtectionType
}

// Usage
if let protection = try? checkFileProtection(at: fileURL) {
    switch protection {
    case .complete:
        print("Maximum protection")
    case .completeUntilFirstUserAuthentication:
        print("Standard protection")
    default:
        print("Other protection")
    }
}

---

File Protection vs Keychain

Decision Matrix

Use Case	Recommended	Why
Passwords, tokens, keys	Keychain	Designed for small secrets
Small sensitive values (<few KB)	Keychain	More secure, encrypted separately
Files >1 KB	File Protection	Keychain not designed for large data
User documents	File Protection	Natural file-based storage
Structured secrets	Keychain	Query by key, access control

Code Comparison

// ✅ CORRECT: Small secrets in Keychain
let passwordData = password.data(using: .utf8)!
let query: [String: Any] = [
    kSecClass as String: kSecClassGenericPassword,
    kSecAttrAccount as