Classes

This class can be used to generate hash arbitrary data. Keyed hashing is supported.

Examples

Public Hashing

let data = "Hello, World!".utf8Bytes
let hash = GenericHash(bytes: data)

Private Hashing with Persisted Keys

// Create a persona
let alice = Persona(uniqueName: "Alice")

// Generate a personalized hash for that persona
let data = "Hello, World!".utf8Bytes
let hash = GenericHash(bytes: data, for: alice)

// Forget the persona and remove all related Keychain entries
try! Persona.forget(alice)

A class that can be used for exchanging keys between two parties on an adverserial channel.

Example

let alice = KeyExchange(side: .client)
let bob = KeyExchange(side: .server)

let alicesSessionKey = alice.sessionKey(for: bob.publicKey)
let bobsSessionKey = bob.sessionKey(for: alice.publicKey)

// alicesSessionKey == bobsSessionKey

This class can be used to securely store key material in memory.

A master key can be used to derive keys for other purposes.

Examples

let context = MasterKey.Context("Examples")!
let masterKey = MasterKey()
let subKey1 = masterKey.derive(sizeInBytes: MasterKey.DerivedKey.MinimumSizeInBytes, with: 0, and: context)!
let subKey2 = masterKey.derive(sizeInBytes: MasterKey.DerivedKey.MinimumSizeInBytes, with: 1, and: context)!

// You can also derive a key in order to use it with secret boxes
let secretBox = SecretBox(secretKey: masterKey.derive(with: 0, and: context))

This class is used to securely store values in memory.

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.
}

A persona is an entity for which you are in posession of the secrets. The secrets are persisted in the system’s Keychain. A persona has a unique name.

The Keychain items are prefixed by the application’s bundle identifier and suffixed with a value determining the type of secret stored.

The actual value of the secret is Base64 encoded to allow users accessing the value from the Keychain Access application (macOS)

Examples

// Create a persona
let alice = Persona(uniqueName: "Alice")

// Once a secret of that persona is used, it will be persisted in the
// system's Keychain.
let secretBox = SecretBox(persona: alice)!

// Use your SecretBox as usual
let plaintext = "Hello, World!".utf8Bytes
let ciphertext = secretBox.encrypt(plaintext: plaintext)
let decrypted = secretBox.decrypt(ciphertext: ciphertext)!

// Forget the persona and remove all related Keychain entries
try! Persona.forget(alice)

This class can be used to encrypt/decrypt data based on a shared secret (symmetric key).

Example

Ephemeral Keys

An ephemeral key is destroyed once the SecretBox is destroyed. There is no way to recover it unless otherwise persisted. This can be used for keys that should only reside in memory, e.g., if they were shared between multiple parties.

let secretBox = SecretBox()
let plaintext = "Hello, World!".utf8Bytes
let ciphertext = secretBox.encrypt(plaintext: plaintext)
let decrypted = secretBox.decrypt(ciphertext: ciphertext)!

Persisted Keys

Persisted keys will be stored in and loaded from the system’s Keychain automatically. This is useful for encrypting data for oneself, e.g., if you want to store encrypted files in a public document storage, such as Dropbox.

// Create a persona
let alice = Persona(uniqueName: "Alice")

// Once a secret of that persona is used, it will be persisted in the
// system's Keychain.
let secretBox = SecretBox(persona: alice)!

// Use your SecretBox as usual
let plaintext = "Hello, World!".utf8Bytes
let ciphertext = secretBox.encrypt(plaintext: plaintext)
let decrypted = secretBox.decrypt(ciphertext: ciphertext)!

// Forget the persona and remove all related Keychain entries
try! Persona.forget(alice)

Padding

If you add padding to your messages, the original size of the message is not disclosed in the ciphertext. The ciphertext size will be a multiple of the block size.

let secretBox = SecretBox()
let plaintext = "Hello, World!".utf8Bytes
let padding: Padding = .padded(blockSize: 16)
let ciphertext = secretBox.encrypt(plaintext: plaintext, padding: padding)
let decrypted = secretBox.decrypt(ciphertext: ciphertext, padding: padding)!