Swift Confidential

Swift Confidential uses caseless enums to encapsulate generated secrets. You can either create a new namespace or extend an existing one using specific YAML syntax.

Creating a new namespace: Use create <name>. Example: create ObfuscatedLiterals results in internal enum ObfuscatedLiterals { ... }.

Extending an existing namespace: Use extend <name> [from <module>]. Example: extend Pinning from Crypto results in extension Crypto.Pinning { ... }.

Note: Nested namespace creation is currently not supported.

YAML Syntax Examples:

# Create new
create ObfuscatedLiterals

# Extend existing
extend Pinning from Crypto

Source Stability

Swift Confidential follows semantic versioning. Because the project is currently in major version 0, source stability is only guaranteed within minor versions (e.g., between 0.5.0 and 0.5.1). To prevent breaking updates, use a source control requirement in your Swift Package Manager dependency:

.upToNextMinor(from: "0.5.0")

Public vs. Experimental API

• Public API: Consists of non-underscored declarations marked public in the ConfidentialKit module.
• Experimental API: Denoted with a leading underscore (e.g., _experimentalMethod). These are subject to change in any release, including patch releases.

To add Swift Confidential to an Xcode project:

1. Select File > Add Package Dependencies....
2. Enter https://github.com/securevale/swift-confidential.git in the Search or Enter Package URL field.
3. Set the Dependency Rule to Up to Next Minor Version.
4. Click Add Package.
5. Select your target and choose the ConfidentialKit package product, then click Add Package.

To integrate Swift Confidential with an Xcode target:

1. Add swift-confidential and swift-confidential-plugin packages to your Xcode project via Swift Package Manager.
2. When adding products from the swift-confidential package, select the ConfidentialKit library.
3. In your target's Build Phases pane, locate the Run Build Tool Plug-ins section.
4. Click the + button, select the Confidential plugin, and click Add.

Note: You can add confidential.yml to your Xcode project for convenience, but do not add it to any of the Xcode targets.

To add Swift Confidential to a Swift Package Manager project, add the package dependency to your Package.swift and then add the ConfidentialKit product to your target.

// 1. Add the package dependency
.package(url: "https://github.com/securevale/swift-confidential.git", .upToNextMinor(from: "0.5.0"))

// 2. Add the ConfidentialKit library to your target
.product(name: "ConfidentialKit", package: "swift-confidential")

Experimental features (like using Swift macros instead of property wrappers) are only available when experimentalMode is enabled. This requires the Swift 6 toolchain (Xcode 16.0 or later).

To enable Experimental Mode:

1. Set experimentalMode: true in your confidential.yml.
2. Change your target dependency from ConfidentialKit to _ConfidentialKit (note the leading underscore).

Warning: Swift macros can increase build times, especially on CI/CD machines.

For unattended CI/CD environments, you can bypass macro and package plugin validations using one of the following two methods:

Method 1: xcodebuild flags

Pass these flags directly to your xcodebuild command:

• -skipMacroValidation
• -skipPackagePluginValidation

Method 2: Xcode defaults

Set these global defaults via the terminal:

• com.apple.dt.Xcode IDESkipMacroFingerprintValidation
• com.apple.dt.Xcode IDESkipPackagePluginFingerprintValidatation

xcodebuild -skipMacroValidation -skipPackagePluginValidation

# Or via defaults
defaults write com.apple.dt.Xcode IDESkipMacroFingerprintValidation -bool YES
defaults write com.apple.dt.Xcode IDESkipPackagePluginFingerprintValidatation -bool YES

Compression is a non-polymorphic technique (same input produces same output) used to reduce data size. Swift Confidential applies additional polymorphic routines to mask the compression algorithm's signature.

Use the following YAML syntax to apply compression:

compress using <#algorithm#>

Supported algorithms:

• lzfse: LZFSE compression algorithm.
• lz4: LZ4 compression algorithm.
• lzma: LZMA compression algorithm.
• zlib: zlib compression algorithm.

compress using lz4

Encryption is a polymorphic technique (same input produces different output each run) used to secure data.

Use the following YAML syntax to apply encryption:

encrypt using <#algorithm#>

Supported algorithms:

• aes-128-gcm: AES in GCM mode with 128-bit key.
• aes-192-gcm: AES in GCM mode with 192-bit key.
• aes-256-gcm: AES in GCM mode with 256-bit key.
• chacha20-poly: ChaCha20-Poly1305 algorithm.

encrypt using aes-256-gcm

Randomization is a polymorphic technique that shuffles data.

Warning: This technique is best suited for secrets $\le$ 256 bytes. For larger secrets, the output size grows significantly (from 2N to 3N, or up to 9N on 64-bit platforms for data $>65,536$ bytes).

Use the following YAML syntax to apply randomization:

shuffle