iOS 文件保护完全指南：数据加密、FileProtectionType 详解与安全存储实践

axiom-file-protection-ref by charleswiltgen/axiom

154 周安装量

715 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/charleswiltgen/axiom --skill axiom-file-protection-ref

iOS 移动应用安全

🇨🇳中文介绍

iOS 文件保护参考

目的：文件加密和数据保护 API 的全面参考 可用性：iOS 4.0+（所有保护级别），iOS 26 中的最新增强功能背景：基于使用硬件加密的 iOS 数据保护架构构建

何时使用此技能

在以下情况下使用此技能：

保护静态的敏感用户数据
为文件选择合适的 FileProtectionType
了解文件何时可访问/已加密
调试设备锁定后的“文件不可访问”错误
实现安全的文件存储
比较 Keychain 与文件保护方法
处理后台文件访问需求

概述

iOS 数据保护提供与设备密码绑定的硬件加速文件加密。当用户设置密码时，每个文件都可以使用受该密码保护的密钥进行加密。

关键概念：

启用保护后，文件会被自动加密
加密密钥源自设备硬件 + 用户密码
设备锁定时文件变得不可访问（取决于保护级别）
无性能成本（硬件 AES 加密）

保护级别比较

级别	加密至	何时可访问	用于	后台访问
complete	设备解锁

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

Azure RBAC 权限管理工具：查找最小角色、创建自定义角色与自动化分配

129,699 周安装

OpenClaw 安全 Linux 云部署指南：私有优先、SSH隧道、Podman容器化

40,100 周安装

Linux云主机安全托管指南：从SSH加固到HTTPS部署

40,000 周安装

xdrop 文件传输脚本：Bun 环境下安全上传下载工具，支持加密分享

37,500 周安装

// ✅ 正确：在后台下载，但关闭时加密
func startBackgroundDownload(url: URL, destination: URL) throws {
    try Data().write(to: destination, options: .completeFileProtectionUnlessOpen)

    // 打开文件句柄用于写入
    let fileHandle = try FileHandle(forWritingTo: destination)

    // 下载在后台继续
    // 文件保持可访问，因为它是打开的
    // 关闭时，文件变为加密状态

    // 稍后，下载完成时：
    try fileHandle.close()  // 现在加密直到下次解锁
}

// ✅ 正确：为大多数应用数据提供平衡的安全性
func saveAppData(_ data: Data, to url: URL) throws {
    try data.write(
        to: url,
        options: .completeFileProtectionUntilFirstUserAuthentication
    )
}

// ✅ 此文件可以在首次解锁后在后台访问
func backgroundTaskCanAccessFile() {
    // 即使设备已锁定（首次解锁后），这也有效
    let data = try? Data(contentsOf: url)
}

// ✅ 检查文件的当前保护级别
func checkFileProtection(at url: URL) throws -> FileProtectionType? {
    let attributes = try FileManager.default.attributesOfItem(atPath: url.path)
    return attributes[.protectionKey] as? FileProtectionType
}

// 用法
if let protection = try? checkFileProtection(at: fileURL) {
    switch protection {
    case .complete:
        print("最高保护")
    case .completeUntilFirstUserAuthentication:
        print("标准保护")
    default:
        print("其他保护")
    }
}

使用场景	推荐	原因
密码、令牌、密钥	Keychain	专为小型机密设计
小型敏感值（<几KB）	Keychain	更安全，单独加密
文件 >1 KB	文件保护	Keychain 不适用于大数据
用户文档	文件保护	自然的基于文件的存储
结构化机密	Keychain	按键查询，访问控制

// ✅ 正确：将小型机密存储在 Keychain 中
let passwordData = password.data(using: .utf8)!
let query: [String: Any] = [
    kSecClass as String: kSecClassGenericPassword,
    kSecAttrAccount as String: "userPassword",
    kSecValueData as String: passwordData,
    kSecAttrAccessible as String: kSecAttrAccessibleWhenUnlocked
]
SecItemAdd(query as CFDictionary, nil)

