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)
-
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.
-
The unique name of the persona.
Declaration
Swift
public let uniqueName: String
-
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.
-
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.
-
The key of the persona that can be used with
GenericHash
.Declaration
Swift
public func genericHashKey() throws -> GenericHash.Key
Return Value
The key.
-
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.
-
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.
-
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.
-
This is used to identify the type of the key.
See moreDeclaration
Swift
public enum KeyType : String
-
This identifies the Keychain entry for the given key type.
Declaration
Swift
public func keychainItem(for type: KeyType) -> GenericPasswordItem