Machines

Machines are servers, containers, or processes that read secrets from your vault. Each machine authenticates with an Ed25519 keypair generated during registration. SikkerKey does not use bearer tokens or API keys for machine authentication.

Registering a Machine

From the machines page, click + Validate to open the bootstrap modal. Select your OS (Linux/macOS or Windows) and copy the bootstrap command.

Linux / macOS:

curl -sSL https://api.sikkerkey.com/v1/bootstrap/YOUR_TOKEN | sh

Windows (PowerShell):

irm https://api.sikkerkey.com/v1/bootstrap/YOUR_TOKEN/ps | iex

The token is valid for 10 minutes and can only be used once.

Requirements

The bootstrap script requires:

• openssl (Linux/macOS). Used to generate the Ed25519 keypair.
• curl (Linux/macOS). Used to download the script and register with SikkerKey.

No root or sudo access is needed. Files are written to ~/.sikkerkey/.

What the Script Does

1. Generates an Ed25519 keypair using openssl genpkey -algorithm Ed25519
2. Extracts the raw 32-byte public key
3. Sends the public key, the token, and the machine's hostname to SikkerKey
4. Receives back the machine ID and vault ID
5. Creates ~/.sikkerkey/vaults/{vaultId}/ with the private key and identity file
6. Sets permissions: directories to 700, files to 600

Only the public key is transmitted during registration. The private key never leaves the machine.

Re-registration

If a machine was previously registered with the same vault, the bootstrap script replaces the old identity automatically. The old machine ID becomes invalid. You will need to approve the new registration from the dashboard.

Multi-Vault

A machine can be registered with multiple vaults. Each vault gets its own directory and keypair under ~/.sikkerkey/vaults/. The SDK resolves which identity to use based on the vault ID you provide.

Machine States

Every machine has two flags that control its access:

A machine must be both approved and enabled to authenticate.

Approving a Machine

Newly registered machines appear with a "pending" status. Click Approve to allow the machine to authenticate. Until approved, the machine cannot read any secrets regardless of project membership or grants.

Click Deny to reject and permanently remove the machine registration.

Machine Authentication

Every request from a machine includes four headers:

The signed payload is: {method}:{path}:{timestamp}:{nonce}:{bodyHash} where bodyHash is the SHA-256 hex digest of the request body.

The SDK handles all of this automatically:

val sk = SikkerKey("vault_abc123")
val secret = sk.getSecret("sk_a1b2c3d4e5")

Verification Order

The server verifies each request in this order:

1. IP lockout check: 3 failed attempts from the same IP within 5 minutes triggers a 30-minute lockout
2. Header presence: all four headers must be present
3. Machine lockout check: 3 failed attempts for the same machine ID triggers a 30-minute lockout (independent of source IP)
4. Machine lookup: the machine must exist, be approved, and be enabled
5. Signature verification: the signed payload is verified against the machine's stored public key
6. Timestamp window: the timestamp must be within 5 minutes of server time (1 minute of forward clock skew allowed)
7. Nonce uniqueness: the nonce must not have been used before. Nonces are persisted in the database and survive server restarts.
8. Account status: the vault owner's account must be active

Signature verification happens before nonce consumption. This means an invalid signature cannot flood the nonce table, and a replayed request with a valid signature is caught by the nonce check.

If any check fails, the request is rejected and an audit log entry is recorded. Failed attempts are counted against both the source IP and the machine ID.

Replay Protection

Every nonce is persisted in the database after signature verification succeeds. A captured request cannot be replayed because the nonce is already recorded. This survives server restarts and works across multiple server instances. Expired nonces (older than 6 minutes) are cleaned up automatically.

Renaming a Machine

Machines are registered with their hostname by default. To rename a machine, click the machine name on the machines page. Enter the new name and press Enter.

Every rename is recorded in the name history. Click history next to the machine name to see all previous names with timestamps.

Renames are audit-logged as machine_rename.

Revoking a Machine

Click Revoke to permanently remove a machine. This deletes:

• The machine registration
• All project memberships for that machine
• All secret access grants for that machine

The machine can no longer authenticate. The identity file on the machine becomes invalid. This cannot be undone.

Denying a pending machine also cleans up any project memberships or grants that may have been configured before approval.

Machine Tracking

The machines page shows:

Adding Machines to Projects

Registering a machine does not give it access to any project or secret. After approval, you must:

1. Navigate to a project and open the Machines tab
2. Click + Add Machine To Project
3. Select the machine

This adds the machine to the project but still does not give it access to any secrets.

4. Click Configure on the machine
5. Move secrets from Available to Granted
6. Save

Only after both steps can the machine read those specific secrets.

Team Member Machines

Team members with the machine_add permission can add their own machines to a vault owner's project. The vault owner grants this permission explicitly.

When a team member adds a machine, it comes from their own vault (not the owner's machine list). On the project machines page, team member machines are shown with an owner badge displaying the team member's username.

The vault owner can remove a team member's machine from the project at any time. When this happens, an audit entry is recorded for both the vault owner and the team member.

Identity File

The bootstrap script creates an identity file at ~/.sikkerkey/vaults/{vaultId}/identity.json:

{
  "machineId": "9daae125-1f61-4eca-bde6-70aaa40db018",
  "machineName": "api-server-1",
  "vaultId": "vault_33a35xpcoz4yqapn",
  "apiUrl": "https://api.sikkerkey.com",
  "privateKeyPath": "/home/deploy/.sikkerkey/vaults/vault_33a35xpcoz4yqapn/private.pem"
}

The SDK reads this file to determine which machine it is, which vault to authenticate against, and where the private key is stored.