Skip to main content

Documentación API de Gestión de Certificados SSL

Información General

URL Base: http://certificados.psi.unc.edu.ar/api/
Acceso: Interno (solo disponible dentro de la PSI)
Descripción: API para la gestión completa del ciclo de vida de certificados SSL, permitiendo crear, listar, verificar y eliminar certificados para dominios.

Endpoints Disponibles

1. Listar Certificados

Endpoint: /cert-list
Método: GET
Descripción: Obtiene un listado de todos los certificados existentes.
Parámetros: No requiere parámetros.
Respuesta: Lista de certificados ordenados por fecha de creación (descendente).

Ejemplo de uso:

GET http://certificados.psi.unc.edu.ar/api/cert-list

2. Crear Certificado para Dominio(s) Específico(s)

Endpoint: /cert-create
Método: GET
Descripción: Crea un nuevo certificado SSL para uno o más dominios.
Parámetros:

  • domains (obligatorio): Lista de dominios separados por "+" para los cuales se creará el certificado.

Proceso:

  1. Verifica que no exista un certificado previo para los dominios especificados
  2. Comprueba que todos los dominios resuelvan al mismo balanceador
  3. Verifica la correcta configuración del balanceador
  4. Emite el certificado
  5. Instala el certificado en /opt/certificados-ssl/
  6. Hace push al repositorio Git

Respuestas posibles:

  • OK: certificado creado para [domains] - Operación exitosa
  • ERROR 1: ya existe cert para [domain] - Ya existe un certificado para alguno de los dominios
  • ERROR 2: DNS para [domain] no resuelve a un balanceador - El DNS no resuelve a un balanceador conocido
  • ERROR 3: DNS no coincide al mismo balanceador - Los dominios no resuelven al mismo balanceador
  • ERROR 4: Balanceador mal configurado para [domain] - Configuración incorrecta en el balanceador
  • ERROR 6: Fallo de emisión para [domains] - Error en la emisión del certificado
  • ERROR 7: No se pudo instalar cert [first] - Error al instalar el certificado
  • ERROR 8: GIT problema con push - Error al hacer push al repositorio

Consideraciones:

  • Este proceso puede demorar un tiempo considerable (en el orden de 1 minuto).

Ejemplo de uso:

GET http://certificados.psi.unc.edu.ar/api/cert-create?domains=ejemplo.unc.edu.ar+subdominio.ejemplo.unc.edu.ar

3. Crear Certificado por Validación DNS

Endpoint: /cert-create-dns
Método: GET
Descripción: Crea un nuevo certificado mediante validación DNS que puede ser específico o wildcard.
Parámetros:

  • domain (obligatorio): Dominio para el cual se creará el certificado. Si contiene * será un certificado wildcard (ej. *.ejemplo.unc.edu.ar); de lo contrario será un certificado específico.

Proceso:

  1. Verifica que no exista un certificado previo para el dominio
  2. Comprueba que exista el alias DNS requerido para la validación:
    • Para certificados wildcard: _acme-challenge.[dominio] debe apuntar a asterisco.certificados.informatica.unc.edu.ar
    • Para certificados específicos: _acme-challenge.[dominio] debe apuntar a especifico.certificados.informatica.unc.edu.ar
  3. Emite el certificado
  4. Instala el certificado en:
    • Para certificados wildcard: /opt/certificados-ssl/asterisco/[dominio sin *]/
    • Para certificados específicos: /opt/certificados-ssl/[dominio]/
  5. Hace push al repositorio Git

Respuestas posibles:

  • OK: certificado creado para [domain] - Operación exitosa
  • ERROR 1: ya existe cert para [domain] - Ya existe un certificado para el dominio
  • ERROR 2: '[alias_actual]', se esperaba '[alias]' - El registro CNAME no está configurado correctamente
  • ERROR 3: Fallo de emisión para [domain] - Error en la emisión del certificado
  • ERROR 4: No se pudo instalar cert [domain] - Error al instalar el certificado
  • ERROR 5: GIT problema con push - Error al hacer push al repositorio

Ejemplo de uso para certificado específico:

GET http://certificados.psi.unc.edu.ar/api/cert-create-dns?domain=ejemplo.unc.edu.ar

Ejemplo de uso para certificado wildcard:

GET http://certificados.psi.unc.edu.ar/api/cert-create-dns?domain=*.ejemplo.unc.edu.ar

4. Eliminar Certificado

