pwn 0.5.783 → 0.5.785

data/etc/default_skills/pwn/plugins/yubikey/fido/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: pwn-plugins-yubikey-fido
+description: Use when managing native FIDO and U2F operations.
+license: MIT
+allowed-tools: [pwn, pwn_eval]
+metadata:
+  bundled: true
+  preserve: true
+  module: PWN::Plugins::YubiKey::FIDO
+  source: pwn/plugins/yubikey/fido.rb
+---
+
+# Native FIDO/U2F
+
+Use `PWN::Plugins::YubiKey::FIDO` for CTAP2 management and caller-controlled
+credential operations. Application logic and CBOR are Ruby; cryptography uses
+Ruby OpenSSL and host entropy. No executable, interpreter worker or CBOR gem is
+required. CTAPHID framing and shared-library device I/O belong to `Transport`.
+
+## When to use
+
+- Read authenticator capabilities, manage PINs, discoverable credentials,
+  fingerprints, always-UV and enterprise-attestation configuration.
+- Run low-level makeCredential/getAssertion or U2F registration/authentication
+  with an RP/application and client-data hash supplied by the caller.
+- Do not treat this module as a browser or WebAuthn relying-party server. It does
+  not invent origins, approve RP IDs or verify server challenges/signatures.
+
+## Prerequisites and safety
+
+Obtain an explicitly selected FIDO connection from `YubiKey::Transport.open`
+with `application: :fido`. Serial-less Security Keys are valid; select them by
+exact device path/reader or unambiguous inventory, never an OTP serial guess.
+HID supports CTAP/U2F; APDU supports FIDO AID selection, NFC CTAP, command chaining,
+GET RESPONSE, keepalive and cancellation. Read getInfo to negotiate actual
+options and PIN protocol 2 or 1; do not infer support from the model name.
+
+Every authentication, signature/counter operation and mutation requires literal
+`confirm: true`. `--force` is only an accepted compatibility flag; it grants no
+consent. `info`, retry counters and fingerprint sensor information do not require
+consent. Help groups are local and do not need a connection.
+
+Supply `pin:` and `new_pin:` as in-memory Strings, or an explicitly provided
+`secret_provider:` callable receiving `:pin`/`:new_pin`. Never put these in args,
+process arguments, environment variables, files or transcripts. There is no
+factory PIN, default prompt, automatic PIN retry or automatic reset retry.
+Sessions erase owned secret copies on completion, but Ruby/OpenSSL cannot promise
+that every temporary allocation is zeroized. Caller-owned Strings are untouched.
+
+## Management calls
+
+```ruby
+fido = PWN::Plugins::YubiKey::FIDO
+fido.execute(args: [])                         # local leaf catalog
+fido.execute(args: ['access'])                 # local group help
+fido.execute(connection: connection, args: ['info'])
+fido.perform(connection: connection, operation: :pin_retries)
+# secret_provider below is an operator-supplied private callable, not a prompt default.
+fido.execute(connection: connection, args: %w[access verify-pin],
+             secret_provider: secret_provider, confirm: true)
+```
+
+Implemented leaf paths (args exclude the `fido` prefix):
+
+| Path | Additional in-memory inputs / behavior |
+|---|---|
+| `info` | Actual CTAP getInfo, or U2F version/capabilities |
+| `reset` | One reset command; firmware power-up/touch window still applies |
+| `access change-pin` | `new_pin:`, plus `pin:` when already configured; initializes only if getInfo reports no PIN |
+| `access change-pin --u2f` | YubiKey 4 FIPS vendor U2F PIN command, capability-probed |
+| `access verify-pin` | `pin:`; verifies by obtaining and discarding a token, no fabricated RP |
+| `access force-change` | Config permission; requires existing PIN and setMinPINLength |
+| `access set-min-length LENGTH` | Optional repeatable `--rp-id RPID`; minimum cannot decrease |
+| `credentials list` | PIN/UV permission 0x04; exhausts every RP and credential; checks totals and duplicates |
+| `credentials list --csv` | Returns CSV in memory; no output file is opened |
+| `credentials delete HEX_ID` | Complete exact credential ID; no ambiguous prefix matching |
+| `fingerprints list` | Permission 0x08; returns template IDs and names |
+| `fingerprints add [NAME]` | Bounded capture loop and optional friendly name |
+| `fingerprints rename HEX_ID NAME` | Exact template ID and UTF-8 friendly name |
+| `fingerprints delete HEX_ID` | Exact template ID |
+| `config toggle-always-uv` | Permission 0x20 if a PIN/UV token is required |
+| `config enable-ep-attestation` | Requires advertised enterprise-attestation capability |
+
+Local groups: root, `access`, `credentials`, `fingerprints`, `config`.
+`operations` lists leaf paths only; variants above are not extra leaf operations.
+PIN verification selects a supported non-RP management permission when scoped
+tokens are advertised, or scopes getAssertion permission to an explicitly supplied
+`rp_id:`. Without either it uses legacy getPINToken, never an invented website.
+An authenticator disabling legacy tokens and exposing no non-RP permission needs
+the caller's `rp_id:`. Built-in UV is not accepted as proof of PIN verification.
+`perform(operation: :update_credential, credential_id: binary_id, user: user_hash,
+...)` implements CTAP2.1 updateUserInformation; `user['id']` must be the existing
+user ID. Preview credential management supports list/delete, not user update.
+
+All native IDs/hashes are **binary Strings** (`.b`); text is valid UTF-8.
+Hex CLI selectors are decoded only after strict even-length hex validation.
+PINs are not normalized or silently truncated. Standard CTAP PINs require at
+least the advertised minimum and at most the advertised byte limit (63 by
+default), with no NUL. Old FIPS U2F requires at least 6 characters and permits
+at most 32 encoded bytes. A newer advertised PIN limit does not waive the CTAP
+255-byte bound on the block-padded PIN plaintext.
+
+## Credential operations
+
+```ruby
+# client_data_hash is a 32-byte SHA-256 digest produced by the caller's ceremony.
+attestation = fido.make_credential(
+  connection: connection, confirm: true, client_data_hash: client_data_hash,
+  rp: { 'id' => relying_party_id, 'name' => relying_party_name },
+  user: { 'id' => user_id.b, 'name' => user_name },
+  secret_provider: secret_provider
+)
+assertions = fido.get_assertion(
+  connection: connection, confirm: true, rp_id: relying_party_id,
+  client_data_hash: client_data_hash,
+  allow_list: [{ 'type' => 'public-key', 'id' => credential_id.b }]
+)
+```
+
+makeCredential accepts `key_params:` (default ES256), `exclude_list:`,
+`extensions:`, `authenticator_options:` and `enterprise_attestation:` (1 or 2).
+getAssertion accepts `allow_list:`, `extensions:` and `authenticator_options:`;
+it returns an Array containing all advertised assertions, using getNextAssertion.
+Use `pin:`/`secret_provider:` for PIN verification, or literal `uv: true` for
+configured built-in UV and a permission-scoped token. Permission tokens bind
+makeCredential/getAssertion to the exact caller RP ID. No-PIN/non-UV requests
+remain possible where the authenticator permits them; the device enforces policy.
+CTAP2.0 preview commands use the legacy PIN token when scoped tokens are absent.
+
+`u2f_register(connection:, confirm: true, client_data_hash:, app_id_hash:)`
+returns the raw public key, key handle, attestation certificate and signature.
+`u2f_authenticate(..., key_handle:)` returns presence, counter and signature.
+Literal `check_only: true` interprets only defined U2F recognition statuses.
+These return cryptographic material, **not a server authentication verdict**.
+The caller must verify challenge, RP/application hash, origin policy, flags,
+algorithm, signature, attestation trust and counter semantics before accepting it.
+
+## Bounds, cancellation and recovery
+
+- `timeout:` is one finite positive operation budget, default 30 seconds.
+  `cancelled:` is a callable, forwarded to Transport as well as checked between
+  exchanges; `on_keepalive:` receives status 1 or 2. Callback exceptions propagate.
+- `max_records:` defaults to 1024, maximum 16384. Counts are assertions, not hints:
+  excessive, duplicate, inconsistent or prematurely ended lists fail explicitly.
+- Enrollment uses `capture_timeout_ms:` (default 10000), `max_samples:` (default
+  128), and optional `on_sample:` callable receiving template ID, status and
+  remaining samples. Intermediate bad captures are reported; PIN attempts are not
+  repeated. Failure attempts one separately bounded enrollment cancel, without
+  deleting any credential. A failed cleanup cannot replace the original error.
+- `perform(operation: :bio_sensor_info)` is unauthenticated. Explicit
+  `perform(operation: :cancel_enrollment, confirm: true)` cancels enrollment.
+- If enrollment completes but naming fails, `EnrollmentError#template_id` names
+  the already-created template. Rename that template; do not enroll again or
+  assume a rollback. A transport timeout can leave device state uncertain.
+- A connection is caller-owned. Use it exclusively for the whole operation; do
+  not interleave concurrent enumeration, PIN or enrollment workflows. Close it in
+  the caller's ensure block. A closed/error transport cannot promise cleanup.
+- U2F-only authenticators report U2F capabilities. CTAP2-only management fails
+  explicitly. FIPS-only PIN/reset commands are implemented, not substituted for
+  ordinary U2F devices. Physical touch/reset timing is never simulated.
+
+## CBOR and crypto verification
+
+`FIDO::CBOR.encode(value:)` / `.decode(data:)` use CTAP canonical major-type
+ordering, minimal integer/length encodings, 32-level depth, 16384-item and 1 MiB
+bounds. Map keys are integer/text; byte strings use ASCII-8BIT encoding. Reject
+indefinite lengths, duplicate keys, noncanonical maps, invalid UTF-8, trailing
+bytes, tags and floating-point values rather than coercing them.
+
+Protocol 1 derives SHA256(ECDH-x), zero-IV AES-256-CBC and 16-byte HMAC outputs.
+Protocol 2 derives independent HKDF-SHA256 HMAC/AES keys using the CTAP labels,
+uses a fresh host-random IV prefix and 32-byte HMAC. Validate COSE EC2/P-256/-25
+key agreement points before ECDH. No device OTP output supplies entropy.
+
+Run the paired RSpec offline with an isolated HOME and the repository's normal
+Ruby bundle; only Connection or native I/O fixtures may be faked. Keep independent
+RFC8949/NIST/RFC4231/P-256/KDF vectors, both PIN protocols, complete public
+management paths, response errors and cancellation tests. Passing fixtures prove
+host protocol behavior, not physical-device or platform interoperability.
+
+References used for the protocol contract:
+
+- [FIDO CTAP 2.1 proposed standard, 2021-06-15](https://fidoalliance.org/specs/fido-v2.1-ps-20210615/fido-client-to-authenticator-protocol-v2.1-ps-20210615.html)
+- [U2F raw message formats 1.2](https://fidoalliance.org/specs/u2f-specs-1.2-ps-20170411/fido-u2f-raw-message-formats-v1.2-ps-20170411.html)
+- [RFC 8949](https://www.rfc-editor.org/rfc/rfc8949) and [RFC 4231](https://www.rfc-editor.org/rfc/rfc4231)
+- Official `python-fido2` 2.2.1: `cbor.py`, `ctap1.py`, `pcsc.py`,
+  `ctap2/{base,pin,credman,bio,config}.py`; YubiKey Manager 5.9.1 `ykman/fido.py`
+  and its FIDO command module. These were read-only interoperability references,
+  not runtime dependencies; the Ruby implementation is independently written.

data/etc/default_skills/pwn/plugins/yubikey/hsmauth/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: pwn-plugins-yubikey-hsmauth
+description: Manage native HSM Auth credentials and sessions.
+license: MIT
+allowed-tools: [pwn, pwn_eval]
+metadata:
+  bundled: true
+  preserve: true
+  module: PWN::Plugins::YubiKey::HSMAuth
+  source: pwn/plugins/yubikey/hsmauth.rb
+---
+
+# Native YubiHSM Auth
+
+## When to use
+
+Use `PWN::Plugins::YubiKey::HSMAuth` for YubiKey YubiHSM Auth credentials and
+session-key derivation. This is not the YubiHSM2 management protocol or a browser
+WebAuthn ceremony. The root YubiKey router owns transport lifetime.
+
+## Public API
+
+- `execute(args:, connection:, ...)` handles `info`, `reset`, `credentials list`,
+  `generate`, `import`, `export`, `symmetric`, `derive`, `delete`, `change-password`,
+  and `access change-management-key` / `change-management-password`.
+- `operations`, `help`, `authors` are local metadata.
+- `open_session(connection:, timeout:)` selects once and returns a session handle.
+- `challenge(session:, label:, algorithm:, credential_password:, confirm: true)`
+  returns the host challenge or ephemeral uncompressed P-256 public point.
+- `calculate(session:, label:, algorithm:, context:, credential_password:,
+  card_crypto:, public_key:, confirm: true)` returns a Hash containing exactly
+  `key_senc`, `key_smac`, `key_srmac`, each sixteen raw bytes.
+
+## Procedure
+
+1. Select the intended APDU connection; never guess a device or factory key.
+2. Read `.help`. Supply passwords/keys only in memory or through a
+   `secret_provider:` receiving a field Symbol after literal `confirm: true`.
+   Wrong authentication is attempted once; APDU errors preserve `status` without
+   logging payloads. Status 63Cx encodes remaining attempts in its low nibble.
+3. Use exact complete label bytes. Management changes do not substring-match.
+4. Symmetric import uses raw `key_enc:` and `key_mac:` (sixteen bytes each).
+   `derive` uses `derivation_password:` with PBKDF2-HMAC-SHA256, salt `Yubico`,
+   10,000 iterations. `generate` creates a P-256 private key on device; symmetric
+   `--generate` returns the generated keys in memory for explicit caller storage.
+5. Asymmetric import accepts `private_key:` as a raw 32-byte scalar, an in-memory
+   PEM/DER String or private OpenSSL EC object on prime256v1. Encrypted PEM/DER
+   takes `key_password:`; it never prompts implicitly or retries decryption.
+   Export returns public key bytes in `RAW`, `PEM` (default) or `DER` format;
+   filenames and secret argv are not accepted by the family API.
+6. For a live HSM challenge exchange, retain the same `open_session` handle for
+   `challenge` and `calculate`. Do not select another application between them.
+   Symmetric context is host challenge + card challenge (sixteen bytes), optional
+   card cryptogram eight bytes. Asymmetric context is two uncompressed P-256
+   points (130 bytes), `public_key:` is the HSM long-term public point, and
+   `card_crypto:` contains sixteen bytes. The caller manages the HSM side.
+7. Check the returned verification scope. Create/delete/reset verify inventory
+   metadata, not private key contents. Password and management-key writes return
+   `status: :acknowledged, verification: :not_readable`; no second authentication
+   attempt is made merely to simulate readback.
+
+## Pitfalls
+
+- No shell, executable, network lookup, hidden cache or filesystem credential
+  lookup is performed. Raw keys are not auto-decoded from hexadecimal Strings.
+- Credential/management passwords are at most sixteen raw bytes and zero-padded
+  per protocol. An explicitly supplied empty String is allowed, but nil never
+  means the factory credential. Ruby memory is not guaranteed zeroizable.
+- Asymmetric operations and challenges require application version 5.6.0;
+  credential-password changes require 5.8.0. Random management-key generation is
+  rejected on 5.8 or later. SELECT failure is not permission to fall back.
+- Device timeout, cancellation or failure must propagate; never replay a mutation.
+- Session keys are secret return values. Do not print or put them in transcripts.
+
+## Verification
+
+Run `bundle exec rspec spec/lib/pwn/plugins/yubikey/hsmauth_spec.rb` and scoped
+RuboCop. The specs exercise production Protocol APDUs with a fake raw exchange
+boundary and independent PBKDF2 / P-256 wire vectors. No hardware interoperability
+or secure-channel transport is claimed by these offline tests.
+
+References: pinned yubikey-manager 5.9.1 `yubikit/hsmauth.py` and
+`ykman/_cli/hsmauth.py`; https://developers.yubico.com/yubihsm-auth/ .

data/etc/default_skills/pwn/plugins/yubikey/management/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: pwn-plugins-yubikey-management
+description: Configure native device capabilities with exact readback.
+license: MIT
+allowed-tools: [pwn, pwn_eval]
+metadata:
+  bundled: true
+  preserve: true
+  module: PWN::Plugins::YubiKey::Management
+  source: pwn/plugins/yubikey/management.rb
+---
+
+# PWN::Plugins::YubiKey::Management
+
+Native device information/configuration over OTP HID, management smartcard or
+CTAP vendor commands. No executable, subprocess, interpreter or network backend.
+
+## API and routing
+
+`execute(args: [...], connection: ...)` takes argv after `config`.
+`operations` lists five prior leaves: `usb`, `nfc`, `mode`, `set-lock-code`, `reset`.
+Empty args return local metadata without device I/O. `--force` is not consent.
+Typed APIs: `info`, `configure_usb`, `configure_nfc`, `set_mode`, `set_lock_code`,
+`reset`, `reboot`, `help`, `authors`. See runtime help for exact options.
+
+## Procedure
+
+1. Select the exact device explicitly. `info` reads version, serial, transport
+   capability masks, lock state, flags/timeouts, NFC restrictions, FIPS masks and
+   reset metadata. Retain unknown raw TLVs; reject malformed/duplicate records and
+   bound pagination. Do not infer all apps from a model or firmware version.
+2. On pre-4.1 firmware, report unavailable capability metadata explicitly and
+   only expose observed USB product/interface information. On 4.x, do not trust
+   the broken USB-enabled tag; 4.2.4 has a documented supported-mask correction.
+3. Application toggles and lock configuration require firmware 5.x plus observed
+   capabilities. `--enable`/`--disable` may repeat. Unsupported apps, conflicting
+   options, disabling all USB apps and missing lock metadata fail before a write.
+   `--list` is read-only and cannot be combined with changes.
+4. Every write/reboot/reset requires literal `confirm: true`. Lock material is
+   sixteen raw in-memory bytes via `lock_code:`/`new_lock_code:` or an explicit
+   `secret_provider.call(field)`. Never guess a credential. Generation requires
+   `secret_sink.call(:new_lock_code, bytes)`; never print the generated value.
+5. Write once, then read actual device information and compare requested fields.
+   Any lost acknowledgment, mismatching readback or identity change raises an
+   uncertainty error; never automatically resend. A lock flag verifies protection
+   state, not export/equality of the lock secret.
+6. USB interface changes normally reboot and need an explicit `reconnect`
+   callable before writing. It receives nonsecret prior identity metadata and
+   must return a fresh handle to the exact device. The returned handle is closed
+   after readback; the original connection remains caller-owned. Never rediscover
+   or switch to the first available key. Serial-less reconnection must preserve
+   the same observed explicit selector; missing/changed selectors fail uncertain.
+   Use `reboot: false` only to intentionally
+   defer activation; stored configuration readback is not active-interface proof.
+7. Legacy NEO/4 `mode` emits the four-byte little-endian mode/timeouts record.
+   Reconnect after physical reinsertion and verify the observed USB product ID
+   maps to exactly the requested interfaces. A CCID reader that provides no USB
+   product ID cannot prove full legacy interface mode; fail uncertain rather than
+   claim success. Legacy timeout values are not readable and are labeled so.
+8. Full-device reset is gated by Bio multi-protocol/PIV or reset-blocked capability
+   metadata and smartcard transport, not assumed available on all YubiKeys. Verify
+   the fresh reset-state field is cleared. `data_erasure_verified: false` is
+   explicit: configuration metadata does not independently prove forensic erasure
+   of every application credential. Use application-specific resets otherwise.
+9. NFC restriction is available from firmware 5.7 and lasts until USB power.
+   Disabling the currently used NFC path needs a separately usable readback path;
+   absence or lost connectivity is uncertainty, never verified completion.
+
+## Evidence boundaries
+
+Same-path specs use synthetic HID/APDU/CTAP wire frames and the real shared
+Protocol codec. They cover field packing, pagination, mutations/readback,
+capability/version refusals, secrets, stale responses and legacy modes. No real
+hardware, credential, network service or global reset is exercised by default.
+Physical compatibility across firmware/models still requires explicit operator
+hardware validation.
+
+Protocol provenance: official yubikey-manager **5.9.1** source,
+`yubikit/management.py`, `yubikit/core/otp.py`, `ykman/_cli/config.py` and
+<https://docs.yubico.com/yesdk/yubikey-api/Yubico.YubiKey.Management.Commands.html>.

data/etc/default_skills/pwn/plugins/yubikey/oath/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: pwn-plugins-yubikey-oath
+description: Use native OATH with exact account identities.
+license: MIT
+allowed-tools: [pwn, pwn_eval]
+metadata:
+  bundled: true
+  preserve: true
+  module: PWN::Plugins::YubiKey::OATH
+  source: pwn/plugins/yubikey/oath.rb
+---
+
+# Native OATH
+
+## When to use
+
+Use `PWN::Plugins::YubiKey::OATH` for OATH application APDUs, not software-only OTP
+or browser WebAuthn. The root YubiKey router owns transport lifetime.
+
+## Public API
+
+- `execute(args:, connection:, ...)` implements `info`, `reset`, `access change`,
+  `remember`, `forget`, and `accounts add`, `uri`, `import`, `list`, `code`,
+  `rename`, `delete`. Empty/group args return local metadata.
+- `operations`, `help`, `authors` are local metadata.
+- `code(connection:, account:, confirm: true, ...)` returns one numeric String.
+- `calculate(connection:, account:, challenge:, confirm: true, ...)` returns a
+  raw full HMAC, not a formatted OTP.
+- `calculate_all(connection:, timestamp:, confirm: true, ...)` returns credential
+  records with `code` value/validity Hashes; HOTP and touch records have nil codes.
+- `parse_uri(uri:)` validates and parses an in-memory otpauth URI locally.
+
+## Procedure
+
+1. Use a caller-selected APDU connection. Never select the first device implicitly.
+2. Pass the exact complete ID returned by LIST, including period/issuer prefixes,
+   whitespace and UTF-8 bytes. No substring, case folding or Unicode normalization
+   is performed when identifying an account.
+3. Use `code` for one numeric OTP String; leading zeroes are significant. Optional
+   `timestamp:` is nonnegative Integer epoch seconds. TOTP periods come from the
+   credential ID, while HOTP uses an empty challenge and increments its counter.
+4. Supply `password:` or sixteen raw bytes in `access_key:` in memory, or an
+   explicit `secret_provider:` callback. Authentication is single-attempt with
+   mutual HMAC-SHA1 verification after SELECT. Missing or wrong credentials never
+   trigger default guesses, repair, cached-key deletion, fallback or retry.
+5. For account creation supply `secret:` (raw bytes) or strict `secret_base32:`;
+   `--generate` returns the generated seed in memory. Metadata options include
+   oath-type, algorithm (SHA1/SHA256/SHA512), digits (6–8), period, issuer, initial
+   HOTP counter and touch. Invalid values fail before authentication. Existing
+   IDs require explicit `overwrite: true` or `--force` in addition to consent.
+6. URI input goes in `uri:`, not argv. Conflicting issuer fields, noncanonical
+   Base32, duplicate URI parameters and invalid periods are rejected, not repaired.
+7. Bulk import accepts `credentials:` (complete Hash records) or `pskc:` (in-memory
+   PSKC 1.0 XML). Validate the complete batch before any authentication/write;
+   never silently skip a bad entry. Each successful PUT is checked with LIST.
+   Partial device failure is not rolled back or retried.
+8. Use `access change` with `new_password:` / `new_access_key:`, or `--clear`.
+   Changes read back protection state only, not secret contents. Reset uses DEAD
+   confirmation bytes and verifies regenerated salt, unlocked state and empty
+   inventory. Rename/delete verify exact IDs and never delete as a repair step.
+
+## Explicit encrypted-cache handoff
+
+There is no built-in host cache or implicit lookup. `access remember`, `--remember`
+and `use_cache: true` require an explicit `encrypted_cache:` adapter supplied by
+the caller. It must expose `encrypted? == true` and these methods:
+
+```ruby
+cache.store(device_id: id, access_key: raw_key)
+cache.fetch(device_id: id) # raw bytes or nil
+cache.delete(device_id: id)
+# access forget --all additionally requires:
+cache.clear
+cache.empty?
+```
+
+The adapter owns encryption-at-rest and unlock policy; the assertion is the
+caller's contract, not a cryptographic audit by this module. This is a transfer to
+an explicit encrypted storage API, **not a plaintext file store**. Mutations are
+read back through the adapter. Stored keys are never deleted after failed auth,
+or automatically removed on password change/reset; explicitly forget stale
+records. `use_cache:` never falls back to a password after failure. Do not supply
+a plaintext Hash/file adapter in production.
+
+## Pitfalls and limits
+
+- `confirm: true` is mandatory for auth, code calculation, mutations and cache
+  writes. `--force` does not supply confirmation. Unprotected inventory is read-only.
+- Native PSKC import supports plain values, AES-128/192/256 key-wrap and
+  MAC-authenticated AES-CBC, raw `pskc_key:` or embedded PBKDF2 with
+  `pskc_password:`. Unsupported algorithms, XML signatures and DTD/entities are
+  rejected. PSKC export-on-add, legacy file-path argv, arbitrary XML encryption
+  algorithms and Steam-specific five-character output are not implemented.
+- LIST returns all exact IDs, including hidden-named records. Display-only legacy
+  flags do not change the structured result. Exact numeric MFA does not silently
+  switch to Steam formatting.
+- Touch requires version 4.2.6, SHA512 4.3.1, rename 5.3.1. Known pre-4.3.5 prefix
+  overwrite defects fail closed. FIPS policy is ultimately enforced by the
+  selected application; no host override or plaintext secure-channel fallback exists.
+- No CLI, subprocess, corrupt-account repair, silent credential deletion or disk
+  access exists. Ruby does not guarantee memory zeroization.
+- A successful APDU or inventory readback is not physical interoperability or
+  proof of the imported secret. Timeouts leave mutation state uncertain.
+
+## Verification
+
+Run `bundle exec rspec spec/lib/pwn/plugins/yubikey/oath_spec.rb` and scoped
+RuboCop. Tests exercise production Protocol framing and a raw exchange boundary,
+including application-specific A5 SEND REMAINING, mutual auth, RFC 6238 vectors,
+strict identities, mutation readback, cache handoff, and authenticated PSKC import.
+No real hardware, home credentials or network is accessed.
+
+References: Yubico YKOATH protocol and pinned yubikey-manager 5.9.1
+`yubikit/oath.py` / `ykman/_cli/oath.py`; RFC 4226, RFC 6238, RFC 6030 and RFC 3394.
+https://developers.yubico.com/OATH/YKOATH_Protocol.html

data/etc/default_skills/pwn/plugins/yubikey/openpgp/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: pwn-plugins-yubikey-openpgp
+description: Use native Ruby OpenPGP card operations through YubiKey APDUs.
+---
+
+# PWN::Plugins::YubiKey::OpenPGP
+
+Native Ruby application logic using the shared `YubiKey::Protocol` APDU/TLV codec
+and a caller-owned `Connection`. It does not run a CLI, start a subprocess, invoke
+another interpreter, discover hardware at load time, or invent factory credentials.
+Use `PWN::Plugins::YubiKey::OpenPGP.help` for all options.
+
+## Safety and connection ownership
+
+- Supply `connection:` with `descriptor[:protocol] == :apdu`. The caller owns
+  connection selection, exclusive access and closing. Use a secure-connection
+  wrapper when the selected device/interface requires SCP; never fall back to
+  plaintext automatically.
+- Pass literal `confirm: true` for **every** mutation, authentication attempt and
+  private-key operation. A compatibility `--force` argument is not consent.
+- Supply secrets as `pin:`, `admin_pin:`, `new_pin:`, `new_admin_pin:`, `reset_code:`
+  or `key_password:`. A `secret_provider:` callable receives only the field Symbol
+  for a required missing secret. Never put credentials in argv, logs or examples.
+- Validate input, key type, algorithm, curve, firmware and card-advertised
+  capabilities before authentication. Unsupported operations raise explicitly.
+- Do not replay a mutation or crypto request after timeout, failed authentication,
+  or a readback mismatch. A timeout can leave uncertain card state. Reset alone
+  deliberately exhausts PIN counters, bounded by observed counters or the
+  one-byte counter range during an explicitly requested corruption recovery.
+- Replacing keys or changing algorithm attributes may erase existing keys.
+  `fixed` and `cached-fixed` touch policy cannot be reversed without replacing
+  the key. Factory reset does **not** restore the attestation key/certificate.
+- PIN changes return freshly read retry counters and `credential_verified: false`:
+  secret values cannot be read back. Use a separate explicitly confirmed
+  `verify_pin` call if verifying the new credential is wanted.
+- Secrets are not persisted by this module. Ruby/OpenSSL allocation and garbage
+  collection do not guarantee zeroization of all temporary copies.
+
+## Management leaf operations
+
+`execute(args: [...], connection: connection, ...)` accepts the words **after**
+`openpgp`. Empty args and the `access`, `keys`, `certificates` groups return local
+help metadata without touching a connection. `operations` lists leaves only.
+
+| Leaf | Native operation and evidence |
+|---|---|
+| `info` | SELECT, GET VERSION, application DO 6E, signature-counter DO 7A, KDF DO F9 when advertised |
+| `reset` | Deliberate bounded PIN blocking, TERMINATE E6, ACTIVATE 44, fresh empty-key metadata readback |
+| `access set-retries USER RESET ADMIN` | Admin VERIFY 83, F2, fresh C4 readback; NEO PIN-reset side effect reported |
+| `access change-pin` | CHANGE REFERENCE DATA 24/81, fresh C4; requires `pin`, `new_pin` |
+| `access change-admin-pin` | CHANGE REFERENCE DATA 24/83, fresh C4; requires `admin_pin`, `new_admin_pin` |
+| `access change-reset-code` | Admin VERIFY, PUT DATA D3, fresh C4; requires `reset_code` |
+| `access unblock-pin` | RESET RETRY COUNTER 2C, P1=0 with reset code or P1=2 with admin authorization |
+| `access set-signature-policy always|once` | PUT DATA C4 with readback |
+| `keys info SLOT` | Parsed algorithm, origin, fingerprint, generation time and UIF metadata |
+| `keys set-touch SLOT POLICY` | GET/PUT DATA D6–D9, button byte 20, readback, fixed-policy protection |
+| `keys import SLOT FILE|-` | Native OpenSSL key parsing, import template 4D/7F48/5F48, PUT DATA ODD DB/3FFF, public-key readback |
+| `keys attest SLOT OUTPUT|-` | User VERIFY 81, proprietary 80/FB, certificate readback; SIG/DEC/AUT only |
+| `certificates export SLOT OUTPUT|-` | SELECT DATA A5 and GET DATA 7F21, or attestation DO FC |
+| `certificates import SLOT FILE|-` | Single PEM/DER X.509 parsing, certificate-limit validation, PUT DATA and exact DER readback |
+| `certificates delete SLOT` | Empty PUT DATA, empty-slot readback |
+
+Slots: `sig`, `dec`, `aut`, `att`; `enc` is an alias for `dec`. Touch policies:
+`off`, `on`, `fixed`, `cached`, `cached-fixed`. Export/attest accept `--format PEM`
+or `--format DER`; PEM is the default. Input `-` requires `key:` or `certificate:`
+in memory, not stdin. Output `-` returns bytes, not stdout. Named output files are
+created exclusively with mode 0600; existing paths are not overwritten.
+
+## Typed cryptographic APIs
+
+```ruby
+pgp = PWN::Plugins::YubiKey::OpenPGP
+
+# Read-only capability discovery and native OpenSSL public-key export.
+supported = pgp.algorithms(connection: connection)
+public_key = pgp.public_key(connection: connection, slot: :sig)
+
+# Explicitly destructive on-card generation; returns an OpenSSL public key.
+public_key = pgp.generate_key(
+  connection: connection, slot: :sig, algorithm: :secp256r1,
+  admin_pin: admin_pin, confirm: true
+)
+
+signature = pgp.sign(
+  connection: connection, message: message, hash_algorithm: :sha256,
+  pin: user_pin, confirm: true
+)
+authentication_signature = pgp.authenticate(
+  connection: connection, message: challenge, pin: user_pin, confirm: true
+)
+plaintext_or_shared_secret = pgp.decipher(
+  connection: connection, value: ciphertext_or_peer_public_key,
+  pin: user_pin, confirm: true
+)
+# decrypt is an alias to the same decipher implementation.
+```
+
+- RSA signing sends DigestInfo through PSO 2A/9E9A; authentication uses INTERNAL
+  AUTHENTICATE 88. RSA signatures are raw modulus-length bytes.
+- ECDSA signs a SHA digest; card `r || s` is checked and converted to DER.
+- Ed25519 sends the original message and returns raw 64-byte signatures.
+  `prehashed: true` is rejected for Ed25519. Other signing methods can accept
+  prehashed SHA-1/224/256/384/512 input of exactly the digest length.
+- RSA decipher sends the zero padding indicator before a modulus-length
+  PKCS1-v1_5 ciphertext. EC/X25519 decipher sends the A6/7F49/86 peer template
+  and returns the **raw shared secret**, not a decrypted OpenPGP message.
+- `verify_pin(mode: :signature|:extended|:admin, ...)` chooses PW1/81, PW1/82 or
+  PW3/83. `unverify_pin` clears that reference on firmware 5.6 or newer.
+- RSA2048/3072/4096, NIST P-256/384/521, secp256k1, Brainpool P256/P384/P512,
+  Ed25519 and X25519 are recognized. Actual generation/import support comes
+  from firmware restrictions and advertised FA entries, not merely host support.
+- NEO RSA imports use CRT components; 4.4 FIPS firmware is limited to RSA2048.
+  RSA generation is disabled on 4.2.0–4.3.4 vulnerable firmware.
+- PKCS8 Curve25519 import extracts the inner 32-byte seed/scalar natively;
+  X25519 reverses scalar bytes for the card. P-521 scalars use 66 bytes.
+- PIN KDF supports card-advertised iterated-and-salted S2K with SHA256/SHA512,
+  role-specific salts and bounded byte counts. Unknown KDFs never send plaintext.
+
+## Verification and boundaries
+
+Run the paired offline suite:
+
+```text
+bundle exec rspec spec/lib/pwn/plugins/yubikey/openpgp_spec.rb
+bundle exec rubocop lib/pwn/plugins/yubikey/openpgp.rb spec/lib/pwn/plugins/yubikey/openpgp_spec.rb
+```
+
+Tests use the actual shared Protocol plus a strict synthetic Connection, literal
+APDU fixtures, native OpenSSL keys, RFC seed material, host signature verification,
+certificate parsing, public-key equality and ECDH equality. They cover command and
+response chaining, version quirks, readback mismatch, malformed input, consent,
+missing secrets, incorrect PIN and timeout without replay. They do not establish
+USB/NFC interoperability or on-device behavior on every firmware/FIPS variant.
+
+This is the card application layer, not a keyring, OpenPGP packet/ASCII-armor
+encoder or signature/attestation trust-chain validator. RSA OAEP and symmetric
+OpenPGP message decryption are not implied by the card PKCS1/ECDH primitives.
+
+Protocol provenance: OpenPGP Card specification 3.4
+(<https://gnupg.org/ftp/specs/OpenPGP-smart-card-application-3.4.pdf>),
+Yubico YubiKey Manager 5.9.1 `yubikit/openpgp.py` and
+`ykman/_cli/openpgp.py` (<https://github.com/Yubico/yubikey-manager>).
+The cached official sources were consulted read-only, never used as runtime
+backends. Source attribution and the reference BSD license are retained in Ruby.