feat: Hardware Key Agent - Add api/harwdarekey/piv package

[Joerger]

Part of RFD 199

I recommend reviewing commit by commit, some of the diffs do not line up in the full diff.

Changes:

• Move the PIV implementation into the new piv package
  • Remove keys package dependencies from the implementation
    • keys.PrivateKeyPolicy -> hardwarekey.PromptPolicy
    • keys.PrivateKey -> hardwarekey.PrivateKey
• Replace YubiKeyPrivateKey with a more service-like approach (YubiKey.Sign(privateKeyRef))
• Replace high level PrivateKey cache with a more well-rounded YubiKey cache.
  • This fixes cross-cluster / cross-yubikey functionality, e.g. if you use 2 different YubiKeys for 2 different cluster logins in Connect.
• Cleanup / separation of concerns between YubiKey and YubiKeyService
  • Remove prompt field from YubiKey, move prompt logic to YubiKeyService with promptMux to defend against over-prompting
  • Move private key generation logic into YubiKeyService.NewPrivateKey
  • Make YubiKey.sharedConnection a non-embedded field so that unintended methods are not exposed.

Depends on #53674

[zmb3]

Is the api module the best place for this code, or should it just be a package under lib/?

Do we need it to be under a utils directory?

[Joerger]

Is the api module the best place for this code, or should it just be a package under lib/?

It's needed for the api/client and integrations to handle hardware key support.

Do we need it to be under a utils directory?

api/utils/keys depends on the package, so I was wary of moving it out of there where it could be more likely to catch us in an import cycle in the future. But it's probably fine to move it to api/hardwarekey/piv.

[Joerger]

@zmb3 on second thought I think I'm going to keep this in api/utils/keys/piv, for this PR. I'd be happy to move this to an agreed upon location once this and related PRs (#53671, #53674, #53675) get merged, but moving it now is a bit of a merge conflict nightmare.

At the very least, moving this logic which was in api/utils/keys to api/utils/keys/piv is a step in the right direction.

[bl-nero]

I don't understand this part. You wrote above that a PIV connection needs to be shared, yet here, it's created separately for each YubiKey created.

[Joerger]

newYubiKey is only called once per yubikey.

[bl-nero]

Is the mutex supposed to be held at this moment? If yes, can we either document this requirement in the function comment, or make the function private?

[Joerger]

teleport/api/utils/keys/yubikey.go

Lines 93 to 99 in 26b43c2

	// If the program has already retrieved and cached this key, return it.
	cachedKeysMu.Lock()
	defer cachedKeysMu.Unlock()
	if key, ok := cachedKeys[pivSlot]; ok && key.GetPrivateKeyPolicy() == requiredKeyPolicy {
	return key, nil
	}