Instalación del Cosigner

Modo regular en Linux con Docker. El soporte para Nitro Enclave llegará pronto.

Requisitos previos

• Host: Linux amd64 o arm64 para producción. macOS o WSL 2 para desarrollo.
• Docker: Engine 20.10+ con Compose v2.
• cosign: v3+. El instalador lo agrega si no está presente.
• De Fystack: un token de emparejamiento (cps_...). Consulta el Paso 1.
• Servidor de callback: obligatorio en producción. Consulta Approval Callback.

Red: sin puertos de entrada. HTTPS saliente hacia Apex, el Fystack Gateway, ghcr.io, tu callback y (en el perfil unattended) AWS KMS.

Paso 1: obtén un token de emparejamiento

En el dashboard de Fystack, abre la pestaña Cosigner, haz clic en Register Cosigner, elige Server y haz clic en Continue.

Ingresa un nombre para el cosigner. El diálogo muestra los comandos de instalación y un token de emparejamiento (cps_...). Copia el token: es de un solo uso, expira en 60 minutos y se muestra una sola vez.

Mantén el diálogo abierto mientras completas los pasos siguientes. Muestra Waiting for your cosigner to connect y se actualiza cuando el cosigner se empareja.

Paso 2: instala cosigner-cli

curl -sSL https://cosigner.fystack.io/install.sh | sh

Comprueba el SHA-256 y la firma de Sigstore del binario y luego lo instala en /usr/local/bin (o ~/.local/bin).

Paso 3: crea el directorio de la instancia

Crea un directorio nuevo y vacío para este cosigner en la ubicación que mejor se adapte a tu host, y ejecuta los comandos restantes desde dentro de él. cosigner-cli guarda allí toda la configuración, los secretos y el estado de la instancia.

Paso 4: comprueba el host

cosigner-cli doctor

Comprueba Docker, cosign y la configuración. Informa unconfigured, configured but unpaired o paired.

Paso 5: empareja e inicia

cosigner-cli up

Luego, up:

1. Solicita el endpoint de Fystack. Presiona Enter para mantener el valor predeterminado.
2. Verifica la versión más reciente de ghcr.io/fystack/cosigner con cosign y fija su digest, antes de solicitar cualquier secreto.
3. Escribe un config.yaml predeterminado (perfil manual, callback desactivado).
4. Pide una contraseña de almacenamiento y el token de emparejamiento del Paso 1.
5. Empareja: genera una identidad Ed25519, la registra en Apex y guarda state/pairing.yaml.
6. Inicia el contenedor, lo desbloquea y se conecta al Gateway.

La configuración predeterminada usa el perfil manual: la clave de almacenamiento se envuelve con tu contraseña, que ingresas en cada inicio, y no hay reinicio automático. Para iniciar al arrancar el sistema con AWS KMS, consulta Perfil unattended.

Paso 6: activa la aprobación por callback

La configuración generada tiene require_callback: false, por lo que se firma cualquier solicitud que envíe Fystack. Activa la aprobación antes de crear billeteras:

cosigner-cli callback add https://YOUR-CALLBACK-HOST \
  --server-public-key server-public.pem

Esto edita config.yaml en el mismo lugar, genera la clave de callback del cosigner en secrets/, escribe cosigner-public.pem y reinicia el cosigner. Copia cosigner-public.pem a tu servidor de callback. Consulta Approval Callback.

Ahora la configuración se ve así:

storage:
  backend: sqlite
  sqlite:
    path: data/cosigner.db
  encryption:
    kek:
      type: password_envelope
      config:
        path: /run/secrets/storage-kek.enc
approval:
  require_callback: true
audit:
  type: file
  config:
    path: /var/lib/cosigner/audit.jsonl
callback:
  timeout: 30s
  retry_count: 1
  url: https://YOUR-CALLBACK-HOST/cosigner/approve
  private_key:
    type: file
    config:
      path: /run/secrets/cosigner-private.der.hex
  response_public_key_path: /run/secrets/server-public.pem

Para ajustar otras opciones, como timeout o retry_count, edita el archivo y ejecuta cosigner-cli restart.

• Dentro del contenedor, /var/lib/cosigner es el directorio state/ de la instancia y /run/secrets es su directorio secrets/ (solo lectura).
• Mantén storage y audit tal como se generaron: cosigner-cli requiere SQLite en data/cosigner.db y registro de auditoría en archivo.

Paso 7: verifica

cosigner-cli status
cosigner-cli info
cosigner-cli logs -f

Cuando status muestre ready, el cosigner estará en línea y podrá participar en keygen.

Perfil unattended

La configuración predeterminada solo admite el perfil manual. Con unattended, la clave de almacenamiento se envuelve con tu clave de AWS KMS y el cosigner se inicia al arrancar el sistema. Escribe tú mismo la configuración antes del Paso 5 y guárdala fuera del directorio de la instancia (up la copia dentro):

storage:
  backend: sqlite
  sqlite:
    path: data/cosigner.db
  encryption:
    kek:
      type: kms
      config:
        provider: aws
        region: YOUR-AWS-REGION
        key_id: YOUR-KMS-KEY-ARN
        ciphertext_blob_path: /run/secrets/storage-kek.kms
approval:
  require_callback: false
audit:
  type: file
  config:
    path: /var/lib/cosigner/audit.jsonl

Cifra una clave aleatoria de 32 bytes con tu clave de KMS y guarda el texto cifrado en base64 como secrets/storage-kek.kms en el directorio de la instancia. El contenedor necesita kms:Decrypt mediante un rol de IAM. Luego ejecuta:

cosigner-cli up \
  --profile unattended \
  --config /secure/config.yaml

Continúa con el Paso 6 para activar la aprobación por callback.

Estructura de la instancia

Ejecutar al arrancar

Solo para el perfil unattended. Adapta la unidad de systemd incluida:

[Unit]
Description=Fystack Cosigner (KMS unattended profile)
Requires=docker.service
After=docker.service network-online.target
Wants=network-online.target

[Service]
Type=oneshot
RemainAfterExit=yes
User=cosigner
Group=cosigner
SupplementaryGroups=docker
ExecStart=/usr/local/bin/cosigner-cli --home /var/lib/fystack-cosigner start
ExecStop=/usr/local/bin/cosigner-cli --home /var/lib/fystack-cosigner stop
TimeoutStartSec=360
TimeoutStopSec=60
UMask=0077

[Install]
WantedBy=multi-user.target

Para el perfil manual, pasa la contraseña mediante un descriptor de archivo:

COSIGNER_PASSWORD_FD=3 cosigner-cli start 3< /run/secrets/cosigner-pw

Esto es menos seguro que escribir la contraseña a mano. Consulta Automatizar el reinicio.

Solución de problemas