A lightweight authentication library for Swift providing common authentication operations, such as password hashing and OTP verification and generation.

Installation

Add the Authentication package to your Package.swift dependencies:

dependencies: [
    .package(url: "https://github.com/vapor/authentication.git", from: "3.0.0")
]

Then add Authentication to your target's dependencies:

targets: [
    .target(
        name: "YourTarget",
        dependencies: [
            .product(name: "Authentication", package: "authentication")
        ]
    )
]

Password Hashing

Securely hash and verify user passwords using the bcrypt algorithm, the PasswordHasher protocol or the PBKDF2 algorithm:

import Authentication

// Create a hasher with default cost (12)
let hasher = BcryptHasher()
// Or use PBKDF2
let hasher = PBKDF2Hasher()
// Or a hasher injected in
let hasher: PasswordHasher

// Hash a password
let hash = try hasher.hash("secretPassword123")

// Verify a password against a hash
let isValid = try hasher.verify("secretPassword123", created: hash)
// isValid == true

Configuration

Bcrypt

The cost parameter controls how computationally expensive the hashing operation is. Higher costs provide more security but take longer to compute:

// Create a bcrypt hasher with custom cost (valid range: 4-31)
let hasher = BcryptHasher(cost: 14)

let hash = try hasher.hash("myPassword")

Note: Increasing the cost by 1 doubles the computation time. A cost of 12 takes approximately 250ms on modern hardware.

PBKDF2

In PBKDF2 you can configure the number of iterations and hashing function. There are sensible standards in place already depending on the hash algorithm used, so only adjust the iterations if necessary:

// Create a PBKDF2 hasher with custom iterations
let hasher = PBKDF2Hasher(
    pseudoRandomFunction: .sha256,
    iterations: 600_000,
)
let hash = try hasher.hash("myPassword")

One-Time Passwords (OTP)

Generate RFC-compliant HOTP and TOTP codes for multi-factor authentication.

Time-Based One-Time Passwords (TOTP)

TOTP generates codes that change at regular intervals (typically 30 seconds):

import Authentication
import Crypto

// Create a symmetric key (store this securely per user)
let key = SymmetricKey(size: .bits256)

// Create a TOTP generator
let totp = TOTP(key: key, digest: .sha256)

// Generate a code for the current time
let code = totp.generate(time: Date())
print(code)  // e.g., "482719"

Hash-Based One-Time Passwords (HOTP)

HOTP generates codes based on a counter value:

import Authentication
import Crypto

let key = SymmetricKey(size: .bits256)

// Create an HOTP generator
let hotp = HOTP(key: key, digest: .sha256)

// Generate codes for sequential counters
let code0 = hotp.generate(counter: 0)
let code1 = hotp.generate(counter: 1)

Configuring OTP Parameters

Both HOTP and TOTP support configuration options:

// Configure digest algorithm: .sha1, .sha256, or .sha512
let totp = TOTP(key: key, digest: .sha512)

// Configure code length: .six, .seven, or .eight digits
let totp = TOTP(key: key, digest: .sha256, digits: .eight)

// Configure time interval (TOTP only, default: 30 seconds)
let totp = TOTP(key: key, digest: .sha256, interval: 60)

Verifying Codes with Range Tolerance

To account for clock drift or user delays, generate multiple codes within a range:

let totp = TOTP(key: key, digest: .sha256)

// Generate codes for current time plus/minus 1 interval
let codes = totp.generate(time: Date(), range: 1)
// Returns 3 codes: [previous, current, next]

// Check if user's code matches any valid code
let isValid = codes.contains(userCode)