DOCSEARCHbyAlgolia
Submit Docs

age-plugin-se

repository·main·Indexed 42 days ago

https://github.com/remko/age-plugin-se

A plugin for the age encryption tool that enables the use of Apple's Secure Enclave for managing encryption identities, allowing users to protect encryption keys using biometrics like Touch ID. It provides a CLI for generating device-bound keys via `keygen` and managing recipients, supporting both `se` and `tag` recipient types, as well as post-quantum keys.

Tokens
2.9K
Snippets
7
Records
16
Agent score
51%

What's inside age-plugin-se

  1. How the plugin interacts with Apple's Secure Enclave

    main

    The plugin is implemented entirely in Swift using Apple's CryptoKit framework to interact with the Secure Enclave.

    By choosing CryptoKit over the older Security framework, the plugin achieves several advantages for the end-user:

    • No special entitlements required: Unlike the Security framework, CryptoKit does not require an Apple Developer Certificate or special entitlements to run, allowing the plugin to be distributed as a simple standalone binary (e.g., via Homebrew).
    • Direct Secure Enclave access: It accesses the Secure Enclave directly without the side effects of the Security framework, such as automatically creating entries in the macOS Keychain.
    • Simplicity: It avoids the complexity of managing macOS App structures or Keychain-based key lookups.

  2. Understand the `piv-p256` recipient stanza

    main
    The age-plugin-se uses the piv-p256 recipient stanza for encrypted files. This stanza is currently being standardized and is the same one used by the age-plugin-yubikey plugin. When you encrypt a file using this plugin, the recipient information will be formatted using this specific stanza.

  3. Relationship between CryptoKit and Swift Crypto

    main
    The plugin uses CryptoKit directly when running on macOS to access Secure Enclave APIs. On non-macOS platforms, it uses Swift Crypto, which is an open-source implementation of a subset of CryptoKit designed for Linux and Windows. This ensures the cryptographic primitives are available across different environments while maintaining native performance and security on macOS.

  4. Convert SE recipients to tag recipients

    main

    The age-plugin-se plugin supports two recipient types via the --recipient-type option:

    • se: Starts with age1se1.... Requires the plugin to be installed for encryption.
    • tag: Starts with age1tag1.... Uses built-in support in age (v1.3.0+) and does not require the plugin to be installed for encryption. It also obfuscates that the key is protected by the Secure Enclave.

    If you have an existing se recipient and the corresponding identity, you can generate a tag recipient using the recipients command.

    # Convert an existing SE identity to a tag recipient
age-plugin-se recipients -i key.txt --recipient-type tag

  6. Encrypt and decrypt files using age-plugin-se

    main

    Once you have generated a Secure Enclave identity, you can use the standard age tool to encrypt and decrypt files. age will automatically detect and use the plugin if it is in your execution path.

    Encryption

    Use the public key (printed during keygen) as the recipient. Encryption can be performed on any machine (Linux, Windows, macOS), even those without a Secure Enclave.

    Decryption

    Use the private key file as the identity. Decryption must be performed on the machine where the key was generated, and it will trigger a biometry prompt (e.g., Touch ID).

    # 1. Generate key
age-plugin-se keygen --access-control=any-biometry -o key.txt

# 2. Encrypt (using the public key printed by keygen)
tar cvz ~/data | age -r age1se1qgg72x2qfk9wg3wh0qg9u0v7l5dkq4jx69fv80p6wdus3ftg6flwg5dz2dp -o data.tar.gz.age

# 3. Decrypt (requires Touch ID on the original machine)
age --decrypt -i key.txt -o data.tar.gz data.tar.gz.age

  7. Install age-plugin-se

    main

    You can install age-plugin-se using several methods depending on your operating system:

    Homebrew (macOS)

    brew install age-plugin-se

    Pre-built Binary

    1. Download a binary from the releases page.
    2. Extract the package.
    3. Windows only: Install Swift.
    4. macOS only: Trust the binary by Control-clicking the file in Finder, choosing Open, and confirming trust.
    5. Move age-plugin-se to an executable path (e.g., /usr/local/bin).

    Alpine Linux

    1. Download and install the package signing key to /etc/apk/keys:
      doas wget -P /etc/apk/keys https://raw.githubusercontent.com/remko/age-plugin-se/main/Scripts/alpine/r@mko.re-66596f64.rsa.pub
    2. Download the .apk files from the releases page.
    3. Install them using apk add:
      doas apk add ./age-plugin-se-0.1.3-r0-x86_64.apk
