Enumerations

Enum representing the different HMAC algorithms supported for OATH credential generation.

OATH algorithms use HMAC (Hash-based Message Authentication Code) with different hash functions to generate one-time passwords. The choice of algorithm affects both security strength and computational requirements.

Algorithm Comparison

Algorithm	Security	Performance	Digest Size	Recommendation
SHA-1	Legacy	Fastest	160 bits	Legacy support only
SHA-256	Strong	Moderate	256 bits	Industry standard
SHA-512	Strongest	Slowest	512 bits	High security needs

Standards Compliance

All algorithms implement the HMAC construction as defined in RFC 2104, and are compatible with RFC 4226 (HOTP) and RFC 6238 (TOTP) specifications.

See more

public enum OathAlgorithm : String, CaseIterable, Codable, Sendable

Enum representing the different types of OATH credentials.

OATH (Open Authentication) supports two main types of one-time password algorithms:

• TOTP (Time-based One-Time Password): Generates codes based on the current time
• HOTP (HMAC-based One-Time Password): Generates codes based on a counter value

Standards Compliance

Both algorithms are standardized in RFC specifications and widely supported by authentication systems and mobile authenticator applications.

• TOTP: Implements RFC 6238 (TOTP: Time-Based One-Time Password Algorithm)
• HOTP: Implements RFC 4226 (HOTP: An HMAC-Based One-Time Password Algorithm)

See more

public enum OathType : String, CaseIterable, Codable, Sendable

Errors that can occur during OATH operations.

OathError provides comprehensive error handling for all OATH-related operations, including credential management, URI parsing, code generation, and policy enforcement. Each error case includes detailed information to help developers diagnose and resolve issues.

Error Categories

• Credential Management: Errors related to storing, retrieving, and managing credentials
• URI Parsing: Errors that occur when parsing otpauth:// or mfauth:// URIs
• Authentication: Errors during OTP code generation and validation
• Policy: Errors related to policy enforcement and credential locking
• System: General system and initialization errors

Usage Examples

do {
    let credential = try await client.addCredentialFromUri(uri)
    let code = try await client.generateCode(credential.id)
} catch let error as OathError {
    switch error {
    case .invalidUri(let message):
        print("Invalid URI format: \(message)")
        // Show user-friendly error about QR code format
    case .credentialLocked(let id):
        print("Credential is locked: \(id)")
        // Prompt user for authentication or wait for unlock
    case .codeGenerationFailed(let message, let underlying):
        print("Code generation failed: \(message)")
        // Check device time or credential validity
    default:
        print("OATH error: \(error.localizedDescription)")
    }
}

Error Recovery

Many errors provide recovery suggestions through the recoverySuggestion property:

if let suggestion = error.recoverySuggestion {
    print("Suggestion: \(suggestion)")
}

See more

public enum OathError : LocalizedError, Sendable

Storage-specific errors for OATH operations.

OathStorageError handles errors that occur at the storage layer, including iOS Keychain operations, file system access, and data persistence issues. These errors are typically system-related and may require different handling than application-level OathError cases.

Common Scenarios

• Device Lock: Keychain access denied when device is locked
• Storage Full: Insufficient space for storing credentials
• Corruption: Data corruption in stored credentials
• Permissions: App permissions insufficient for storage access

Usage Examples

do {
    let credentials = try await storage.getAllOathCredentials()
} catch let error as OathStorageError {
    switch error {
    case .accessDenied(let message):
        // Device may be locked or permissions missing
        print("Storage access denied: \(message)")
    case .storageCorrupted(let message):
        // May need to clear and reinitialize storage
        print("Storage corrupted: \(message)")
    case .storageFailure(let message, let underlying):
        // General storage error with potential underlying cause
        print("Storage failure: \(message)")
        if let underlying = underlying {
            print("Underlying error: \(underlying)")
        }
    default:
        print("Storage error: \(error.localizedDescription)")
    }
}

See more

public enum OathStorageError : LocalizedError, Sendable