{"record":{"id":"fda908922ad6f3e1","repo":"gravitational/teleport","slug":"piv-is-unavailable-in-current-build","errorCode":null,"errorMessage":"PIV is unavailable in current build","messagePattern":"PIV is unavailable in current build","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"api/utils/keys/piv/service_unavailable.go","lineNumber":30,"sourceCode":"// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage piv\n\nimport (\n\t\"context\"\n\t\"crypto\"\n\t\"errors\"\n\t\"io\"\n\n\t\"github.com/gravitational/trace\"\n\n\t\"github.com/gravitational/teleport/api/utils/keys/hardwarekey\"\n)\n\nvar errPIVUnavailable = errors.New(\"PIV is unavailable in current build\")\n\nfunc NewYubiKeyService(_ hardwarekey.Prompt) *unavailableYubiKeyPIVService {\n\treturn &unavailableYubiKeyPIVService{}\n}\n\ntype unavailableYubiKeyPIVService struct{}\n\nfunc (s *unavailableYubiKeyPIVService) NewPrivateKey(_ context.Context, _ hardwarekey.PrivateKeyConfig) (*hardwarekey.Signer, error) {\n\treturn nil, trace.Wrap(errPIVUnavailable)\n}\n\n// Sign performs a cryptographic signature using the specified hardware\n// private key and provided signature parameters.\nfunc (s *unavailableYubiKeyPIVService) Sign(_ context.Context, _ *hardwarekey.PrivateKeyRef, _ hardwarekey.ContextualKeyInfo, _ io.Reader, _ []byte, _ crypto.SignerOpts) ([]byte, error) {\n\treturn nil, trace.Wrap(errPIVUnavailable)\n}\n\nfunc (s *unavailableYubiKeyPIVService) SetPrompt(_ hardwarekey.Prompt) {}","sourceCodeStart":12,"sourceCodeEnd":48,"githubUrl":"https://github.com/gravitational/teleport/blob/1283425b60ec5f60d509ba4c791183d452923ff7/api/utils/keys/piv/service_unavailable.go#L12-L48","documentation":"In builds compiled without PIV/CGO support (no native YubiKey PIV library linked), NewYubiKeyService returns an unavailableYubiKeyPIVService stub whose every operation (NewPrivateKey, Sign) fails with errPIVUnavailable. It signals that hardware-key PIV functionality is not present in this binary, not that the YubiKey itself is broken.","triggerScenarios":"Calling piv.NewPrivateKey to generate/store a private key on a YubiKey, or piv.Sign to sign with one, while running a Teleport binary built without the PIV build tag / CGO (e.g. pure-Go release builds, Windows/Linux non-cgo builds).","commonSituations":"Using tsh or tbot built without CGO on a machine expecting YubiKey hardware key support; switching from a cgo-enabled build to a lightweight build; container images without libpcsclite/PIV dependencies compiled in.","solutions":["Rebuild/install the Teleport binary with CGO and PIV support (the appropriate build tag, e.g. `piv`, with CGO_ENABLED=1).","If hardware keys are not required, avoid the PIV code path or configure the client to use software keys instead.","Check `tsh version`/build flavor to confirm PIV support is compiled in before prompting users for YubiKey operations."],"exampleFix":"// before\ngo build -tags piv ./tool/tsh // CGO disabled so PIV stub is used\n\n// after\nCGO_ENABLED=1 go build -tags piv ./tool/tsh","handlingStrategy":"fallback","validationCode":"if !piv.Available() { return errors.New(\"this binary lacks YubiKey PIV support; use a cgo/piv build\") }","typeGuard":"_, ok := svc.(*piv.YubiKeyPIVService); if !ok { /* stub: PIV unavailable */ }","tryCatchPattern":"signer, err := svc.NewPrivateKey(ctx, cfg)\nif err != nil && strings.Contains(err.Error(), \"PIV is unavailable\") {\n    return fmt.Errorf(\"PIV support missing in this build; rebuild with CGO and the piv tag: %w\", err)\n}","preventionTips":["Ship CGO-enabled, piv-tagged binaries wherever YubiKey hardware keys are used.","Feature-detect PIV availability at startup and disable hardware-key prompts early.","Document build flavors so operators know which builds support PIV."],"tags":["hardware-keys","yubikey","build-config","cgo"],"backgroundTag":"feature-unavailable-in-build","analyzedSha":"1283425b60ec5f60d509ba4c791183d452923ff7","analyzedAt":"2026-09-02T04:06:41.601Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}