// ✅ 正确：使用文件保护的文件
let userData = try JSONEncoder().encode(user)
try userData.write(to: fileURL, options: .completeFileProtection)

// ❌ 错误：.complete 文件无法在后台访问
class BackgroundTask {
    func performBackgroundSync() {
        // 如果文件具有 .complete 保护且设备已锁定，此操作将失败
        let data = try? Data(contentsOf: sensitiveFileURL)
        // 如果设备已锁定，data 将为 nil
    }
}

// ✅ 正确：使用 .completeUntilFirstUserAuthentication
// 首次解锁后文件可在后台访问
try data.write(
    to: fileURL,
    options: .completeFileProtectionUntilFirstUserAuthentication
)

所有 iCloud 数据在静态时加密（Apple 管理的密钥）
某些数据类型提供端到端加密（高级数据保护）
文件保护仅影响本地设备

// ✅ 正确：iCloud 文件的保护仅影响本地副本 func saveToICloud(data: Data, filename: String) throws { guard let iCloudURL = FileManager.default.url( forUbiquityContainerIdentifier: nil ) else { return }
```
let fileURL = iCloudURL.appendingPathComponent(filename)

// 此保护应用于本地缓存副本
try data.write(to: fileURL, options: .completeFileProtection)

// iCloud 对云存储有单独的加密
```
}

// ✅ 推荐：在应用启动时设置默认保护
func configureDefaultFileProtection() {
    let fileManager = FileManager.default

    let directories: [FileManager.SearchPathDirectory] = [
        .documentDirectory,
        .applicationSupportDirectory
    ]

    for directory in directories {
        guard let url = fileManager.urls(
            for: directory,
            in: .userDomainMask
        ).first else { continue }

        try? fileManager.setAttributes(
            [.protectionKey: FileProtectionType.completeUntilFirstUserAuthentication],
            ofItemAtPath: url.path
        )
    }
}

// 在应用初始化期间调用
func application(_ application: UIApplication, didFinishLaunchingWithOptions...) {
    configureDefaultFileProtection()
    return true
}

// ✅ 正确：保护 SwiftData/SQLite 数据库
let appSupportURL = FileManager.default.urls(
    for: .applicationSupportDirectory,
    in: .userDomainMask
)[0]

let databaseURL = appSupportURL.appendingPathComponent("app.sqlite")

// 在创建数据库之前设置保护
try? FileManager.default.setAttributes(
    [.protectionKey: FileProtectionType.completeUntilFirstUserAuthentication],
    ofItemAtPath: appSupportURL.path
)

// 现在创建数据库 - 它继承保护
let container = try ModelContainer(
    for: MyModel.self,
    configurations: ModelConfiguration(url: databaseURL)
)

// ⚠️ 有时必要：为后台访问降低保护
func enableBackgroundAccess(for url: URL) throws {
    try FileManager.default.setAttributes(
        [.protectionKey: FileProtectionType.completeUntilFirstUserAuthentication],
        ofItemAtPath: url.path
    )
}

// 仅在以下情况下执行此操作：
// 1. 确实需要后台访问
// 2. 数据敏感性允许
// 3. 已考虑安全权衡

场景	推荐保护	锁定时可访问？	后台访问？
用户健康数据	`.complete`	❌ 否	❌ 否
财务记录	`.complete`	❌ 否	❌ 否
大多数应用数据	`.completeUntilFirstUserAuthentication`	✅ 是（首次解锁后）	✅ 是
下载（大文件）	`.completeUnlessOpen`	✅ 打开时	✅ 打开时
数据库文件	`.completeUntilFirstUserAuthentication`	✅ 是	✅ 是
下载的图像	`.completeUntilFirstUserAuthentication`	✅ 是	✅ 是
公共缓存	`.none`	✅ 是	✅ 是
临时文件	`.none`	✅ 是	✅ 是

🇺🇸English

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 String: "userPassword",
    kSecValueData as String: passwordData,
    kSecAttrAccessible as String: kSecAttrAccessibleWhenUnlocked
]
SecItemAdd(query as CFDictionary, nil)

