pki

package

v0.2.0 Latest Latest Go to latest Published: Oct 3, 2026 License: MIT Imports: 9 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/osapi-io/osapi

Links

Open Source Insights

Documentation ¶

Overview ¶

Package pki provides Ed25519 keypair management for agent identity, including generation, loading, saving, signing, and verification.

Index ¶

Constants
func FingerprintOf(pubKey ed25519.PublicKey) string
func ParsePublicKeyPEM(pemData []byte) (ed25519.PublicKey, error)
func Verify(pubKey ed25519.PublicKey, data []byte, signature []byte) bool
type EnrollmentRequest
type EnrollmentResponse
type EnrollmentState
type Manager
- func New(fs avfs.VFS, keyDir string, keyPrefix string) *Manager

Constants ¶

View Source

const (
	// EnrollRequestSuffix is the NATS subject suffix for enrollment requests.
	EnrollRequestSuffix = "enroll.request"

	// EnrollResponsePrefix is the NATS subject prefix for enrollment responses.
	// Append ".<machineID>" to form the full subject.
	EnrollResponsePrefix = "enroll.response"

	// PKIRotateSuffix is the NATS subject suffix for key rotation notifications.
	PKIRotateSuffix = "pki.rotate"
)

Variables ¶

This section is empty.

Functions ¶

func FingerprintOf ¶

func FingerprintOf(
	pubKey ed25519.PublicKey,
) string

FingerprintOf returns the SHA256 fingerprint of the given public key in the format "SHA256:<hex>". Returns an empty string when the key is empty, so a record without a key never reports a fingerprint.

Callers that hold a bare public key rather than a Manager use this, which keeps one digest format across the codebase.

func ParsePublicKeyPEM ¶

func ParsePublicKeyPEM(
	pemData []byte,
) (ed25519.PublicKey, error)

ParsePublicKeyPEM parses a PEM-encoded Ed25519 public key.

func Verify ¶

func Verify(
	pubKey ed25519.PublicKey,
	data []byte,
	signature []byte,
) bool

Verify verifies the signature of the given data using the provided public key.

Types ¶

type EnrollmentRequest ¶

type EnrollmentRequest struct {
	MachineID   string `json:"machine_id"`
	Hostname    string `json:"hostname"`
	PublicKey   []byte `json:"public_key"`
	Fingerprint string `json:"fingerprint"`
}

EnrollmentRequest is sent by the agent to the controller.

type EnrollmentResponse ¶

type EnrollmentResponse struct {
	Accepted            bool   `json:"accepted"`
	ControllerPublicKey []byte `json:"controller_public_key,omitempty"`
	Reason              string `json:"reason,omitempty"`
}

EnrollmentResponse is sent by the controller to the agent.

type EnrollmentState ¶

type EnrollmentState string

EnrollmentState represents the agent's PKI enrollment state.

const (
	// StateUnregistered indicates the agent has not yet enrolled.
	StateUnregistered EnrollmentState = "unregistered"

	// StatePending indicates the agent has submitted an enrollment request.
	StatePending EnrollmentState = "pending"

	// StateAccepted indicates the controller has accepted the agent.
	StateAccepted EnrollmentState = "accepted"

	// StateRejected indicates the controller has rejected the agent.
	StateRejected EnrollmentState = "rejected"
)

type Manager ¶

type Manager struct {
	// contains filtered or unexported fields
}

Manager handles Ed25519 keypair lifecycle.

func New ¶

func New(
	fs avfs.VFS,
	keyDir string,
	keyPrefix string,
) *Manager

New creates a PKI Manager with the given filesystem, key directory path, and key prefix (e.g., "agent" or "controller"). The prefix determines the key filenames: {prefix}.key and {prefix}.pub.

func (*Manager) ControllerPublicKey ¶

func (m *Manager) ControllerPublicKey() ed25519.PublicKey

ControllerPublicKey returns the stored controller public key.

func (*Manager) Fingerprint ¶

func (m *Manager) Fingerprint() string

Fingerprint returns the SHA256 fingerprint of the public key in the format "SHA256:<hex>". Returns an empty string if no public key is set.

func (*Manager) LoadOrGenerate ¶

func (m *Manager) LoadOrGenerate() error

LoadOrGenerate loads existing PEM-encoded Ed25519 keys from disk, or generates and saves a new keypair if none exists.

func (*Manager) PreviousControllerPublicKey ¶

func (m *Manager) PreviousControllerPublicKey() ed25519.PublicKey

PreviousControllerPublicKey returns the previous controller public key, if any. This is the key that was current before the last rotation.

func (*Manager) PrivateKey ¶

func (m *Manager) PrivateKey() ed25519.PrivateKey

PrivateKey returns the Ed25519 private key.

func (*Manager) PublicKey ¶

func (m *Manager) PublicKey() ed25519.PublicKey

PublicKey returns the Ed25519 public key.

func (*Manager) RotateControllerKey ¶

func (m *Manager) RotateControllerKey(
	newKey ed25519.PublicKey,
)

RotateControllerKey stores the new controller key and moves the current one to previous, enabling a grace period where both keys are accepted.

func (*Manager) SetControllerPublicKey ¶

func (m *Manager) SetControllerPublicKey(
	key ed25519.PublicKey,
)

SetControllerPublicKey stores the controller's public key for verifying controller-signed messages.

func (*Manager) Sign ¶

func (m *Manager) Sign(
	data []byte,
) []byte

Sign signs the given data with the manager's private key and returns the signature.

func (*Manager) VerifyWithGrace ¶

func (m *Manager) VerifyWithGrace(
	data []byte,
	signature []byte,
) bool

VerifyWithGrace checks the signature against both the current and previous controller public keys. Returns true if either key validates the signature, supporting graceful key rotation.

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL