feat: Hardware Key Agent - Add api/utils/keys/hardwarekey package

api/client/webclient/webclient.go

@@ -45,6 +45,7 @@ import (
 	"github.com/gravitational/teleport/api/types"
 	"github.com/gravitational/teleport/api/utils"
 	"github.com/gravitational/teleport/api/utils/keys"
+	"github.com/gravitational/teleport/api/utils/keys/hardwarekey"
 )
 
 const (
@@ -528,7 +529,7 @@ type AuthenticationSettings struct {
 	// PrivateKeyPolicy contains the cluster-wide private key policy.
 	PrivateKeyPolicy keys.PrivateKeyPolicy `json:"private_key_policy"`
 	// PIVSlot specifies a specific PIV slot to use with hardware key support.
-	PIVSlot keys.PIVSlot `json:"piv_slot"`
+	PIVSlot hardwarekey.PIVSlotKeyString `json:"piv_slot"`
 	// DeviceTrust holds cluster-wide device trust settings.
 	DeviceTrust DeviceTrustSettings `json:"device_trust,omitempty"`
 	// HasMessageOfTheDay is a flag indicating that the cluster has MOTD

api/profile/profile.go

@@ -35,6 +35,7 @@ import (
 	"github.com/gravitational/teleport/api/defaults"
 	"github.com/gravitational/teleport/api/utils/keypaths"
 	"github.com/gravitational/teleport/api/utils/keys"
+	"github.com/gravitational/teleport/api/utils/keys/hardwarekey"
 	"github.com/gravitational/teleport/api/utils/sshutils"
 )
 
@@ -107,7 +108,7 @@ type Profile struct {
 	PrivateKeyPolicy keys.PrivateKeyPolicy `yaml:"private_key_policy"`
 
 	// PIVSlot is a specific piv slot that Teleport clients should use for hardware key support.
-	PIVSlot keys.PIVSlot `yaml:"piv_slot"`
+	PIVSlot hardwarekey.PIVSlotKeyString `yaml:"piv_slot"`
 
 	// MissingClusterDetails means this profile was created with limited cluster details.
 	// Missing cluster details should be loaded into the profile by pinging the proxy.

api/types/authentication.go

@@ -32,6 +32,7 @@ import (
 	"github.com/gravitational/teleport/api/defaults"
 	"github.com/gravitational/teleport/api/utils"
 	"github.com/gravitational/teleport/api/utils/keys"
+	"github.com/gravitational/teleport/api/utils/keys/hardwarekey"
 	"github.com/gravitational/teleport/api/utils/tlsutils"
 )
 
@@ -134,7 +135,7 @@ type AuthPreference interface {
 	// GetHardwareKey returns the hardware key settings configured for the cluster.
 	GetHardwareKey() (*HardwareKey, error)
 	// GetPIVSlot returns the configured piv slot for the cluster.
-	GetPIVSlot() keys.PIVSlot
+	GetPIVSlot() hardwarekey.PIVSlotKeyString
 	// GetHardwareKeySerialNumberValidation returns the cluster's hardware key
 	// serial number validation settings.
 	GetHardwareKeySerialNumberValidation() (*HardwareKeySerialNumberValidation, error)
@@ -491,9 +492,9 @@ func (c *AuthPreferenceV2) GetHardwareKey() (*HardwareKey, error) {
 }
 
 // GetPIVSlot returns the configured piv slot for the cluster.
-func (c *AuthPreferenceV2) GetPIVSlot() keys.PIVSlot {
+func (c *AuthPreferenceV2) GetPIVSlot() hardwarekey.PIVSlotKeyString {
 	if hk, err := c.GetHardwareKey(); err == nil {
-		return keys.PIVSlot(hk.PIVSlot)
+		return hardwarekey.PIVSlotKeyString(hk.PIVSlot)
 	}
 	return ""
 }
@@ -840,7 +841,7 @@ func (c *AuthPreferenceV2) CheckAndSetDefaults() error {
 	}
 
 	if hk, err := c.GetHardwareKey(); err == nil && hk.PIVSlot != "" {
-		if err := keys.PIVSlot(hk.PIVSlot).Validate(); err != nil {
+		if err := hardwarekey.PIVSlotKeyString(hk.PIVSlot).Validate(); err != nil {
 			return trace.Wrap(err)
 		}
 	}

api/utils/keys/alias.go

@@ -0,0 +1,26 @@
+/*
+Copyright 2025 Gravitational, Inc.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+    http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package keys
+
+import "github.com/gravitational/teleport/api/utils/keys/hardwarekey"
+
+// Temporary aliases for types moved to the hardwarekey or piv packages
+// TODO(Joerger): Remove once /e no longer relies on them.
+
+// AttestationStatement is an attestation statement for a hardware private key
+// that supports json marshaling through the standard json/encoding package.
+type AttestationStatement = hardwarekey.AttestationStatement
+
+// AttestationStatementFromProto converts an AttestationStatement from its protobuf form.
+var AttestationStatementFromProto = hardwarekey.AttestationStatementFromProto

api/utils/keys/hardwarekey/attestation.go

@@ -0,0 +1,50 @@
+// Copyright 2025 Gravitational, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package hardwarekey
+
+import (
+	"bytes"
+
+	"github.com/gogo/protobuf/jsonpb"
+	"github.com/gravitational/trace"
+
+	attestationv1 "github.com/gravitational/teleport/api/gen/proto/go/attestation/v1"
+)
+
+// AttestationStatement is an attestation statement for a hardware private key
+// that supports json marshaling through the standard json/encoding package.
+type AttestationStatement attestationv1.AttestationStatement
+
+// ToProto converts this AttestationStatement to its protobuf form.
+func (a *AttestationStatement) ToProto() *attestationv1.AttestationStatement {
+	return (*attestationv1.AttestationStatement)(a)
+}
+
+// AttestationStatementFromProto converts an AttestationStatement from its protobuf form.
+func AttestationStatementFromProto(att *attestationv1.AttestationStatement) *AttestationStatement {
+	return (*AttestationStatement)(att)
+}
+
+// MarshalJSON implements custom protobuf json marshaling.
+func (a *AttestationStatement) MarshalJSON() ([]byte, error) {
+	buf := new(bytes.Buffer)
+	err := (&jsonpb.Marshaler{}).Marshal(buf, a.ToProto())
+	return buf.Bytes(), trace.Wrap(err)
+}
+
+// UnmarshalJSON implements custom protobuf json unmarshaling.
+func (a *AttestationStatement) UnmarshalJSON(buf []byte) error {
+	return (&jsonpb.Unmarshaler{AllowUnknownFields: true}).Unmarshal(bytes.NewReader(buf), a.ToProto())
+}