Endpoint: /cert-remove
Método: GET
Descripción: Elimina un certificado existente.
Restricciones: Disponible solo desde IPs específicas (127.0.0.1, 192.168.1.0)
Parámetros:

  • domain (obligatorio): Dominio del certificado a eliminar.

Proceso:

  1. Revoca el certificado en la CA
  2. Remueve el certificado de la lista de certificados gestionados
  3. Elimina el directorio del certificado
  4. Actualiza el repositorio Git
  5. Elimina el certificado de la base de datos

Respuestas posibles:

  • EXITO: certificado de [domain] removido - Operación exitosa
  • ERROR 1: no existe el directorio de cert para [domain] - No existe directorio para el certificado
  • ERROR 2: no aparece el cert para [domain] - El certificado no está en la lista
  • ERROR 3: no existe [domain] en el repositorio - El certificado no está en el repositorio

Ejemplo de uso (solo desde IPs autorizadas):

GET http://certificados.psi.unc.edu.ar/api/cert-remove?domain=ejemplo.unc.edu.ar

5. Verificar Existencia de Certificado

Endpoint: /cert-exist
Método: GET
Descripción: Verifica si existe un certificado para un dominio específico y lista todos los dominios cubiertos por ese certificado.
Parámetros:

  • domain (obligatorio): Dominio a verificar.

Respuestas posibles:

  • Lista de dominios cubiertos por el certificado (si existe)
  • fail - No existe certificado para el dominio

Ejemplo de uso:

GET http://certificados.psi.unc.edu.ar/api/cert-exist?domain=ejemplo.unc.edu.ar

6. Descargar Certificado en formato ZIP

Endpoint: /cert-get-zip
Método: GET
Descripción: Genera y devuelve un archivo ZIP con el certificado completo.
Content-Type: application/zip
Parámetros:

  • domain (obligatorio): Dominio cuyo certificado se desea descargar.
  • asterisco (opcional): Con valor "yes" si se trata de un certificado wildcard.

Respuestas posibles:

  • Archivo ZIP con el certificado
  • Nok - No existe certificado para el dominio

Ejemplo de uso para certificado normal:

GET http://certificados.psi.unc.edu.ar/api/cert-get-zip?domain=ejemplo.unc.edu.ar

Ejemplo de uso para certificado wildcard:

GET http://certificados.psi.unc.edu.ar/api/cert-get-zip?domain=ejemplo.unc.edu.ar&asterisco=yes

En caso del certificado wildcard, el dominio NO debe ponerse con asterico

7. Test (Endpoint de Prueba)

Endpoint: /test
Método: GET
Descripción: Endpoint de ejemplo para pruebas. No realiza ninguna acción.

Ejemplo de uso:

GET http://certificados.psi.unc.edu.ar/api/test

8. Fecha del Servidor

Endpoint: /date
Método: GET
Descripción: Devuelve la fecha y hora actual del servidor.

Ejemplo de uso:

GET http://certificados.psi.unc.edu.ar/api/date

9. Prueba de Argumentos

Endpoint: /args
Método: GET
Descripción: Endpoint para probar el paso de argumentos en formato key=value.

Ejemplo de uso:

GET http://certificados.psi.unc.edu.ar/api/args?key1=value1&key2=value2

Consideraciones Adicionales

Estructura de Almacenamiento de Certificados

  • Certificados normales: /opt/certificados-ssl/[dominio]/
  • Certificados wildcard: /opt/certificados-ssl/asterisco/[dominio]/

Archivos en el Directorio del Certificado

Cada directorio de certificado contiene:

  • cert.pem - Certificado del servidor
  • privkey.pem - Clave privada
  • fullchain.pem - Cadena completa (certificado + intermedios)
  • chain.pem - Certificados intermedios

Validación DNS para Certificados

Para emitir certificados mediante validación DNS, es necesario configurar un registro CNAME:

  • Para certificados wildcard: _acme-challenge.[dominio] debe apuntar a asterisco.certificados.informatica.unc.edu.ar
  • Para certificados específicos: _acme-challenge.[dominio] debe apuntar a especifico.certificados.informatica.unc.edu.ar

Actualización en Balanceadores

Tras crear o eliminar certificados, el sistema notifica automáticamente a los siguientes balanceadores:

  • bal-1
  • bal-2
  • bal-3
  • g3-lb-1
  • bal-4

Fin de la documentación.

Referidos:

  • Gabriel Guillaumet (gguillaumet011@unc.edu.ar)
  • Valentin Castellano (valentin.castellano@unc.edu.ar)
Back to top