https://github.com/vapor/authentication
👤 Lightweight authentication framework for Swift
https://github.com/vapor/authentication
authentication authorization fluent server-side-swift swift-linux vapor vapor-service
Last synced: 9 days ago
JSON representation
👤 Lightweight authentication framework for Swift
- Host: GitHub
- URL: https://github.com/vapor/authentication
- Owner: vapor
- License: mit
- Created: 2017-02-15T14:59:00.000Z (almost 9 years ago)
- Default Branch: main
- Last Pushed: 2025-12-30T16:37:42.000Z (23 days ago)
- Last Synced: 2026-01-03T10:49:10.867Z (19 days ago)
- Topics: authentication, authorization, fluent, server-side-swift, swift-linux, vapor, vapor-service
- Language: C
- Homepage:
- Size: 166 KB
- Stars: 54
- Watchers: 18
- Forks: 33
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
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:
```swift
dependencies: [
.package(url: "https://github.com/vapor/authentication.git", from: "3.0.0")
]
```
Then add `Authentication` to your target's dependencies:
```swift
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:
```swift
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:
```swift
// 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:
```swift
// 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):
```swift
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:
```swift
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:
```swift
// 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:
```swift
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)
```