feat: Hardware Key Agent w/ PIN caching - fix cross-cluster support by Joerger · Pull Request #54144 · gravitational/teleport

Joerger · 2025-04-18T21:13:59Z

Part of RFD 199

Changes:

Replace the PINCachingPrompt with a more adaptive PINCache on the YubiKeyPIVService itself. This fixes cross-cluster and cluster-less (Connect home page) PIN caching when the service is used as a hardware key agent.
- The PIN cache is shared across different client key's with different pin_cache_ttls. Each key's ttl is taken into account when deciding whether to use a cached PIN or prompt for a PIN. This generally results in fewer and more consistent PIN prompts.
Tie the pin_cache_ttl of a key to it's key PEM file, rather than the profile. This value will get set at time of login, and can be reset to an updated value by re-logging in.
- This helps decouple the hardware key agent from the client store, avoiding issues like this race condition
Adds a max pin_cache_ttl of 1 hour to prevent abuse, especially over the hardware key agent.
- Note that PIV PIN caching is purely a client-side feature, so it is not possible to entirely prevent users from changing this limit, or enabling PIN caching on a cluster that doesn't enable it explicitly.

…Keys.

…set.

Joerger · 2025-04-21T23:46:54Z

@zmb3 @EdwardDowling @r0mant Friendly ping to review

Joerger · 2025-04-23T18:43:23Z

@zmb3 Friendly ping to re-review

zmb3 · 2025-04-23T19:23:52Z

+		return pin, nil
+	}
+
+	pin, err := prompt.AskPIN(ctx, requirement, keyInfo)


Should we add the 1 minute timeout here so an unanswered PIN prompt doesn't prevent all future operations from succeeding?

…54144)

