Introduction to op-cache

op-cache is a fast caching proxy specifically designed for enhancing the performance of 1Password CLI's op read commands. When using the 1Password command-line tool to retrieve secrets, users often face latency issues, as these commands typically take between 200 to 500 milliseconds to execute. This delay arises from the need to communicate with the 1Password desktop application for each request.

Installation

Setting up op-cache is straightforward, and you can choose between two methods: using Cargo or building it manually. Here’s how to get started.

Cargo

If you have Rust and Cargo installed, the easiest way to install op-cache is through the following command:

cargo install --path .

This command installs the op-cache binary directly from the current directory.

Manual

Alternatively, if you prefer to build op-cache manually, follow these steps:

1. Clone the op-cache repository to your local machine.
2. Navigate to the directory where you cloned the repository.
3. Run the following command to build the project:

cargo build --release

After the build process completes, you will find the op-cache binary in the

target/release/ 

directory. You can run it using:

./target/release/op-cache

Verifying the installation

To verify that op-cache has been installed correctly, you can check its version by running:

op-cache --version

This should display the version of op-cache you just installed.

How to use op-cache

Getting started with op-cache is straightforward. Below are the essential commands you'll need to manage secrets efficiently.

Reading a secret

To read a secret, simply use the following command:

op-cache read op://vault/item/field

This command automatically starts the op-cache daemon if it's not already running, allowing for quick access to cached secrets. For instance, if you want to read an API token, you can execute:

op-cache read op://Private/API/token

Running Commands

An interesting feature is also op-cache run with the ability to scan your environment for variables with op:// values and resolve them all concurrently through the cache, then replaces the current process with your command (via exec).

Here's an example from the README:

# Run a command with secrets in env vars
export DATABASE_URL="op://Private/DB/url"
export API_KEY="op://Private/API/token"
op-cache run -- ./my-app

# Works with any command
op-cache run -- env | grep SECRET
op-cache run -- docker compose up

Checking daemon status

To verify if the op-cache daemon is running, use:

op-cache status

This command provides insights into the daemon's current state, ensuring that your caching setup is operational.

Viewing cache statistics

You can monitor the performance of your cache by checking statistics with:

op-cache stats

This will return information such as the number of entries, hits, misses, and the current hit rate. For example:

$ op-cache stats
Cache Statistics:
  Entries: 1
  Hits:    0
  Misses:  1
  Hit Rate: 0.0%

Clearing the cache

If you need to clear all cached secrets, perhaps due to changes in your vault, use:

op-cache clear

This command purges the cache immediately, ensuring that subsequent reads fetch the latest data.

Stopping the daemon

To stop the op-cache daemon safely, use:

op-cache stop

This command shuts down the daemon cleanly, freeing up system resources.

Retrieving secrets in scripts

Imagine you have a script that requires accessing a secret multiple times. Without op-cache, each op read command could take between 200-500ms due to the communication overhead with the 1Password desktop app. However, with op-cache, the first command will take the usual time, but subsequent calls will return the cached secret in just 1-2ms.

Example:

# First read - cache miss
$ op-cache read op://Private/API/token
sk-abc123...

# Status check
$ op-cache stats
Cache Statistics:
  Entries: 1
  Hits:    0
  Misses:  1
  Hit Rate: 0.0%

# Second read - cache hit
$ op-cache read op://Private/API/token
sk-abc123...

# Status check
$ op-cache stats
Cache Statistics:
  Entries: 1
  Hits:    1
  Misses:  1
  Hit Rate: 50.0%

In this scenario, the efficiency gain becomes apparent as the script can execute faster, reducing overall execution time.

How op-cache works

op-cache is designed to streamline the process of retrieving secrets with the 1Password CLI, significantly improving performance through caching. At its core, op-cache operates as a fast caching proxy that interacts with a local daemon, which manages the storage of secrets in memory.

Interaction with the daemon

