Working with Opki in production
Opki is an OpenPGP key infrastructure implementation, and like most things in the key management space, it does one thing well and a dozen things poorly if you expect it to handle everything. The core idea is straightforward: it automates the generation, distribution, and revocation of OpenPGP keys using smartcard backends. If you've ever manually pushed keys to a YubiKey with gpg --edit-card, you already know the pain Opki tries to solve. I built a small deployment around Opki last year for a team that needed hardware-backed signing keys distributed across twelve people. The theory was clean. The actual execution dragged on for three weeks because I kept running into a specific edge case with batch-generated primary keys not syncing to the smartcard's ATR response consistently. The cards would register fine, gpg would see them, but the key references inside the OpenPGP applet would occasionally diverge from what Opki's database recorded. The workaround was to force a full card reset between each batch operation using gpg --card-edit followed by the admin commands, then let Opki re-poll the card state before proceeding with any subsequent key assignments. It added maybe twenty minutes per machine, but skipping it meant keys showing up in the wrong slots or not at all.
What Opki actually requires
You need a Linux system running the standard GnuPG stack, preferably version 2.2 or later, and a smartcard that supports the OpenPGP applet at version 3.4 or higher. I use YubiKeys in the 5-series, though any CCID-compliant device with OpenPGP card support works. The software itself is available from the usual project sources on GitHub, and the install path typically involves pulling the source, compiling against the pcsc-lite development headers, and running the built binaries from a known directory rather than installing system-wide, which avoids library conflicts with whatever GnuPG package your distro ships. The configuration happens through a YAML file. It defines your local key server URL, the smartcard backend, and per-user settings. Each user gets a profile that maps their email to a specific card slot and a pre-generated key template. This is where most people hit trouble. The key template needs to match the exact parameter set your policy requires, and if you generate templates with suboptimal curve choices or weak expiration dates, Opki will faithfully replicate those choices everywhere and you'll spend hours later trying to correct them.
Setting up the first key rotation
Create your Opki config directory and populate it with a base config file. Set the smartcard backend to pcsc and point the key server to whatever internal GnuPG keyserver you're running. If you don't have one, Opki can operate in offline mode, but then you lose automated distribution and revocation becomes a manual process. Generate a master key template using gpg --full-generate-key with your required parameters. Do not use --quick-generate-key here. The faster command sometimes produces subkeys with mismatched capabilities that confuse Opki's parsing. Once the master key exists, export it with gpg --export-secret-keys and store it in your templates directory. Then configure a user profile referencing that template, assigning it to the appropriate smartcard slot. When you run the deployment command, Opki will attempt to clone the template onto the target card. It reads the card's current state, writes the secret key material to the correct application object, and verifies the result. The verification step is where things usually go wrong if the card firmware is outdated. Make sure the YubiKey firmware is at least version 5.2.3. Older firmwares have a bug where the OpenPGP applet silently drops the RSA decryption key under certain conditions during bulk writes. You won't see an error. The key just won't be there when you try to use it.
Common issues and what to do about them
The biggest problem I've seen with Opki is revocation handling. When a card is lost or compromised, Opki can generate a revocation certificate and push it to the configured keyserver. But the actual mechanism depends on the keyserver supporting DANE-TLS or at least HTTPS with certificate validation. Many internal keyservers run plain HTTP, and Opki doesn't gracefully handle that. It either fails outright or uploads without integrity verification, which means you can't trust the revocation made it out. Another issue is batch operations on cards that have already been provisioned with different tools. If a YubiKey has had keys written to it using gpg's built-in key import before Opki touches it, the metadata can conflict. Opki expects a clean card with only the OpenPGP applet in its factory state. The fix is to reset the card fully through the YubiKey Manager tool before running any Opki operations. This wipes all application data including PIV and OATH, so don't do this on a card that's doing other work. Performance is another practical concern. Opki processes cards sequentially by default, even when you specify multiple targets. A single full key write cycle takes roughly two to three minutes per card, and there's no built-in parallelization. For a team of thirty, that's over an hour of uninterrupted time. I got around this by writing a simple shell wrapper that launches multiple Opki instances against different USB ports and monitors their exit codes. It's not elegant, but it cuts the total time down to around fifteen minutes depending on your USB controller topology.
When Opki isn't the right choice
If you only need to manage a handful of keys on personal hardware, GnuPG's native card tools are faster and don't require a separate daemon. Opki shines when you're managing twenty or more devices across multiple users with consistent policies. Below that threshold, you're adding operational overhead without much benefit. For environments where hardware-backed keys aren't mandatory, consider a certificate-based PKI instead. Opki is deeply tied to the OpenPGP model, which has well-known limitations around key binding and user identity verification that X.509 doesn't share in the same way. If your organization already uses X.509 infrastructure, introducing Opki creates a second trust domain that nobody will maintain properly. The project itself moves slowly. Releases are infrequent, and the documentation assumes you already understand OpenPGP card internals. If you're comfortable with gpg-agent, pcsc-lite, and the OpenPGP card specification, Opki is manageable. If you're not, plan for a steep learning curve that offers diminishing returns compared to simpler alternatives.