// ✅ CORRECT: Files with file protection
let userData = try JSONEncoder().encode(user)
try userData.write(to: fileURL, options: .completeFileProtection)

Keychain advantages :

More granular access control (Face ID/Touch ID)
Separate encryption (not tied to file system)
Survives app deletion (if configured)

File protection advantages :

Works with existing file operations
Handles large data efficiently
Automatic with minimal code

Background Access Considerations

iOS Background Modes and File Protection

// ❌ WRONG: .complete files can't be accessed in background
class BackgroundTask {
    func performBackgroundSync() {
        // This FAILS if file has .complete protection and device is locked
        let data = try? Data(contentsOf: sensitiveFileURL)
        // data will be nil if device locked
    }
}

// ✅ CORRECT: Use .completeUntilFirstUserAuthentication
// Files accessible in background after first unlock
try data.write(
    to: fileURL,
    options: .completeFileProtectionUntilFirstUserAuthentication
)

Handling Protection Errors

// ✅ CORRECT: Handle protection errors gracefully
func readFile(at url: URL) -> Data? {
    do {
        return try Data(contentsOf: url)
    } catch let error as NSError {
        if error.domain == NSCocoaErrorDomain &&
           error.code == NSFileReadNoPermissionError {
            // File is protected and device is locked
            print("File protected, device locked")
            return nil
        }
        throw error
    }
}

iCloud and File Protection

How Protection Works with iCloud

Local file protection :

Applied to local cached copies
Does NOT affect iCloud-stored versions
iCloud has its own encryption (in transit and at rest)

iCloud encryption :

All iCloud data encrypted at rest (Apple-managed keys)
End-to-end encryption available for some data types (Advanced Data Protection)
File protection only affects local device

// ✅ CORRECT: Protection on iCloud file affects local copy only func saveToICloud(data: Data, filename: String) throws { guard let iCloudURL = FileManager.default.url( forUbiquityContainerIdentifier: nil ) else { return }
```
let fileURL = iCloudURL.appendingPathComponent(filename)

// This protection applies to local cached copy
try data.write(to: fileURL, options: .completeFileProtection)

// iCloud has separate encryption for cloud storage
```
}

Common Patterns

Pattern 1: Default Protection for New Apps

// ✅ RECOMMENDED: Set default protection at app launch
func configureDefaultFileProtection() {
    let fileManager = FileManager.default

    let directories: [FileManager.SearchPathDirectory] = [
        .documentDirectory,
        .applicationSupportDirectory
    ]

    for directory in directories {
        guard let url = fileManager.urls(
            for: directory,
            in: .userDomainMask
        ).first else { continue }

        try? fileManager.setAttributes(
            [.protectionKey: FileProtectionType.completeUntilFirstUserAuthentication],
            ofItemAtPath: url.path
        )
    }
}

// Call during app initialization
func application(_ application: UIApplication, didFinishLaunchingWithOptions...) {
    configureDefaultFileProtection()
    return true
}

Pattern 2: Encrypting Database Files

// ✅ CORRECT: Protect SwiftData/SQLite database
let appSupportURL = FileManager.default.urls(
    for: .applicationSupportDirectory,
    in: .userDomainMask
)[0]

let databaseURL = appSupportURL.appendingPathComponent("app.sqlite")

// Set protection before creating database
try? FileManager.default.setAttributes(
    [.protectionKey: FileProtectionType.completeUntilFirstUserAuthentication],
    ofItemAtPath: appSupportURL.path
)

// Now create database - it inherits protection
let container = try ModelContainer(
    for: MyModel.self,
    configurations: ModelConfiguration(url: databaseURL)
)

Pattern 3: Downgrading Protection for Background Tasks

// ⚠️ SOMETIMES NECESSARY: Lower protection for background access
func enableBackgroundAccess(for url: URL) throws {
    try FileManager.default.setAttributes(
        [.protectionKey: FileProtectionType.completeUntilFirstUserAuthentication],
        ofItemAtPath: url.path
    )
}

