🗝️ swift-openssl

Swift package providing OpenSSL cryptographic functionality with C bindings from OpenSSL.

Objectives

• Provide modern Swift bindings for OpenSSL
• Offer Swift Crypto-compatible API design
• Expose libcrypto and libssl bindings for full control of the implementation
• Ensure availability for Linux and Apple platform ecosystems
• Maintain automatic updates for Swift and OpenSSL versions

Requirements

• Swift 6.0+
• macOS 13+, iOS 16+, tvOS 16+, watchOS 9+, visionOS 1+

Installation

Warning

These APIs are not considered stable and may change with any update. Specify a version using exact: to avoid breaking changes.

Using Xcode

1. Go to File > Add Packages...
2. Enter the package URL: https://github.com/21-DOT-DEV/swift-openssl
3. Select the desired version

Using Package.swift

Add to your Package.swift:

dependencies: [
    .package(url: "https://github.com/21-DOT-DEV/swift-openssl.git", from: "0.1.0")
]

Usage

Caution

This package has not yet implemented cryptographic test vectors. Do not use in production until proper verification is in place.

SHA256 Hashing

import OpenSSL

// Hash data
let data = "Hello, World!".data(using: .utf8)!
let digest = OpenSSL.SHA.sha256(data: data)
print(digest.hexString)

// Hash string directly
let stringDigest = OpenSSL.SHA.sha256(string: "Hello, World!")
print(stringDigest.hexString)

Base64URL Encoding

import OpenSSL

// Encode data as base64url (useful for JWT)
let data = "Hello, World!".data(using: .utf8)!
let encoded = OpenSSL.Base64URL.encode(data)
print(encoded)

// Decode base64url string
if let decoded = OpenSSL.Base64URL.decode(encoded) {
    print(String(data: decoded, encoding: .utf8)!)
}

RSA Key Parsing

import OpenSSL

let privateKeyPEM = """
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----
"""

// Parse PEM-encoded keys
let privateKey = try OpenSSL.RSA.PrivateKey(pemRepresentation: privateKeyPEM)
print(privateKey.pemData)

Note: RSA signing and verification require the OpenSSL provider layer, which is not yet included. Key parsing is functional.

OpenSSL Version

import OpenSSL

// Get the OpenSSL version string
print(OpenSSL.SSL.versionString)

Development

Updating OpenSSL Version

1. Update the subtree to the new version:

   swift package --allow-writing-to-package-directory subtree pull --name openssl --branch openssl-X.Y.Z

2. Regenerate Configure-generated files (see below)

3. Re-extract sources:

   swift package --allow-writing-to-package-directory subtree extract --clean --all
   swift package --allow-writing-to-package-directory subtree extract --all

4. Copy generated files and verify build

Regenerating Configure-Generated Files

Some OpenSSL headers are generated by the Configure script. These files are committed to the repository and only need regeneration when updating OpenSSL versions.

Generated files:

• include/openssl/configuration.h - Build configuration and OPENSSL_NO_* defines
• crypto/buildinf.h - Build information (compiler, date, platform)
• providers/fips/include/fips/fipsindicator.h - FIPS indicator macros

Regeneration steps:

# Navigate to vendored OpenSSL
cd Vendor/openssl

# Run Configure with disabled algorithms (no-asm for portability)
./Configure darwin64-arm64-cc no-asm no-shared no-apps no-docs no-tests \
    no-rc5 no-rc2 no-idea no-bf no-cast no-seed no-camellia \
    no-mdc2 no-whirlpool no-md2 no-md4 \
    no-sm2 no-sm3 no-sm4 no-aria no-gost no-blake2 \
    no-lms no-ml-dsa no-ml-kem no-slh-dsa \
    no-ec_nistp_64_gcc_128 no-padlockeng

# Generate all required files
make build_all_generated

# Extract sources (includes configuration.h and other generated files)
cd ../..
swift package --allow-writing-to-package-directory subtree extract --name openssl

# Clean up Vendor directory (required - do not commit generated files to Vendor/)
cd Vendor/openssl
make distclean

Disabled algorithms:

Category	Algorithms	Rationale
Legacy ciphers	RC5, RC2, IDEA, BF, CAST, SEED, Camellia	Deprecated, rarely used
Legacy hashes	MDC2, Whirlpool, MD2, MD4, Blake2	Deprecated or specialized
Regional standards	SM2, SM3, SM4, ARIA, GOST	Chinese/Korean/Russian standards
Post-quantum	LMS, ML-DSA, ML-KEM, SLH-DSA	Experimental, increases binary size
Platform-specific	ec-nistp-64-gcc-128, padlockeng	Requires specific compiler/hardware

Important: Always run make distclean after extraction. Generated files must NOT be committed to Vendor/openssl/ as they will conflict with subtree operations.

Note: The buildinf.h file contains build-time information (compiler flags, build date). Since this is for informational purposes only, generating once for a canonical platform is sufficient.

Project Structure

Sources/
├── OpenSSL/           # Swift wrapper API
├── libcrypto/         # OpenSSL crypto library (extracted + generated)
│   ├── crypto/        # Core crypto sources
│   ├── include/       # Public headers (openssl/*.h)
│   ├── internal_include/  # Internal headers (crypto/*.h, internal/*.h)
│   └── providers/     # Provider headers
└── libssl/            # OpenSSL SSL/TLS library (extracted)
    ├── src/           # SSL sources
    └── include/       # SSL headers

License

MIT License - see LICENSE for details.

OpenSSL is licensed under the Apache License 2.0.