Přeskočit obsah

SSH Key Management

This guide documents the SSH Key Management feature (key pairs, authorized-keys, agent deployment simulation).

Overview

  • Key pairs: generated or imported private keys stored encrypted with the system encryptor.
  • Authorized keys: records representing a request to deploy a public key to an agent's authorized_keys file.
  • Agent endpoints: minimal agent discovery and polling endpoints provided for testing and agent integration.

API Endpoints

  • POST /api/v1/ssh/keys — generate a new key pair (JSON body: name, key_type, key_size, optional user_id, project_id).
  • POST /api/v1/ssh/keys/import — import an existing private key PEM (JSON body: name, private_key, optional user_id, project_id).
  • POST /api/v1/ssh/keys/:id/export — export a private key (requires user_id in body).
  • GET /api/v1/ssh/keys — list key pairs.
  • POST /api/v1/ssh/authorized-keys — request deployment of an authorized key (creates pending record).
  • GET /agent/:agent_id/authorized-keys/pending — agent polls for pending authorized key deployments.

Import Notes

  • The import endpoint accepts PEM-encoded private keys. Supported formats: PKCS#8, PKCS#1 (RSA), and Ed25519 keys that can be parsed by Go's x509 package.
  • Private keys are encrypted at rest using the configured Encryptor. In tests, a deterministic encryptor is used.

Agent Deploy Simulation

For development and testing, a background deployer (StartAuthorizedKeyDeployer) periodically marks pending authorized-keys as deployed.

Real agents should poll GET /agent/:agent_id/authorized-keys/pending and perform the deployment steps (write to authorized_keys, etc.), then update status using an agent API (not implemented here).

Migrations

SQL migrations for SSH tables are added under backend/internal/db/migrations/000059_ssh_key_management.up.sql and .down.sql — ensure these are applied in production migrations.

Testing

Unit tests are available in the repository under backend/internal/*.

Security

Do not modify code under backend/internal/core/crypto/ or HSM-related code. Use the provided Encryptor API for encrypting private key material.

Contact

For questions about integration with agents or production deployment, consult the architecture docs.