// Only do this if:
// 1. Background access is truly required
// 2. Data sensitivity allows it
// 3. You've considered security tradeoffs

Debugging File Protection Issues

Issue: File Not Accessible in Background

Symptom : Background tasks fail to read files

// Debug: Check current protection
if let protection = try? FileManager.default.attributesOfItem(
    atPath: url.path
)[.protectionKey] as? FileProtectionType {
    print("Protection: \(protection)")
    if protection == .complete {
        print("❌ Can't access in background when locked")
    }
}

Solution : Use .completeUntilFirstUserAuthentication instead

Issue: Files Inaccessible After Restart

Symptom : App can't access files immediately after device reboot

Cause : Using .complete or .completeUntilFirstUserAuthentication (works as designed)

Solution : This is expected behavior. Either:

Wait for user to unlock device
Handle gracefully with appropriate UI
Use .none for files that must be accessible (security tradeoff)

Entitlements

File protection generally works without special entitlements, but some features require:

Data Protection Entitlement

<!-- Required for: .complete protection level -->
<key>com.apple.developer.default-data-protection</key>
<string>NSFileProtectionComplete</string>

When needed :

Using .complete protection
Some iOS versions for any protection (check documentation)

How to add :

Xcode → Target → Signing & Capabilities
"+ Capability" → Data Protection
Select protection level

Quick Reference Table

Scenario	Recommended Protection	Accessible When Locked?	Background Access?
User health data	`.complete`	❌ No	❌ No
Financial records	`.complete`	❌ No	❌ No
Most app data	`.completeUntilFirstUserAuthentication`	✅ Yes (after first unlock)	✅ Yes
Downloads (large files)	`.completeUnlessOpen`	✅ While open	✅ While open

Related Skills

axiom-storage — Decide when to use file protection vs other security measures
axiom-storage-management-ref — File lifecycle, purging, and disk management
axiom-storage-diag — Debug file access issues

Last Updated : 2025-12-12 Skill Type : Reference Minimum iOS : 4.0 (all protection levels) Latest Updates : iOS 26

Weekly Installs

Repository

charleswiltgen/axiom

GitHub Stars

590

First Seen

Jan 21, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode77

claude-code72

codex71

gemini-cli70

cursor68

github-copilot66

iOS 文件保护完全指南：数据加密、FileProtectionType 详解与安全存储实践

🇨🇳中文介绍

iOS 文件保护参考

何时使用此技能

概述

保护级别比较

相关 Skills

详细级别描述

.complete

.completeUnlessOpen

.completeUntilFirstUserAuthentication

.none

设置文件保护

在文件创建时

在现有文件上

目录的默认保护

检查当前保护

文件保护与 Keychain 对比

决策矩阵

代码比较

后台访问注意事项

iOS 后台模式与文件保护

处理保护错误

iCloud 与文件保护

保护如何与 iCloud 配合使用

常见模式

模式 1：新应用的默认保护

模式 2：加密数据库文件

模式 3：为后台任务降级保护

调试文件保护问题

问题：文件在后台不可访问

问题：重启后文件不可访问

权限

数据保护权限

快速参考表

相关技能

🇺🇸English

iOS File Protection Reference

When to Use This Skill

Overview

Protection Levels Comparison

Detailed Level Descriptions

.complete

.completeUnlessOpen

.completeUntilFirstUserAuthentication

.none

Setting File Protection

At File Creation

On Existing Files

Default Protection for Directory

Checking Current Protection

File Protection vs Keychain

Decision Matrix

Code Comparison

Background Access Considerations

iOS Background Modes and File Protection

Handling Protection Errors

iCloud and File Protection

How Protection Works with iCloud

Common Patterns

Pattern 1: Default Protection for New Apps

Pattern 2: Encrypting Database Files

Pattern 3: Downgrading Protection for Background Tasks

Debugging File Protection Issues

Issue: File Not Accessible in Background

Issue: Files Inaccessible After Restart

Entitlements

Data Protection Entitlement

Quick Reference Table

Related Skills

最新 Skills