* feat: Hardware Key Agent - Add `api/utils/keys/hardwarekey` package (#53671) * Move hardware key files into new hardwarekey package. * Tidy up PIVSlot logic and remove its piv-go dependency. * Add godoc comments to cliPrompt methods; Update cliprompt.go license year. * Add godocs. * feat: Hardware Key Agent - Add `hardwarekey.Service` interface with adapted PIV implementation (#53674) * Add hardware key service interface; Add mock service for tests. * Add piv implementation of hardware key service. * Remove old yubikey parsing logic in favor of hardwarekey.PrivateKeyRef. * Remove HardwareSigner in favor of hardwarekey.PrivateKey. * Add test; Cleanup comment; Don't require pin/touch prompts in tests with MockHarwdareKeyService by default. * Fix tests. * Add TODOs. * Use unhashed digest for WarmupHardwareKey. * Address comments. * Fix race condition in test service. * Address comments. * feat: Hardware Key Agent - Add `api/harwdarekey/piv` package (#53677) * Remove YubiKeyPrivateKey * Remove keys package dependencies from PIV implementation. * Move PIV implementation into new piv package. * Move newPrivateKey into YubiKeyService.NewPrivateKey. * * Clean up separation of concerns between YubiKey and YubiKeyService * Replace hardwarekey.PrivateKey cache with YubiKey cache for proper support for multiple clusters or yubikeys * Add YubiKey version field for use in version specific signature edge cases * Change sharedPIVConnection connection from an embedded field. * Address comments. * Add getKeyRef helper method. * feat: Hardware Key Agent - Enrich the PEM encoded hardware private key file (#53675) * Enrich hardware key PEM file. * Add test. * Validate PrivateKeyRef before/after encode/decode. * Update api/utils/keys/hardwarekey/hardwarekey.go Co-authored-by: STeve (Xin) Huang <xin.huang@goteleport.com> * Validate key ref in hardware key service implementations; Fix merge conflict. --------- Co-authored-by: STeve (Xin) Huang <xin.huang@goteleport.com> * feat: Hardware Key Agent - set hardware key service in client store (#53563) * Replace prompt in keystore with hardware key service in client store. * Add client StoreConfig and StoreConfigOpt. * Add client store and key store tests. * Provide nil service for ProfileStatus's AppsForCluster and DatabasesForCluster methods. * Address comments. * Fix test. * Fix test with cmp.Diff. * feat: Hardware Key Agent - Propagate contextual key info from key store to hardware key prompts (#53703) * Propagate contextual key info from key store through to hardware key prompts. * Remove HardwareKeyPromptConstructor. * Cleanup; add tests. * feat: Hardware Key Agent - consolidate globally shared PIV service variables (#53974) * Consolidate process-wide shared prompt mutex and yubikey connections into a shared YubiKeyService, which will also share the prompt. * Fix interactive piv service tests. * Fix wording on comment. * Move RemoveProfile and ListProfileNames into ProfileStore. (#53781) * feat: Hardware Key PIN caching (#53976) * Add PinCachingPrompt. * Add PINCacheTimeout to auth preference proto message. * Report PIVPINCacheTimeout through ping; Store PIVPINCacheTimeout in profile. * Set PIV pin cache timeout for tsh and teleterm. * Add SetPrompt and GetPrompt to hardware key service interface. * Cleanup; Add test. * Address comments. * Rename to PINCacheTTL. * Apply suggestions. * Fix lint. * Simplify randPIN for test. * Use math/rand/v2. * Update terraform docs. * Revert pin caching change for connect to fix race condition. (#54140) * feat: Hardware Key Agent (#54026) * Add HardwareKeyAgent proto service. * Add hardware key agent client and server implementation. * Add tsh piv agent command. * Use hardware key agent service when available. * * Add config option to Teleport connect to start the hardware key agent server * Add flag to tsh daemon command to start the hardware key agent server * Fix hardware key agent client connection for Windows. * Add hardware key agent service; Add tests. * Minor cleanup. * Move hardware key agent proto to /api. * * Restructure packages based on dependencies. * Add hardware key agent test coverage for RSA, ECDSA, and ED25519 keys. * Add PIV test coverage for RSA keys. * Fix lint. * Fix lint; Fix test. * Address comments. * Address comments. * Fix merge conflict. * feat: Hardware Key Agent - require users to configure certificate (#54118) * * Hardware key agent checks whether a key is configured for Teleport clients before performing a signature. * Add detailed error message and docs for configuring PIV slot certificate. * Add additional checks for mismatched public key on PIV slot, which can occur when generating a new key on a PIV slot with an active login session. * Update api/utils/keys/piv/yubikey.go Co-authored-by: Zac Bergquist <zac.bergquist@goteleport.com> * Apply suggestions from code review Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> --------- Co-authored-by: Zac Bergquist <zac.bergquist@goteleport.com> Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * Remove MaxUint32 call to fix builds on 32-bit systems. (#54125) * feat: Hardware Key Agent - command hint (#54090) * Supply command for context on hardware key prompt. * * Include command in Teleport Connect hardware key prompts, excluding tshd commands * Fix proxy host context passed to Teleport connect hardware key prompts * Only use direct service for `tsh login` to avoid jumping between clients * Add new line before command. * Fix story. * Address comments. * Trim forward slash for windows. * Change proxy_host to proxy_hostname; Update comment. * feat: Hardware Key Agent w/ PIN caching - fix cross-cluster support (#54144) * Style hardware key prompt with command in Connect (#54258) * Style hardware key prompt with command in Connect. * Move `CliCommand.tsx` to `components` * Extend stories with a command * Use `CliCommand` component, improve spacing * Wrap command in the dialog * End sentences with a dot * Add a gap between `CliCommand` and errors in `OnlineDocumentGateway` --------- Co-authored-by: Grzegorz Zdunek <grzegorz.zdunek@goteleport.com> * feat: Hardware Key Agent - fix socket replacement on Windows (#54126) * Prevent windows from trying to reuse the addr and getting a bind error. * Replace unresponsive windows unix sockets. * Explicitly check for error message instead of os.Stat. * Move windowsBindErrMessage. * Add cross-platform ErrAddrInUse constant. * Move error constants to hardwarekey package. * feat: Hardware Key Agent - initialize hardware key service at start of `tsh daemon` (#54226) * * Initialize shared hardware key service and client store for tshd * Replace CustomHardwareKeyPrompt with SetPrompt * Add lazy loaded tshd event service client and use it to initialize hardware key prompt early. * Address comments; Set TshdEventsClient in daemon service. * Fix test. * Fix potential race condition on global yubikey service prompt. * Add test. * Require ClientStore in `client.Config` (#54227) * Invert config.EnableEscapeSequences into config.DisableEscapeSequences so that the default value (false) results in the desired default behavior. * * Replace MakeDefaultClientConfig with CheckAndSetDefaults * Require ClientStore to be provided in config * Remove CustomHardwareKeyPrompt from config * Set client store in tests that were missing it. * Ensure tsh only initializes client store once. * Client config uses its own client store. * Replace uses of KeysDir with ClientStore. * Remove unused home apth for vnet process. * Remove unnecessary profile re-load and helper function. * Replace sync.Once with atomic; add get/setClientStore. * Fix uncaught merge conflict. * Fix test; Add comment for why we initialize the client store atomically. * Return error when using MemKeyStore for tsh puttyconfig. * Fix merge conflict. * feat: PIV PIN Caching - add file config option (#54328) * Add pin_cache_ttl as file config option. * Add test. * Update lib/config/fileconf.go Co-authored-by: Bernard Kim <bernard@goteleport.com> --------- Co-authored-by: Bernard Kim <bernard@goteleport.com> * Restore namespace in client config. --------- Co-authored-by: STeve (Xin) Huang <xin.huang@goteleport.com> Co-authored-by: Zac Bergquist <zac.bergquist@goteleport.com> Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> Co-authored-by: Grzegorz Zdunek <grzegorz.zdunek@goteleport.com> Co-authored-by: Bernard Kim <bernard@goteleport.com>

* feat: Hardware Key Agent - Add `api/utils/keys/hardwarekey` package (#53671) * Move hardware key files into new hardwarekey package. * Tidy up PIVSlot logic and remove its piv-go dependency. * Add godoc comments to cliPrompt methods; Update cliprompt.go license year. * Add godocs. * feat: Hardware Key Agent - Add `hardwarekey.Service` interface with adapted PIV implementation (#53674) * Add hardware key service interface; Add mock service for tests. * Add piv implementation of hardware key service. * Remove old yubikey parsing logic in favor of hardwarekey.PrivateKeyRef. * Remove HardwareSigner in favor of hardwarekey.PrivateKey. * Add test; Cleanup comment; Don't require pin/touch prompts in tests with MockHarwdareKeyService by default. * Fix tests. * Add TODOs. * Use unhashed digest for WarmupHardwareKey. * Address comments. * Fix race condition in test service. * Address comments. * feat: Hardware Key Agent - Add `api/harwdarekey/piv` package (#53677) * Remove YubiKeyPrivateKey * Remove keys package dependencies from PIV implementation. * Move PIV implementation into new piv package. * Move newPrivateKey into YubiKeyService.NewPrivateKey. * * Clean up separation of concerns between YubiKey and YubiKeyService * Replace hardwarekey.PrivateKey cache with YubiKey cache for proper support for multiple clusters or yubikeys * Add YubiKey version field for use in version specific signature edge cases * Change sharedPIVConnection connection from an embedded field. * Address comments. * Add getKeyRef helper method. * Rename NewSoftwarePrivateKey to NewPrivateKey (#53598) * feat: Hardware Key Agent - Enrich the PEM encoded hardware private key file (#53675) * Enrich hardware key PEM file. * Add test. * Validate PrivateKeyRef before/after encode/decode. * Update api/utils/keys/hardwarekey/hardwarekey.go Co-authored-by: STeve (Xin) Huang <xin.huang@goteleport.com> * Validate key ref in hardware key service implementations; Fix merge conflict. --------- Co-authored-by: STeve (Xin) Huang <xin.huang@goteleport.com> * feat: Hardware Key Agent - set hardware key service in client store (#53563) * Replace prompt in keystore with hardware key service in client store. * Add client StoreConfig and StoreConfigOpt. * Add client store and key store tests. * Provide nil service for ProfileStatus's AppsForCluster and DatabasesForCluster methods. * Address comments. * Fix test. * Fix test with cmp.Diff. * feat: Hardware Key Agent - Propagate contextual key info from key store to hardware key prompts (#53703) * Propagate contextual key info from key store through to hardware key prompts. * Remove HardwareKeyPromptConstructor. * Cleanup; add tests. * feat: Hardware Key Agent - consolidate globally shared PIV service variables (#53974) * Consolidate process-wide shared prompt mutex and yubikey connections into a shared YubiKeyService, which will also share the prompt. * Fix interactive piv service tests. * Fix wording on comment. * Move RemoveProfile and ListProfileNames into ProfileStore. (#53781) * feat: Hardware Key PIN caching (#53976) * Add PinCachingPrompt. * Add PINCacheTimeout to auth preference proto message. * Report PIVPINCacheTimeout through ping; Store PIVPINCacheTimeout in profile. * Set PIV pin cache timeout for tsh and teleterm. * Add SetPrompt and GetPrompt to hardware key service interface. * Cleanup; Add test. * Address comments. * Rename to PINCacheTTL. * Apply suggestions. * Fix lint. * Simplify randPIN for test. * Use math/rand/v2. * Update terraform docs. * Revert pin caching change for connect to fix race condition. (#54140) * feat: Hardware Key Agent (#54026) * Add HardwareKeyAgent proto service. * Add hardware key agent client and server implementation. * Add tsh piv agent command. * Use hardware key agent service when available. * * Add config option to Teleport connect to start the hardware key agent server * Add flag to tsh daemon command to start the hardware key agent server * Fix hardware key agent client connection for Windows. * Add hardware key agent service; Add tests. * Minor cleanup. * Move hardware key agent proto to /api. * * Restructure packages based on dependencies. * Add hardware key agent test coverage for RSA, ECDSA, and ED25519 keys. * Add PIV test coverage for RSA keys. * Fix lint. * Fix lint; Fix test. * Address comments. * Address comments. * Fix merge conflict. * feat: Hardware Key Agent - require users to configure certificate (#54118) * * Hardware key agent checks whether a key is configured for Teleport clients before performing a signature. * Add detailed error message and docs for configuring PIV slot certificate. * Add additional checks for mismatched public key on PIV slot, which can occur when generating a new key on a PIV slot with an active login session. * Update api/utils/keys/piv/yubikey.go Co-authored-by: Zac Bergquist <zac.bergquist@goteleport.com> * Apply suggestions from code review Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> --------- Co-authored-by: Zac Bergquist <zac.bergquist@goteleport.com> Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * Remove MaxUint32 call to fix builds on 32-bit systems. (#54125) * feat: Hardware Key Agent - command hint (#54090) * Supply command for context on hardware key prompt. * * Include command in Teleport Connect hardware key prompts, excluding tshd commands * Fix proxy host context passed to Teleport connect hardware key prompts * Only use direct service for `tsh login` to avoid jumping between clients * Add new line before command. * Fix story. * Address comments. * Trim forward slash for windows. * Change proxy_host to proxy_hostname; Update comment. * feat: Hardware Key Agent w/ PIN caching - fix cross-cluster support (#54144) * Style hardware key prompt with command in Connect (#54258) * Style hardware key prompt with command in Connect. * Move `CliCommand.tsx` to `components` * Extend stories with a command * Use `CliCommand` component, improve spacing * Wrap command in the dialog * End sentences with a dot * Add a gap between `CliCommand` and errors in `OnlineDocumentGateway` --------- Co-authored-by: Grzegorz Zdunek <grzegorz.zdunek@goteleport.com> * feat: Hardware Key Agent - fix socket replacement on Windows (#54126) * Prevent windows from trying to reuse the addr and getting a bind error. * Replace unresponsive windows unix sockets. * Explicitly check for error message instead of os.Stat. * Move windowsBindErrMessage. * Add cross-platform ErrAddrInUse constant. * Move error constants to hardwarekey package. * feat: Hardware Key Agent - initialize hardware key service at start of `tsh daemon` (#54226) * * Initialize shared hardware key service and client store for tshd * Replace CustomHardwareKeyPrompt with SetPrompt * Add lazy loaded tshd event service client and use it to initialize hardware key prompt early. * Address comments; Set TshdEventsClient in daemon service. * Fix test. * Fix potential race condition on global yubikey service prompt. * Add test. * Require ClientStore in `client.Config` (#54227) * Invert config.EnableEscapeSequences into config.DisableEscapeSequences so that the default value (false) results in the desired default behavior. * * Replace MakeDefaultClientConfig with CheckAndSetDefaults * Require ClientStore to be provided in config * Remove CustomHardwareKeyPrompt from config * Set client store in tests that were missing it. * Ensure tsh only initializes client store once. * Client config uses its own client store. * Replace uses of KeysDir with ClientStore. * Remove unused home apth for vnet process. * Remove unnecessary profile re-load and helper function. * Replace sync.Once with atomic; add get/setClientStore. * Fix uncaught merge conflict. * Fix test; Add comment for why we initialize the client store atomically. * Return error when using MemKeyStore for tsh puttyconfig. * Fix merge conflict. * feat: PIV PIN Caching - add file config option (#54328) * Add pin_cache_ttl as file config option. * Add test. * Update lib/config/fileconf.go Co-authored-by: Bernard Kim <bernard@goteleport.com> --------- Co-authored-by: Bernard Kim <bernard@goteleport.com> * Restore namespace in client config. --------- Co-authored-by: STeve (Xin) Huang <xin.huang@goteleport.com> Co-authored-by: Zac Bergquist <zac.bergquist@goteleport.com> Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> Co-authored-by: Grzegorz Zdunek <grzegorz.zdunek@goteleport.com> Co-authored-by: Bernard Kim <bernard@goteleport.com>

github-actions Bot added size/sm tsh tsh - Teleport's command line tool for logging into nodes running Teleport. labels Apr 18, 2025

Joerger requested review from rosstimothy and zmb3 April 18, 2025 21:14

github-actions Bot requested review from EdwardDowling and r0mant April 18, 2025 21:14

Joerger force-pushed the joerger/key-specific-pin-caching branch from b9c4894 to 97f2746 Compare April 18, 2025 21:16

Joerger added 8 commits April 18, 2025 14:34

Add hardware key PINCache.

9a72fb1

Remove PINCachingPrompt.

bf4f475

Set PINCacheTTL in key ref.

af62d04

Add PINCache to cli and teleterm hardware key prompts.

d7023d6

Resore signMu.

bb4ca2a

Pass pin cache TTL in hardware key agent sign requests.

1cefa23

Move pinCache to YubiKey struct to maintain support for multiple Yubi…

e4afebd

…Keys.

Enforce max PIV PIN cache TTL of 1 hour.

f478201

Joerger force-pushed the joerger/key-specific-pin-caching branch from 97f2746 to f478201 Compare April 18, 2025 21:37

Joerger added the no-changelog Indicates that a PR does not require a changelog entry label Apr 18, 2025

Joerger mentioned this pull request Apr 18, 2025

Hardware Key Agent w/ PIN caching tracker #53704

Closed

rosstimothy reviewed Apr 21, 2025

View reviewed changes

Comment thread api/types/authentication.go Outdated

Comment thread api/utils/keys/hardwarekey/pincache.go Outdated

Comment thread api/utils/keys/hardwarekeyagent/agent.go Outdated

Joerger requested a review from rosstimothy April 21, 2025 18:55

Joerger added 3 commits April 21, 2025 12:27

Remove unused fields.

1f394d7

Ensure a new goroutine is not started when pin expiration is already …

936cbfb

…set.

Update error message.

a213ea7

Joerger force-pushed the joerger/key-specific-pin-caching branch from 0a1a5f1 to a213ea7 Compare April 21, 2025 19:28

rosstimothy reviewed Apr 21, 2025

View reviewed changes

Comment thread api/utils/keys/hardwarekey/cliprompt.go

Comment thread api/utils/keys/hardwarekey/pincache.go Outdated

Remove goroutine.

4afbec4

Joerger requested a review from rosstimothy April 21, 2025 21:07

rosstimothy approved these changes Apr 21, 2025

View reviewed changes

Merge branch 'master' into joerger/key-specific-pin-caching

64df837

Joerger requested a review from zmb3 April 22, 2025 19:17

Joerger mentioned this pull request Apr 22, 2025

Move hardware key change pin stderr message to cliPrompt #54207

Merged

Merge branch 'master' into joerger/key-specific-pin-caching

8f19a0d

zmb3 reviewed Apr 23, 2025

View reviewed changes

Joerger added a commit that referenced this pull request Apr 23, 2025

feat: Hardware Key Agent w/ PIN caching - fix cross-cluster support (#…

33417ef

…54144)

Add prompt timeout.

3c99ace

Joerger requested a review from zmb3 April 23, 2025 20:26

zmb3 approved these changes Apr 23, 2025

View reviewed changes

public-teleport-github-review-bot Bot removed request for EdwardDowling and r0mant April 23, 2025 22:44

Joerger added this pull request to the merge queue Apr 23, 2025

Merged via the queue into master with commit 2be659d Apr 23, 2025
43 checks passed

Joerger deleted the joerger/key-specific-pin-caching branch April 23, 2025 23:06

Joerger added a commit that referenced this pull request Apr 24, 2025

feat: Hardware Key Agent w/ PIN caching - fix cross-cluster support (#…

52fc073

…54144)

Joerger added a commit that referenced this pull request Apr 25, 2025

feat: Hardware Key Agent w/ PIN caching - fix cross-cluster support (#…

667ce33

…54144)

Joerger mentioned this pull request Apr 25, 2025

[v17] Hardware Key Agent w/ PIN caching #54297

Merged

Joerger added a commit that referenced this pull request Apr 25, 2025

feat: Hardware Key Agent w/ PIN caching - fix cross-cluster support (#…

b6ae004

…54144)

Joerger added a commit that referenced this pull request Apr 25, 2025

feat: Hardware Key Agent w/ PIN caching - fix cross-cluster support (#…

39d1064

…54144)

Joerger mentioned this pull request Apr 25, 2025

[v16] Hardware Key Agent w/ PIN caching #54298

Merged

Joerger added a commit that referenced this pull request Apr 25, 2025

feat: Hardware Key Agent w/ PIN caching - fix cross-cluster support (#…

1c18915

…54144)

Joerger added a commit that referenced this pull request Apr 25, 2025

feat: Hardware Key Agent w/ PIN caching - fix cross-cluster support (#…

dfcd155

…54144)

Joerger added a commit that referenced this pull request Apr 25, 2025

feat: Hardware Key Agent w/ PIN caching - fix cross-cluster support (#…

013e3e3

…54144)

Joerger added a commit that referenced this pull request Apr 28, 2025

feat: Hardware Key Agent w/ PIN caching - fix cross-cluster support (#…

3f54c21

…54144)

Joerger added a commit that referenced this pull request Apr 28, 2025

feat: Hardware Key Agent w/ PIN caching - fix cross-cluster support (#…

03b5e4b

…54144)

Joerger added a commit that referenced this pull request Apr 28, 2025

feat: Hardware Key Agent w/ PIN caching - fix cross-cluster support (#…

51e7249

…54144)

Joerger added a commit that referenced this pull request Apr 28, 2025

feat: Hardware Key Agent w/ PIN caching - fix cross-cluster support (#…

7b5ff9b

…54144)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Hardware Key Agent w/ PIN caching - fix cross-cluster support#54144

feat: Hardware Key Agent w/ PIN caching - fix cross-cluster support#54144
Joerger merged 17 commits intomasterfrom
joerger/key-specific-pin-caching

Joerger commented Apr 18, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Joerger commented Apr 21, 2025

Uh oh!

Joerger commented Apr 23, 2025

Uh oh!

zmb3 Apr 23, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Joerger commented Apr 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Joerger commented Apr 21, 2025

Uh oh!

Joerger commented Apr 23, 2025

Uh oh!

zmb3 Apr 23, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Joerger commented Apr 18, 2025 •

edited

Loading