doas apk add ./age-plugin-se-doc-0.1.3-r0-noarch.apk

    Building from Source

    1. Install Swift (required for non-macOS platforms).
    2. Clone the repository or download a source package.
    3. Run make to build.
    4. Run sudo make install PREFIX=/usr/local to install.

  8. Integrate age-plugin-se with passage

    main

    You can use age-plugin-se to protect passwords in [passage] using Touch ID.

    Setup Workflow

    1. Create Secure Enclave identity: age-plugin-se keygen -o $HOME/.passage/identities.
    2. Create a backup identity: Since the SE key is device-bound, create a standard age backup: age-keygen | age -p > $HOME/.passage/identities.backup.
    3. Configure recipients: Add both the Secure Enclave public key and the backup public key to $HOME/.passage/store/.age-recipients.

    Recovery Workflow

    If you lose your device:

    1. Generate a new age-plugin-se key.
    2. Add the new public key to .age-recipients.
    3. Decrypt your backup key using age -d $HOME/.passage/identities.backup > $HOME/.passage/identities.
    4. Run passage reencrypt to update the store.
    # Create SE identity
age-plugin-se keygen -o $HOME/.passage/identities

# Create backup
age-keygen | age -p > $HOME/.passage/identities.backup

# Configure passage to use both
cat << EOF > $HOME/.passage/store/.age-recipients
# Backup key
age1szwgh3vau33786pdp77yl2rx9hdl9p9v6t5aynzv9jepv2lqys6q24pcc4

# Secure Enclave key
age1se1qgg72x2qfk9wg3wh0qg9u0v7l5dkq4jx69fv80p6wdus3ftg6flwg5dz2dp
EOF

  9. Generate a Secure Enclave identity with keygen

    main

    Use the keygen subcommand to generate a new private key bound to your machine's Secure Enclave. You must specify an --access-control type to define how the key is protected (e.g., via Touch ID or passcode).

    Warning: The private key is bound to the specific Secure Enclave of your machine and cannot be transferred to another machine. Always maintain a separate backup key (e.g., a standard age key) for long-term data.

    # Generate a key requiring any biometry (e.g. Touch ID)
age-plugin-se keygen --access-control=any-biometry -o key.txt

  10. Reference: age-plugin-se CLI commands and options

    main

    The age-plugin-se CLI provides two primary subcommands:

    keygen

    Generates a new private key bound to the Secure Enclave.

    recipients

    Reads an identity file and outputs the corresponding recipient(s).

    Global Options

    OptionDescription
    --access-control ACCESS_CONTROLAccess control for the generated key. Supported: none, passcode, any-biometry, any-biometry-and-passcode, any-biometry-or-passcode, current-biometry, current-biometry-and-passcode. Default: any-biometry-or-passcode.
    -o, --output OUTPUTWrite the result to the file at path OUTPUT.
    -i, --input INPUTRead data from the file at path INPUT.
    --pqGenerate post-quantum keys (always uses tag recipient type).
    --recipient-type RECIPIENT_TYPERecipient type to generate. Supported: se, tag. Default: se.
    age-plugin-se keygen [--pq] [-o OUTPUT] [--access-control ACCESS_CONTROL] [--recipient-type RECIPIENT_TYPE]
age-plugin-se recipients [--pq] [-o OUTPUT] [-i INPUT] [--recipient-type RECIPIENT_TYPE]

  11. Configure access control for Secure Enclave keys

    main

    Use the --access-control option to define how the generated key can be used. This determines the biometric or passcode requirements for accessing the key in the Secure Enclave.

    Supported values:

    • none
    • passcode
    • any-biometry
    • any-biometry-and-passcode
    • any-biometry-or-passcode (Default)
    • current-biometry
    • current-biometry-and-passcode

    Note on current-biometry: When using current-biometry, adding or removing a fingerprint stops the key from working. Removing an added fingerprint enables the key again.

  12. Reference: `age-plugin-se` CLI Options

    main

    The following options are available for the keygen and recipients subcommands:

    OptionArgumentDescription
    --access-controlACCESS_CONTROLAccess control for using the generated key.
    -i, --inputINPUTRead data from the file at path INPUT.
    -o, --outputOUTPUTWrite the result to the file at path OUTPUT.
    --pq(flag)Generate post-quantum keys.
    --recipient-typeRECIPIENT_TYPERecipient type to generate (se or tag).