When you execute a command to read a secret, op-cache checks the local daemon's cache via a UNIX socket. If the secret is found in the cache (a cache hit), the response is returned almost instantly, typically within 1-2 milliseconds. This is a stark contrast to the standard op read command, which can take 200-500 milliseconds due to the need to communicate with the 1Password desktop app.

On the other hand, if the secret isn't in the cache (a cache miss), op-cache will invoke the op read command to fetch the secret from the 1Password app. Once retrieved, this secret is stored in the cache for future requests, thus reducing the time for subsequent reads.

Auto-start daemon

One of op-cache's user-friendly features is its ability to auto-start the daemon on the first use. This means that even if the daemon isn't running, you can initiate a secret read command seamlessly, allowing for a smoother user experience.

By leveraging this caching mechanism, op-cache dramatically reduces the time spent on repeated secret retrieval, making it an invaluable tool for 1Password CLI users, especially those who need to access secrets frequently within scripts.

Configuration options

Configuring op-cache is a straightforward process that allows you to tailor its performance to meet your needs. The configuration settings are stored in a YAML file, which is typically located at ~/.config/op-cache/config.yaml . Below are the key options you can modify:

Socket path

The socket path defines where the op-cache daemon will communicate with the client. The default is set to /tmp/op-cache.sock . You can change this to a different path if needed, but ensure the specified directory is writable.

socket_path: /tmp/op-cache.sock

Time-to-live (TTL)

The ttl_seconds setting specifies how long cached secrets remain valid. The default value is set to 86400 seconds (or 24 hours). You can adjust this value to expire cached secrets sooner or later based on your security needs.

ttl_seconds: 86400  # Cache TTL in seconds

Maximum entries

The max_entries option controls how many secrets can be cached simultaneously. By default, this is set to 1000 entries. If you expect to work with a larger set of secrets, consider increasing this number.

max_entries: 1000  # Max cached secrets

Op CLI path

This setting specifies the path to the Op CLI tool. If you have installed it in a custom location, you can update this path accordingly.

op_path: op  # Path to op CLI

Command timeout

The op_timeout_seconds defines how long the Op commands will wait before timing out. The default is set to 30 seconds, which should be sufficient for most operations.

op_timeout_seconds: 30  # Timeout for op commands

Optional settings

All configuration options are optional, as sensible defaults are provided. You can choose to modify only the settings that are relevant to your use case. After making changes, simply save the config.yaml file, and your new settings will take effect the next time you run op-cache.

By tailoring these configurations, you can optimize op-cache to better meet the demands of your workflow and enhance your experience while using the 1Password CLI.

Security

When it comes to managing sensitive information, security is paramount. op-cache incorporates several robust measures to ensure that your cached secrets remain secure.

Memory-only storage

One of the key security features of op-cache is that it stores cached secrets solely in memory. This means that sensitive data is never written to disk, significantly reducing the risk of unauthorized access through file system vulnerabilities. By keeping secrets in volatile memory, op-cache minimizes exposure and ensures that your data is only accessible during the active session.

User isolation

op-cache employs UNIX socket permissions to implement user isolation. Each user has their own separate cache, which prevents other users on the same system from accessing cached secrets. This isolation is crucial for maintaining confidentiality, especially in multi-user environments where sensitive information should be kept private.

Time-to-Live (TTL)

To further enhance security, op-cache includes a Time-to-Live (TTL) feature, which automatically expires cached secrets after a predetermined duration (defaulting to 24 hours). This ensures that old secrets are not lingering in memory longer than necessary, reducing the risk of exposure if a session is compromised.

Immediate cache purge

In case of an emergency or if you need to refresh the cached data, you can easily clear the cache with the op-cache clear command. This action immediately purges all cached secrets, providing an additional layer of control over your sensitive information.

Daemon management

The op-cache daemon is designed to stop cleanly when you issue the op-cache stop command or when the system shuts down. This ensures that no secrets are left behind in memory after the daemon is no longer active, further safeguarding your data.

By implementing these security measures, op-cache provides a reliable and secure way to manage your secrets while enhancing the performance of 1Password CLI commands. You can read more about op-cache on its GitHub page.