SecretBox

public class SecretBox

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)!

  • A class for secret keys that can be used by the SecretBox.

    See more

    Declaration

    Swift

    public class SecretKey : KeyMaterial
    Show on GitHub

  • This class represents a nonce (number used once) that is required for indeterministically encrypting a given message.

    See more

    Declaration

    Swift

    public class Nonce : KeyMaterial
    Show on GitHub

  • This class represents a message authentication code to verify the integrity of encrypted messages.

    See more

    Declaration

    Swift

    public class AuthenticationCode : KeyMaterial
    Show on GitHub

  • This class represents an authenticated ciphertext, which is an encrypted message including the nonce used for indeterministic encryption and a message authentication code for verifying the integrity of the encrypted message.

    See more

    Declaration

    Swift

    public struct AuthenticatedCiphertext : EncryptedData
    Show on GitHub

  • Initializes a secret box with a given secret key.

    Declaration

    Swift

    public init(secretKey: SecretKey)

    Parameters

    secretKey

    The secret key.
    Show on GitHub

  • Initializes a secret box for a given persona. This automatically loads secret key for that persona from the system’s Keychain.

    Declaration

    Swift

    public convenience init?(persona: Persona)

    Parameters

    persona

    The persona to which the secret key belongs.
    Show on GitHub

  • Initializes a secret box with an ephemeral key. The key cannot be accessed and will be irrevocably destroyed once the secret box object is deleted. Encrypted messages can than no longer be decrypted.

    Declaration

    Swift

    public convenience init()
    Show on GitHub

  • Encrypts a message.

    The message can be decrypted by using decrypt(authenticatedCiphertext:)

    Note

    This function should only be used if you are required to use a specific nonce. Usually encrypt(plaintext:) should be preferred.

    Warning

    If you specify a padding, you need to specify the same padding when decrypting.

    Declaration

    Swift

    public func encrypt(plaintext: Bytes, padding: Padding = .none, with nonce: Nonce = Nonce()) -> AuthenticatedCiphertext

    Parameters

    plaintext

    The message that should be encrypted.
    padding

    A padding, which should be applied to the plaintext.
    nonce

    A nonce (number used once).

    Return Value

    An authenticated ciphertext containing the encrypted message.

    Show on GitHub

  • Encrypt padded plaintext blocks.

    The message can be decrypted by using decrypt(authenticatedCiphertext:)

    Note

    This function should only be used if you are required to use a specific nonce. Usually encrypt(plaintext:) should be preferred.

    Warning

    You need to specify the same padding for decryption, i.e., by specifying the block size.

    Declaration

    Swift

    public func encrypt(plaintext: Blocks, with nonce: Nonce = Nonce()) -> AuthenticatedCiphertext

    Parameters

    plaintext

    The padded message that should be encrypted.
    nonce

    A nonce (number used once).

    Return Value

    An authenticated ciphertext containing the encrypted message.

    Show on GitHub

  • Decrypts an encrypted message.

    A message can be encrypted by using encrypt(plaintext:).

    Declaration

    Swift

    public func decrypt(ciphertext authenticatedCiphertext: AuthenticatedCiphertext, padding: Padding = .none) -> Bytes?

    Parameters

    authenticatedCiphertext

    The authenticated ciphertext of the encrypted message.
    padding

    The padding used for encrypting the message.

    Return Value

    The decrypted message, nil if the authentication code is invalid or the message has invalid padding.

    Show on GitHub