Persona

public class Persona

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)

Note

The persona is unique per device and application bundle identifier. If you create two personas with equal names on two different applications or devices, they cannot be used to decrypt secrets of one another. If a persona is removed and re-created with the same name, it cannot be used to decrypt values encrypted for the previous one.

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)

  • These errors indicate that erroneous keys where stored in the Keychain.

    See more

    Declaration

    Swift

    enum Error : Swift.Error
    Show on GitHub

  • Forget a persona. This will remove all secrets of this persona from the system’s Keychain.

    Warning

    Removing a persona will delete all secrets of that persona which also means, that encrypted messages or files encrypted for this persona cannot be decrypted anymore.

    Declaration

    Swift

    public static func forget(_ persona: Persona) throws

    Parameters

    persona

    The persona that should be deleted.
    Show on GitHub

  • The unique name of the persona.

    Declaration

    Swift

    public let uniqueName: String
    Show on GitHub

  • Create a new persona. If the persona was created before, the secrets will be retrieved from the system’s Keychain.

    Declaration

    Swift

    public init(uniqueName: String)

    Parameters

    uniqueName

    A name that is unique for that persona.
    Show on GitHub

  • Helper function to store key material in the system’s Keychain for this persona.

    Declaration

    Swift

    private func secret<Key>(for type: KeyType, defaultInitializer: () -> Key, capturingInitializer: (_ bytes: inout Bytes) -> Key?) throws -> Key where Key : KeyMaterial

    Parameters

    type

    The type of the key.
    defaultInitializer

    A default initializer used for new keys.
    capturingInitializer

    An initializer that takes a byte array.
    bytes

    The raw bytes of the key.

    Return Value

    The key for the item. A new key, if the item did not exist, the existing key else and nil if there was an error.

    Show on GitHub

  • This updates or creates a Keychain entry containing the key material.

    Warning

    This will overwrite an existing entry and might destroy a secret forever.

    Throws

    A Keychain.Error if they entry cannot be created or updated in the Keychain.

    Declaration

    Swift

    private func setSecret<Key>(key: Key, for type: KeyType) throws where Key : KeyMaterial

    Parameters

    key

    The new key that should be stored in the Keychain.
    type

    The type of the key.
    Show on GitHub

  • The master key of the persona, which can be used to derive other keys.

    Declaration

    Swift

    public func masterKey() throws -> MasterKey

    Return Value

    The master key.

    Show on GitHub

  • The secret key of the persona that can be used with SecretBox.

    Declaration

    Swift

    public func secretKey() throws -> SecretBox.SecretKey

    Return Value

    The secret key.

    Show on GitHub

  • The key of the persona that can be used with GenericHash.

    Declaration

    Swift

    public func genericHashKey() throws -> GenericHash.Key

    Return Value

    The key.

    Show on GitHub

  • Explicitly set the master key for the persona.

    Warning

    This will overwrite the master key that was previously assigned to this persona. This is irreversible and previously derived keys cannot be derived again. Data encrypted with derived keys cannot be decrypted unless the keys where persisted otherwise.

    Throws

    A Keychain.Error if they entry cannot be created or updated in the Keychain.

    Declaration

    Swift

    public func setMasterKey(_ masterKey: MasterKey) throws

    Parameters

    masterKey

    The new master key.
    Show on GitHub

  • Explicitly set the secret key for the persona.

    Warning

    This will overwrite the secret key that was previously assigned to this persona. This is irreversible. Data encrypted with the secret key cannot be decrypted unless it was persisted otherwise.

    Throws

    A Keychain.Error if they entry cannot be created or updated in the Keychain.

    Declaration

    Swift

    public func setSecretKey(_ secretKey: SecretBox.SecretKey) throws

    Parameters

    secretKey

    The new secret key.
    Show on GitHub

  • Explicitly set the generic hash key for the persona.

    Warning

    This will overwrite the generic hash key that was previously assigned to this persona. This is irreversible and previously hashed values cannot be derived again unless the key was persisted otherwise.

    Throws

    A Keychain.Error if they entry cannot be created or updated in the Keychain.

    Declaration

    Swift

    public func setGenericHashKey(_ genericHashKey: GenericHash.Key) throws

    Parameters

    genericHashKey

    The new generic hash key.
    Show on GitHub

  • This is used to identify the type of the key.

    See more

    Declaration

    Swift

    public enum KeyType : String
    Show on GitHub

  • This is the bundle identifier of the application. It is used to identify the service of the password item in the system’s Keychain.

    Declaration

    Swift

    private var bundleIdentifier: String { get }
    Show on GitHub

  • This constructs an identifier for the service and type of key.

    Declaration

    Swift

    private func itemService(type: KeyType) -> String

    Parameters

    type

    The type of the key.

    Return Value

    The identifier.

    Show on GitHub

  • This identifies the Keychain entry for the given key type.

    Declaration

    Swift

    public func keychainItem(for type: KeyType) -> GenericPasswordItem
    Show on GitHub

  • This is an array that holds all Keychain entries for this persona.

    Declaration

    Swift

    private var keychainItems: [KeychainItem] { get }
    Show on GitHub