Skip to content

lachlanbell/SwiftOTP

Repository files navigation

Logo SwiftOTP

Build Status Version Carthage compatible License Platform Swift Version

SwiftOTP is a Swift library for generating One Time Passwords (OTP) commonly used for two factor authentication. SwiftOTP supports both HMAC-Based One Time Passwords (HOTP) and Time Based One Time Passwords (TOTP) defined in RFC 4226 and RFC 6238 respectively.

Installation

CocoaPods

SwiftOTP is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod 'SwiftOTP'

Then run pod install in the project directory to install.

Carthage

SwiftOTP is available through Carthage. To install it, simply add the following line to your Cartfile:

github "lachlanbell/SwiftOTP"

Then run carthage update in the project directory and add the resulting frameworks to your project.

Swift Package Manager

You can use Swift Package Manager and specify dependency in Package.swift by adding this:

dependencies: [
    .package(url: "https://github.com/lachlanbell/SwiftOTP.git", .upToNextMinor(from: "3.0.0"))
]

Usage

TOTP (Time-Based One Time Password)

Creation of a TOTP Object:

let totp = TOTP(secret: data)

A TOTP Object can be created with the default settings (6 digits, 30sec time interval and using HMAC-SHA-1) as shown above, or the individual parameters can be set as shown below:

let totp = TOTP(secret: data, digits: 6, timeInterval: 30, algorithm: .sha1)

Generating TOTP Passwords

After creating a TOTP object, a password can be generated for a point in time, either by using a Date object or a Unix time value using the generate() function

For example, to get a password for the current time using a TOTP object named totp:

if let totp = TOTP(secret: data) {
    let otpString = totp.generate(time: Date)
}

Or from Unix time (i.e. seconds elapsed since 01 Jan 1970 00:00 UTC):

if let totp = TOTP(secret: data) {
    let otpString = totp.generate(secondsPast1970: 1234567890)
}

Note: only Int values are accepted by this function, and must be positive.

HOTP (HMAC-Based One Time Password (counter-based))

In addition to TOTP, SwiftOTP also supports the generation of counter-based HOTP passwords.

Creation of an HOTP Object:

let hotp = HOTP(secret: data)

A HOTP Object can be created with the default settings (6 digits, using HMAC-SHA-1) as shown above, or the individual parameters can be set as shown below:

let hotp = HOTP(secret: data, digits: 6, algorithm: .sha1)

Generating HOTP Passwords

After creating a HOTP object, a password can be generated for a counter value (UInt64) by using the generate() function, for example (where hotp is a HOTP object):

if let hotp = HOTP(secret: data) {
    let otpString = hotp.generate(counter: 42)
}

Base32

Most secret keys for generating one time passwords use Base32 encoding. As such, SwiftOTP includes a Base32 Helper to decode a Base32 string to Data.

For example:

base32DecodeToData("ABCDEFGHIJKLMNOP")!

Or in use:

guard let data = base32DecodeToData("ABCDEFGHIJKLMNOP") else { return }

if let hotp = HOTP(secret: data) {
    print(hotp.generate(42))
}

Supported parameters

Hash Functions

SwiftOTP supports HMAC with SHA1 as specified in RFC 4226, as well as SHA256 and SHA512 added in RFC 6238. MD5 is not supported, due to its insufficient hash length.

Digit Length

Both the TOTP and HOTP objects only accept a digit length value between 6 and 8, as specified in RFC 4226. Both objects will be nil if an invalid digit length value is provided.

Older Swift Versions

Use the corresponding branch for using an older Swift version (4.0 and greater). For example:

pod 'SwiftOTP', :git => 'https://github.com/lachlanbell/SwiftOTP.git', :branch => 'swift-4.0'

License

SwiftOTP is available under the MIT license. See the LICENSE file for more info.

Acknowledgements

SwiftOTP depends on the following open-source projects:

Some parts of the password generator code were adapted from the old Google Authenticator source.