Password

public class Password

This class can be used to securely handle passwords. Passwords will be copied to a secure memory location, comparison will be performed in constant time to avoid timing attacks and a method for hashing passwords is provided to store them for user authentication purposes.

Examples

let password = Password("Correct Horse Battery Staple")!
let hashedPassword = password.hash()!

// Store `hashedPassword.string` to database.

// If a user wants to authenticate, just read it from the database and
// verify it against the password given by the user.
if hashedPassword.isVerified(by: password) {
    // The user is authenticated successfully.
}

  • Defines how much CPU load will be required for hashing a password. This reduces the speed of brute-force attacks. You might be required to chose high or medium if your device does not have much CPU power.

    See

    Guidelines for choosing the parameters
    See more

    Declaration

    Swift

    public enum ComplexityLimit
    Show on GitHub

  • Defines how much memory will be required for hashing a password. This makes brute-forcing more costly. The speed requirements induced by increased CPU load can be reduced by massively parallelizing the attack using FPGAs. As these have limited memory, this factor mitigates those attacks. You might be required to chose high or medium if your device is not equipped with much memory.

    See

    Guidelines for choosing the parameters
    See more

    Declaration

    Swift

    public enum MemoryLimit
    Show on GitHub

  • A salt should be applied to passwords prior to hashing in order to prevent dictionary attacks. This class represents such a salt.

    See more

    Declaration

    Swift

    public struct Salt
    Show on GitHub

  • A key that is derived from a Password.

    A derived key contains additional information, i.e., the parameters used to derive the key. In order to derive the same key from the password, the same parameters have to be used.

    See more

    Declaration

    Swift

    public class DerivedKey : KeyMaterial
    Show on GitHub

  • The password bytes in secure memory.

    Declaration

    Swift

    let bytes: KeyMaterial
    Show on GitHub

  • The password size in bytes.

    Declaration

    Swift

    var sizeInBytes: UInt32 { get }
    Show on GitHub

  • Initializes a password from a given string with a given encoding.

    Declaration

    Swift

    public init?(_ password: String, using encoding: String.Encoding = .utf8)

    Parameters

    password

    The password string, e.g., as entered by the user.
    encoding

    The encoding of the password string.
    Show on GitHub

  • Hashes a password for securely storing it on disk or in a database for the purpose of authenticating a user.

    Warning

    Do not change the complexity limits unless it is required, due to device limits or negative performance impact. Please refer to the Guidelines for choosing the parameters.

    See

    HashedPassword

    Declaration

    Swift

    public func hash(complexity: ComplexityLimit = .high, memory: MemoryLimit = .high) -> HashedPassword?

    Parameters

    complexity

    The CPU load required.
    memory

    The amount of memory required.

    Return Value

    The hashed password, nil if something went wrong.

    Show on GitHub

  • Checks if this password authenticates a hashed password.

    See

    HashedPassword.isVerified(by:)

    Declaration

    Swift

    public func verifies(_ hashedPassword: HashedPassword) -> Bool

    Parameters

    hashedPassword

    The hashed password.

    Return Value

    true if this password authenticates the hashed password.

    Show on GitHub

  • Derive a cryptographic key for a given password.

    Declaration

    Swift

    public func derive(sizeInBytes: UInt32, complexity: ComplexityLimit = .high, memory: MemoryLimit = .high, salt: Salt = Salt()) -> DerivedKey?

    Parameters

    sizeInBytes

    The size of the derived key in bytes.
    salt

    The salt that will be used for deriving the key.
    complexityLimit

    The complexity limit that will be used for deriving the key.
    memoryLimit

    The memory limit that will be used for deriving the key.
    Show on GitHub

  • Compares two passwords in constant time regardless of their length. This is done by calculating a hash (in sense of a fingerprint not in sense of a hashed password used for storage) on the password and comparing the hash values (which are of equal length) in constant time.

    Declaration

    Swift

    public static func == (lhs: Password, rhs: Password) -> Bool

    Parameters

    lhs

    A password.
    rhs

    Another password.

    Return Value

    true if the passwords are equal.

    Show on GitHub