teleport/lib/boundkeypair/bound_keypair.go

/*
 * Teleport
 * Copyright (C) 2025  Gravitational, Inc.
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

package boundkeypair

import (
	"crypto"
	"crypto/subtle"
	"time"

	"github.com/go-jose/go-jose/v3/jwt"
	"github.com/gravitational/trace"
	"github.com/jonboulle/clockwork"

	"github.com/gravitational/teleport/lib/defaults"
	"github.com/gravitational/teleport/lib/utils"
)

const (
	// challengeExpiration is the TTL for a bound keypair challenge document
	// once generated by the server, used to calculate the JWT `exp` field.
	challengeExpiration time.Duration = time.Minute

	// challengeNotBeforeOffset is the offset applied to the `nbf` field to
	// allow for a small amount of clock drift.
	challengeNotBeforeOffset = -10 * time.Second
)

// RecoveryMode is a recovery configuration mode
type RecoveryMode string

const (
	// RecoveryModeStandard is the standard recovery mode, and enforces the
	// recovery count limit and verifies client state.
	RecoveryModeStandard RecoveryMode = "standard"

	// RecoveryModeRelaxed does not enforce the recovery count limit, but still
	// verifies client state.
	RecoveryModeRelaxed = "relaxed"

	// RecoveryModeInsecure does enforces neither the recovery count limit nor
	// the client state.
	RecoveryModeInsecure = "insecure"
)

// RecoveryModes returns a list of all supported recovery modes
func RecoveryModes() []RecoveryMode {
	return []RecoveryMode{
		RecoveryModeStandard,
		RecoveryModeRelaxed,
		RecoveryModeInsecure,
	}
}

// RecoveryModeStrings returns a list of all supported recovery modes, typed as
// strings appropriate for use in CLI libraries.
func RecoveryModeStrings() []string {
	return []string{
		string(RecoveryModeStandard),
		string(RecoveryModeRelaxed),
		string(RecoveryModeInsecure),
	}
}

// ParseRecoveryMode parses a recovery mode from its string form.
func ParseRecoveryMode(s string) (RecoveryMode, error) {
	switch s {
	case RecoveryModeInsecure:
		return RecoveryModeInsecure, nil
	case RecoveryModeRelaxed:
		return RecoveryModeRelaxed, nil
	case "", string(RecoveryModeStandard):
		return RecoveryModeStandard, nil
	default:
		return "", trace.BadParameter("invalid recovery mode: %s", s)
	}
}

// ChallengeDocument is a bound keypair challenge document. These documents are
// sent in JSON form to clients attempting to authenticate, and are expected to
// be sent back signed with the private counterpart of a known public key.
type ChallengeDocument struct {
	*jwt.Claims

	// Nonce is a secure random string, unique to a particular challenge
	Nonce string `json:"nonce"`
}

// ChallengeValidator is used to issue and validate bound keypair challenges for
// a given public key.
type ChallengeValidator struct {
	clock clockwork.Clock

	subject     string
	clusterName string
	publicKey   crypto.PublicKey
}

// NewChallengeValidator creates a new challenge validation helper using the
// given subject, cluster name, and public key. Subjects are arbitrary but a
// public key ID is recommended.
func NewChallengeValidator(
	subject string,
	clusterName string,
	publicKey crypto.PublicKey,
) (*ChallengeValidator, error) {
	return &ChallengeValidator{
		clock: clockwork.NewRealClock(),

		subject:     subject,
		clusterName: clusterName,

		// TODO: API design issue to consider when implementing rotation: the
		// public key will change during rotation. Should a new validator be
		// created, or can we design this better?
		publicKey: publicKey,
	}, nil
}

// IssueChallenge generates a new challenge document using the configured clock.
func (v *ChallengeValidator) IssueChallenge() (*ChallengeDocument, error) {
	// Implementation note: these challenges are only ever sent to a single
	// client once, and we expect a valid reply as the next exchange in the
	// join ceremony. There is not an opportunity for reuse, multiple attempts,
	// or for clients to select their own nonce, so we won't bother storing it.
	nonce, err := utils.CryptoRandomHex(defaults.TokenLenBytes)
	if err != nil {
		return nil, trace.Wrap(err, "generating nonce")
	}

	return &ChallengeDocument{
		Claims: &jwt.Claims{
			Issuer:    v.clusterName,
			Audience:  jwt.Audience{v.clusterName}, // the cluster is both the issuer and audience
			NotBefore: jwt.NewNumericDate(v.clock.Now().Add(challengeNotBeforeOffset)),
			IssuedAt:  jwt.NewNumericDate(v.clock.Now()),
			Expiry:    jwt.NewNumericDate(v.clock.Now().Add(challengeExpiration)),
			Subject:   v.subject,
		},
		Nonce: nonce,
	}, nil
}

// ValidateChallengeResponse validates a signed challenge document, ensuring the
// signature matches the requested public key, and that the claims pass JWT
// validation.
func (v *ChallengeValidator) ValidateChallengeResponse(issued *ChallengeDocument, compactResponse string) error {
	token, err := jwt.ParseSigned(compactResponse)
	if err != nil {
		return trace.Wrap(err, "parsing signed response")
	}

	var document ChallengeDocument
	if err := token.Claims(v.publicKey, &document); err != nil {
		return trace.Wrap(err)
	}

	// Validate the challenge document claims per JWT rules.
	const leeway time.Duration = time.Minute
	if err := document.Claims.ValidateWithLeeway(jwt.Expected{
		Issuer:   v.clusterName,
		Subject:  v.subject,
		Audience: jwt.Audience{v.clusterName},
		Time:     v.clock.Now(),
	}, leeway); err != nil {
		return trace.Wrap(err, "validating challenge claims")
	}

	// JWT validation won't check equality on the time fields, so we'll manually
	// check them.
	if !issued.Claims.IssuedAt.Time().Equal(document.Claims.IssuedAt.Time()) {
		return trace.AccessDenied("invalid challenge document")
	}
	if !issued.Claims.Expiry.Time().Equal(document.Claims.Expiry.Time()) {
		return trace.AccessDenied("invalid challenge document")
	}
	if !issued.Claims.NotBefore.Time().Equal(document.Claims.NotBefore.Time()) {
		return trace.AccessDenied("invalid challenge document")
	}

	if subtle.ConstantTimeCompare([]byte(issued.Nonce), []byte(document.Nonce)) == 0 {
		return trace.AccessDenied("invalid nonce")
	}

	return nil
}