Operaciones de Cosigner

Referencia de la CLI, copias de seguridad, actualizaciones y monitoreo.

Comandos

Flags globales: --home (directorio de la instancia; por defecto COSIGNER_HOME y luego el directorio actual) y --docker.

Comando Qué hace Flags
up Verifica, empareja e inicia una nueva instancia. Equivale a start una vez emparejada. --apex-endpoint --config --profile --image --token-file
start Inicia. Pide la contraseña en el perfil manual.
stop Detiene y conserva el estado. Drena las sesiones durante hasta 25s.
restart Recrea el contenedor.
status ready, state, participant_id, active_sessions.
logs Logs del contenedor. --tail -f
doctor Comprueba el host, la configuración y la firma de la imagen.
info Clave pública, imagen, huella del callback.
callback add Exige la aprobación por callback. --url --server-public-key --ca --no-restart
callback remove Deja de exigir la aprobación. -y --no-restart
backup Copia de seguridad cifrada de la instancia. El Cosigner debe estar detenido. --out
restore Restaura en un directorio vacío. --in
export Escribe archivos de recuperación .mshare. Perfil manual, detenido. --wallet --out-dir --list
update Verifica e instala una versión más reciente tras una copia de seguridad. --version --backup-out --dry-run
version Versión de la CLI.

Variables de entorno

Variable Uso
COSIGNER_HOME Directorio de la instancia
COSIGNER_PASSWORD_FD Lee la contraseña de almacenamiento desde un descriptor de archivo
COSIGNER_RECOVERY_PASSWORD_FD Lee la contraseña de la copia de seguridad desde un descriptor de archivo
COSIGNER_NO_UPDATE_CHECK=1 Oculta los avisos de actualización

Perfiles

manual unattended
Clave de almacenamiento Contraseña (Argon2id) AWS KMS
Inicio Contraseña en cada inicio Automático, al arrancar
Reinicio de Docker no on-failure:5
.mshare export Sí No

Se define en up. No se puede cambiar después.

Automatizar el reinicio

En el perfil manual, start y restart piden la frase de contraseña de almacenamiento. Para ejecutarlos desde un script, pasa la frase de contraseña por un descriptor de archivo con COSIGNER_PASSWORD_FD.

Desde un archivo:

chmod 600 /etc/cosigner/passphrase
COSIGNER_PASSWORD_FD=3 cosigner-cli --home /srv/cosigner restart 3< /etc/cosigner/passphrase

Desde un almacén de secretos, para que la frase de contraseña no se escriba en disco:

COSIGNER_PASSWORD_FD=3 cosigner-cli --home /srv/cosigner restart \
  3< <(gcloud secrets versions access latest --secret=cosigner-passphrase)
  • 3 es el número del descriptor de archivo. Debe ser 3 o mayor y el mismo en ambos lugares.
  • El archivo debe contener solo la frase de contraseña. Se elimina un salto de línea final; cualquier otro carácter adicional hace que el desbloqueo falle.
  • Una frase de contraseña incorrecta falla de inmediato, sin reintentos.

Esto es menos seguro que escribir la frase de contraseña a mano. Cualquiera que pueda leer el archivo de la frase de contraseña o el secreto, y ejecutar cosigner-cli, puede desbloquear el Cosigner. Guarda la frase de contraseña fuera del directorio de la instancia, nunca junto a secrets/storage-kek.enc, y limita quién puede leerla. Es preferible usar un almacén de secretos en lugar de un archivo.

Copia de seguridad y restauración

backup escribe un único archivo con la configuración, los secretos, la identidad, el registro de emparejamiento, la base de datos cifrada y el log de auditoría. Se cifra con una contraseña de recuperación independiente (Argon2id + AES-256-GCM).

cosigner-cli stop
cosigner-cli backup --out /backups/cosigner-2026-10-12.cosrec
cosigner-cli start

Escríbelo fuera del directorio de la instancia. Los datos de la instancia están limitados a 128 MiB.

cosigner-cli --home /srv/cosigner-restored restore --in /backups/cosigner-2026-10-12.cosrec
cosigner-cli --home /srv/cosigner-restored start

Detén o revoca primero la instancia anterior. Nunca ejecutes dos copias del mismo Cosigner.

Prueba las restauraciones en un host limpio con regularidad.

Exportación de recuperación

export escribe un .mshare por billetera, cifrado con una frase de contraseña de seis palabras que se muestra una sola vez. Estos archivos son la aportación del Cosigner a Fystack Recovery, que reconstruye las claves sin conexión a partir de un umbral de shares. Un solo archivo no puede reconstruir una clave.

cosigner-cli stop
cosigner-cli export --out-dir /secure/recovery
cosigner-cli start

Guarda las frases de contraseña separadas de los archivos. Consulta Recuperación de claves para ver el procedimiento completo.

Actualizaciones

cosigner-cli update --dry-run
cosigner-cli update --backup-out /backups/pre-update.cosrec
  1. Elige la versión más reciente (o --version). No permite volver a versiones anteriores.
  2. Verifica la firma y el contrato del contenedor.
  3. Detiene el Cosigner y escribe una copia de seguridad.
  4. Fija el nuevo digest e inicia.

No hay reversión automática. Conserva la copia de seguridad hasta que la nueva versión haya firmado transacciones reales.

Monitoreo

Estado: se comprueba cada 10s; se considera desactualizado tras 15s. Configura alertas para:

  • ready: false más allá de la configuración del primer arranque.
  • state: callback_unavailable.
  • Salida del contenedor (el perfil manual nunca se reinicia por sí solo).

Log de auditoría: state/audit.jsonl, firmado y encadenado por hash. Eventos: session_start, session_end, session_abort, callback_decision, kek_use, identity_sign, backup_created, restore_performed. Envíalo fuera del host; Docker no lo rota.

Logs: Docker json-file, 10 MB x 5.

Retirada del servicio

  1. Pide a Fystack que revoque el Cosigner.
  2. cosigner-cli stop.
  3. Conserva una copia de seguridad final y las exportaciones según tu política de retención y, luego, elimina el directorio de la instancia.