LUKS Unlock API

Send your LUKS passphrase to the server’s dropbear SSH for disk decryption.

Endpoint

POST /api/unlock

Authentication

Requires bearer token in Authorization header.

Authorization: Bearer <token>

Request

Headers

Content-Type: application/json
Authorization: Bearer <token>

Body

{
  "passphrase": "your-luks-passphrase"
}

Field	Type	Required	Description
passphrase	string	Yes	LUKS disk encryption passphrase

Response

Success (200 OK)

{
  "success": true,
  "message": "Passphrase sent successfully"
}

Validation Error (400)

{
  "error": "Passphrase cannot be empty"
}

Or:

{
  "error": "Passphrase too long"
}

Or:

{
  "error": "Passphrase contains invalid characters"
}

Unauthorized (401)

{
  "error": "Invalid or expired token"
}

SSH Error (500)

{
  "error": "Failed to unlock: Connection refused"
}

Passphrase Validation

Rule	Limit
Minimum length	1 character
Maximum length	1024 characters
Forbidden characters	Control characters (null, newline, tab, etc.)

Valid characters include letters, numbers, spaces, and special characters like !@#$%^&*().

How It Works

1. articwake connects via SSH to the dropbear server running in initrd
2. Authenticates using the configured Ed25519 private key
3. Requests a PTY and shell
4. Sends the passphrase to stdin (consumed by cryptsetup-askpass)
5. Closes the connection

The server’s LUKS container unlocks and the system continues booting.

Configuration

ARTICWAKE_HOMELAB_IP="100.x.y.z"
ARTICWAKE_SSH_PORT="2222"
ARTICWAKE_SSH_KEY_PATH="/etc/secrets/articwake-key"

Example

curl

curl -X POST http://localhost/api/unlock \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"passphrase": "my-secret-passphrase"}'

JavaScript (fetch)

const response = await fetch('http://localhost/api/unlock', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ passphrase: 'my-secret-passphrase' })
});

const result = await response.json();

Security Notes

• The passphrase is never stored by articwake
• It’s transmitted over SSH (encrypted) to your server
• The connection uses public key authentication
• articwake accepts any host key (dropbear regenerates keys on each boot)

After Unlocking

1. The LUKS container unlocks and the system continues booting
2. Wait ~30-60 seconds for the full system boot
3. Poll /api/status until system_ssh_open becomes true
4. Your server is now fully accessible

Troubleshooting

”Connection refused”

• Server hasn’t finished booting to initrd yet
• Check /api/status - initrd_ssh_open should be true
• Wait and retry

”Authentication failed”

• SSH key not authorized in server’s initrd
• Wrong key configured in ARTICWAKE_SSH_KEY_PATH
• See SSH Key Setup

”Wrong port”

• Dropbear might be on a different port
• Check ARTICWAKE_SSH_PORT configuration
• Common ports: 22, 2222, 4748

Passphrase not accepted

• Wrong LUKS passphrase
• Try unlocking manually to verify:

  ssh -p 2222 -i /path/to/key root@server-ip
  # Then enter passphrase at prompt