Skip to main content

runtime

Package runtime is the Go API of the Drift secure storage plugin (github.com/go-drift/drift/plugins/securestorage/plugin in drift.yaml): string values encrypted at rest, optionally behind biometric authentication.

import securestorage "github.com/go-drift/drift/plugins/securestorage/runtime"

go func() {
    err := securestorage.Set(ctx, "token", token, nil)
    ...
    token, found, err := securestorage.Get(ctx, "token", nil)
}()

Every call waits for the platform (the keychain, a biometric prompt), so call them from a goroutine: from the UI thread they fail with platform.ErrBlocksUIThread.

Biometric protection guards reading a value; writing and deleting one never prompt. On iOS it is enforced by the Keychain (the item's access control); on Android by the plugin, before it decrypts the value (BiometricPrompt without a CryptoObject), so it guards against another person using the unlocked device, not against code running as the app.

On Android, values do not survive a backup restore or device transfer: a restored store opens empty (see the plugin package's Backup and restore), so keep what it holds recoverable.

Variables​

var (
    // ErrAuthFailed indicates biometric authentication failed.
    ErrAuthFailed = errors.New("biometric authentication failed")
    // ErrAuthCanceled indicates the user canceled biometric authentication.
    ErrAuthCanceled = errors.New("biometric authentication canceled")
    // ErrBiometricsUnavailable indicates the device cannot do biometric
    // authentication (no hardware, or none enrolled).
    ErrBiometricsUnavailable = errors.New("biometric authentication unavailable")
    // ErrBiometricsNotConfigured indicates RequireBiometric without the
    // plugin's biometrics: config.
    ErrBiometricsNotConfigured = errors.New("biometric protection needs the securestorage plugin's biometrics: config")
    // ErrLocked indicates the value cannot be read while the device is
    // locked (its Accessibility).
    ErrLocked = errors.New("secure storage is locked until the device is unlocked")
    // ErrNoActivity indicates a biometric prompt with no screen to show it
    // over (Android).
    ErrNoActivity = errors.New("no screen to show the biometric prompt over")
)

func Contains​

func Contains(ctx context.Context, key string, opts *Options) (bool, error)

Contains reports whether there is a value under key, without reading it (no prompt).

func Delete​

func Delete(ctx context.Context, key string, opts *Options) error

Delete removes the value under key, if any.

func DeleteAll​

func DeleteAll(ctx context.Context, opts *Options) error

DeleteAll removes every value.

func Get​

func Get(ctx context.Context, key string, opts *Options) (value string, found bool, err error)

Get returns the value under key, and whether there is one. A value stored with RequireBiometric prompts for biometric authentication first.

func Keys​

func Keys(ctx context.Context, opts *Options) ([]string, error)

Keys returns the keys that have values.

func Set​

func Set(ctx context.Context, key, value string, opts *Options) error

Set stores value under key, replacing any value there.

type Accessibility​

Accessibility is when a value can be read (iOS; Android values are readable whenever the app runs).

type Accessibility string
const (
    // WhenUnlocked: only while the device is unlocked. The default.
    WhenUnlocked Accessibility = "when_unlocked"
    // AfterFirstUnlock: after the first unlock since boot, also while
    // locked (for background work).
    AfterFirstUnlock Accessibility = "after_first_unlock"
    // WhenUnlockedThisDeviceOnly is WhenUnlocked, excluded from backups.
    WhenUnlockedThisDeviceOnly Accessibility = "when_unlocked_this_device_only"
    // AfterFirstUnlockThisDeviceOnly is AfterFirstUnlock, excluded from
    // backups.
    AfterFirstUnlockThisDeviceOnly Accessibility = "after_first_unlock_this_device_only"
)

type Biometric​

Biometric is the kind of biometric authentication the device offers.

type Biometric string
const (
    // BiometricNone: none available, or none enrolled.
    BiometricNone Biometric = "none"
    // BiometricFaceID, BiometricTouchID and BiometricOpticID are iOS's.
    BiometricFaceID  Biometric = "face_id"
    BiometricTouchID Biometric = "touch_id"
    BiometricOpticID Biometric = "optic_id"
    // BiometricFingerprint and BiometricFace are Android's strong
    // biometrics.
    BiometricFingerprint Biometric = "fingerprint"
    BiometricFace        Biometric = "face"
)

func AvailableBiometric​

func AvailableBiometric(ctx context.Context) (Biometric, error)

AvailableBiometric returns the biometric authentication the device offers, BiometricNone if it has none enrolled.

type Options​

Options configures a call. A nil *Options uses the defaults.

type Options struct {
    // Service namespaces the keys. Empty uses the app's default namespace.
    Service string
    // Accessibility is when Set's value can be read (iOS).
    Accessibility Accessibility
    // RequireBiometric makes Set's value readable only after biometric
    // authentication. Needs the plugin's biometrics: config.
    RequireBiometric bool
    // BiometricPrompt is the message Get shows when the value needs
    // biometric authentication.
    BiometricPrompt string
}

Generated by gomarkdoc