DOCSEARCHbyAlgolia
Submit Docs

rage

repository·main·Indexed 25 days ago

https://github.com/str4d/rage

A simple, modern, and secure file encryption tool implementing the 'age' format. Designed for UNIX-style composability, rage supports multiple recipients, passphrases, and SSH keys. It includes a CLI for encrypting and decrypting files, as well as the age-plugin library for extending the encryption format via custom recipient and identity logic.

Tokens
17.2K
Snippets
27
Records
106
Agent score
86%

What's inside rage

  1. Understand the age plugin architecture

    main

    The age-plugin library provides an API for building plugins that extend the age file encryption format. Plugins allow exposing recipient and identity logic across process boundaries.

    An age client (like rage) interacts with plugins using two main components:

    1. Recipients: Wraps file keys into stanzas for encryption.
    2. Identities: Unwraps stanzas to retrieve file keys for decryption.

    Plugins are identified by a case-insensitive NAME. The client searches the system PATH for a binary named age-plugin-<name> to execute the plugin.

  2. When to use the age-core Rust library

    main
    The age-core crate contains common structs and functions used across the age ecosystem. Most developers should use the primary age crate instead. You should only depend on age-core directly if you are implementing a custom recipient type.

  3. Test localization locally

    main

    To verify translations locally, run the binary with the LANG environment variable set to your target locale. Use cargo run --bin BINARY_NAME -- ARGUMENTS to execute the command.

    Example for testing rage and rage-keygen with a specific locale:

    $ LANG=your-locale cargo run --bin rage -- --help
$ LANG=your-locale cargo run --bin rage -- ARGUMENTS
$ LANG=your-locale cargo run --bin rage-keygen -- --help

  4. Use the rage CLI

    main

    The rage CLI is used for encrypting and decrypting files using the age format. It supports multiple recipients, passphrases, and SSH keys.

    Basic Command Syntax:

    • Encrypt: rage [--encrypt] (-r RECIPIENT | -R PATH)... [-i IDENTITY] [-a] [-o OUTPUT] [INPUT]
    • Decrypt: rage --decrypt [-i IDENTITY] [-o OUTPUT] [INPUT]

    Key Arguments & Options:

    • [INPUT]: Path to the file to read (defaults to stdin).
    • -e, --encrypt: Encrypt the input (default behavior).
    • -d, --decrypt: Decrypt the input.
    • -r, --recipient <RECIPIENT>: Specify an age public key (age1...) or an SSH public key. Can be repeated.
    • -R, --recipients-file <PATH>: Path to a file containing one recipient per line. Can be repeated.
    • -i, --identity <IDENTITY>: Path to an age identity file or an SSH private key file. Can be repeated.
    • -p, --passphrase: Encrypt with a passphrase instead of recipients.
    • -a, --armor: Encrypt to a PEM encoded format.
    • -o, --output <OUTPUT>: Write the result to the specified file (defaults to stdout).

  5. Add or update translations using Fluent

    main

    The project uses Fluent for localization. Locale files are located in age/i18n/ and rage/i18n/ directories.

    To update an existing locale (your-locale):

    1. Compare age/i18n/en-US/age.ftl with age/i18n/your-locale/age.ftl and copy over any missing unique identifiers.
    2. Compare rage/i18n/en-US/age.ftl with rage/i18n/your-locale/age.ftl and copy over any missing unique identifiers.
    3. Edit the .ftl files in both age/i18n/your-locale/ and rage/i18n/your-locale/ to replace English text with translations.

    To add a new locale (your-locale):

    1. Create directories age/i18n/your-locale/ and rage/i18n/your-locale/.
    2. Copy age/i18n/en-US/age.ftl to age/i18n/your-locale/age.ftl.
    3. Copy rage/i18n/en-US/age.ftl to rage/i18n/your-locale/age.ftl.
    4. Edit the new .ftl files to provide the translations.

  6. Install rage

    main

    You can install rage using various package managers depending on your environment:

    • Cargo (Rust 1.85+): cargo install rage
    • Homebrew (macOS/Linux): brew install rage
    • MacPorts: port install rage
    • Alpine Linux (edge): apk add rage
    • Arch Linux: pacman -S rage-encryption
    • NixOS: Add pkgs.rage to environment.systemPackages or run nix-env -i rage
    • openSUSE Tumbleweed: zypper install rage-encryption
    • FreeBSD: pkg install rage-encryption
    • Scoop (Windows): scoop bucket add main then scoop install main/rage
    • Debian/Ubuntu: Use pre-built Debian packages.

    Pre-built binaries are also available on GitHub Releases for Windows, Linux, and macOS.

    cargo install rage

  8. Encrypt and decrypt with passphrases

    main

    You can use passphrases instead of public keys by using the -p or --passphrase flag. If you leave the passphrase empty during encryption, rage will automatically generate a secure one.

    Encryption:

    $ rage -p -o example.png.age example.png
# Follow prompts to enter or autogenerate passphrase

    Decryption:

    $ rage -d example.png.age > example.png
# Follow prompt to enter passphrase

    Note on Pinentry: If a binary named pinentry is in your $PATH, rage will use it for passphrase entry. You can override this by setting the PINENTRY_PROGRAM environment variable.

    rage -p -o example.png.age example.png

  9. Build Debian packages for rage

    main
    To build a Debian package for the rage package, you must first install the cargo-deb utility. Once installed, you can generate the package using the cargo deb command targeting the rage package.

  10. Use the age crate instead of age-core

    main
    The age-core crate is a low-level library containing common structs and functions used across the age ecosystem. Most users should depend on the age crate directly. You should only depend on age-core if you are implementing a custom recipient type.

  11. Configure age feature flags

    main

    The age crate provides several optional features to extend its functionality. You can enable these in your Cargo.toml using the features key.

    • armor: Enables the age::armor module for support of ASCII-armored age files.
    • async: Enables asynchronous APIs for encryption and decryption.
    • cli-common: Enables common helper functions for building age CLI tools.
    • ssh: Enables the age::ssh module to reuse existing SSH key files for encryption.
    • web-sys: Enables calculating the work factor for passphrase encryption using the Web Performance timer when compiling for wasm32-unknown-unknown targets.
    • unstable: Enables in-development functionality. Warning: Features behind this flag have no stability or interoperability guarantees.

  12. Decrypt files with rage

    main
    Use the decrypt command to recover files. Decryption requires providing identities (such as SSH keys or identity files). If the file was encrypted using a passphrase (scrypt), you must provide the passphrase rather than identity files. Note that the --armor flag is not supported during decryption; the tool automatically detects if the input is armored.