Ciclo de vida de certificado DV

El ciclo de vida del certificado DV está formado por estos tres pasos principales:

  • Preparar la solicitud de certificado DV
  • Enviar el pedido de certificado DV.
  • (Opcional) Cancelar el pedido de certificado.
  • Completar validación de control de dominio (DCV)
  • Verificar estado del pedido
  • Descargar certificado emitido

Una vez que se ha emitido el certificado, puede realizar alguna de estas acciones:

  • Reemitir un certificado.
  • Revocar un certificado.
Ciclo de vida total de certificado DV

Preparar la solicitud de certificado DV

Para armar el cuerpo de su solicitud y enviar una solicitud de pedido, debe recopilar algunos datos clave:

  • El nombre de dominio que el certificado protegerá.
  • La solicitud de firma de certificado (CSR) generada en el servidor en el que se instalará el certificado.
  • El período de validez del certificado (cantidad de tiempo durante la que el certificado debería ser válido).
  • El método DCV que usará al demostrar que tiene el control del dominio.

Nombre de dominio

Una vez que recopile el nombre de dominio que el certificado protegerá, debe ingresarlo en uno de dos parámetros del cuerpo de la solicitud.

Parámetro Tipo Descripción
common_name cadena Dominio principal que el certificado protegerá.
dns_names matriz Los dominios adicionales que el certificado protegerá.
Agregar dominios a este parámetro puede generar costos adicionales.

Todos los pedidos de certificados DV incluyen una función adicional que le permite cubrir tanto la raíz como el subdominio www de su dominio sin costo adicional. Al armar el cuerpo de su solicitud, agregue el dominio base ([su-dominio].com) y el parámetro common_name y luego la otra versión del dominio (www.[su-dominio].com) a la matriz dns_names.

Solicitud de firma del certificado (CSR)

La (CSR) debe generarse en el servidor en el que se instalará el certificado. Una vez generada, ingrese la CSR con formato PEM en el parámetro csr del cuerpo de la solicitud. Vea Crear una CSR (Solicitud de firma de certificado) para obtener información adicional.

Período de validez

Cuando pide un certificado, debe especificar su período de validez. Puede usar cualquiera de estos parámetros para determinar durante cuánto tiempo será válido un certificado.

Parámetro Tipo Descripción
validity_years int Use este parámetro cuando especifique la validez del certificado en años.
Valores permitidos: 1, 2
validity_days int Use este parámetro cuando especifique la validez del certificado en días.
custom_expiration_date cadena Use este parámetro para especificar una fecha determinada en la que el certificado debe caducar.
Formato: yyyy-MM-dd

Si se incluye más de un parámetro de validez el cuerpo de la solicitud, los priorizamos de la siguiente manera: custom_expiration_date > validity_days > validity_years.

Método DCV

La DCV por correo electrónico es el método DCV predeterminado que se usa para los pedidos de certificados DV. Si así lo desea, puede cambiar el método DCV predeterminado incluyendo el parámetro dcv_method en el cuerpo de la solicitud. El parámetro dcv_method acepta estos valores:

Valor Descripción
email Envía correos electrónicos DCV a cualquier dirección de correo electrónico (por ejemplo, al administrador y a los contactos técnicos) que encontramos en el registro WHOIS del dominio y a las cinco direcciones de correo electrónico formadas para el dominio (admin, administrator, webmaster, hostmaster y postmaster
@[domain_name]).
Cuando usa este método, puede definir un alcance de correo electrónico específico incluyendo el objeto dcv_emails.
dns‑txt‑token Se devuelve un autentificador de valor aleatorio en el cuerpo de la respuesta para que se agregue a un registro DNS TXT del dominio. Usar este método exige la capacidad de modificar los registros DNS del dominio.
http‑token Se devuelve un autentificador de valor aleatorio en el cuerpo de la respuesta que se colocará en un archivo .txt del sitio web que será protegido mediante el certificado. Usar este método exige la capacidad de cargar archivos al servidor web.

Vea Métodos de validación de control de dominio (DCV) para obtener más información sobre los diferentes métodos DCV y cómo completarlos.

(Opcional) matriz dcv_emails

Cuando usa el método DCV por correo electrónico, se puede especificar las direcciones de correo electrónico que deben usarse al enviar los correos electrónicos DCV. Para hacerlo, incluya la matriz dcv_emails en el cuerpo de la solicitud y agregue una entrada para cada dominio en el pedido.

Cuando usa este parámetro, las direcciones de correo electrónico ingresadas deben especificarse en el registro WHOIS del dominio o ser una de las direcciones de correo electrónico predeterminadas para el dominio (definidas por los estándares de la industria como: admin, administrator, webmaster, hostmaster o postmaster @[domain_name]). Además, solo le enviaremos el correo electrónico DCV a las direcciones especificadas.

Por ejemplo, si especifica john.doe@,[domain_name], no le enviaremos los correos electrónicos DCV a ninguna de las direcciones de correo electrónico predeterminadas. O si especifica admin@[dominio.com,], no le enviaremos el correo electrónico DCV a john.doe@[domain_name].

Example dcv_emails array
"dcv_emails": [
  { 
    "dns_name": "example.com",
    "email_domain": "example.com",
    "email": "hostname@example.com"
  },
  { 
    "dns_name": "my.example.com",
    "email_domain": "example.com",
    "email": "admin@example.com"
  },
  { 
    "dns_name": "another.example.com",
    "email_domain": "example.com",
    "email": "admin@example.com"
  }
]

Enviar el pedido de certificado DV.

Ahora que ha recopilado la información antes mencionadas, está listo para armar el cuerpo de su solicitud y enviar su solicitud de pedido. Esto se hace con un POST en el terminal Pedido DV SSL.

Un POST exitoso en este terminal devuelve un código de respuesta HTTP 201 creado. En el cuerpo de la solicitud hay algunos datos clave que se usan para verificar el estado del pedido, así como para descargar el certificado una vez que se haya emitido.

  • id: Id. de pedido usado para verificar los detalles del pedido y realizar las acciones DCV.
  • certificate_id: Id. de certificado usado para descargar el certificado emitido.
  • dcv_random_value: autentificador generado aleatoriamente que se usa para los métodos DCV dns-txt-token y http-token. Este autentificador caduca después de 30 días.

Para obtener más información sobre cada parámetro usado en el cuerpo de la solicitud, vea el cuadro Pedido DV SSL: parámetros de la solicitud.

cURL
curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/{{dv_ssl_certificate_id}}' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
    "certificate": {
        "common_name": "example.com",
        "dns_names": [
            "sub.example.com",
            "app.example.com"
        ],
        "csr": "<csr>",
        "server_platform": {
            "id": 45
        },
        "signature_hash": "sha256",
        "organization_units": [
            "Accounting department"
        ]
    },
    "validity_years": 2,
    "comments": "Message for the approver",
    "disable_renewal_notifications": true,
    "dcv_method": "email",
    "locale": "en",
    "dcv_emails": [
      { 
        "dns_name": "example.com",
        "email_domain": "example.com",
        "email": "hostname@example.com"
      },
      { 
        "dns_name": "sub.example.com",
        "email_domain": "example.com",
        "email": "admin@example.com"
      },
      { 
        "dns_name": "app.example.com",
        "email_domain": "example.com",
        "email": "admin@example.com"
      }
    ],
    "payment_method": "balance",
    "custom_fields": [
        {
            "metadata_id": 11,
            "value": "Invoice #00001"
        }
    ]
}'
201 Created (email)
{
  "id": 112233,
  "certificate_id": 123456
}
201 Created (dns-txt-token or http-token)
{
  "id": 112233,
  "certificate_id": 123456,
  "dcv_random_value": "icru1984rnekfj"
}

Después de enviar el pedido, puede usar el terminal Información del pedido para obtener los detalles del pedido y repasar la información enviada.

(Opcional) Cancelar el pedido de certificado.

Después de hacer un pedido, puede haber veces en las que necesita cancelarlo. Para cancelar un pedido, debe cambiar el estado de pendiente a cancelado. Esto se hace con un PUT en el terminal Actualizar el estado de pedido.

Un PUT exitoso en este terminal devuelve una respuesta HTTP 204 Sin contenido.

El parámetro status solo permite un valor de CANCELED (distinguir mayúsculas de minúsculas).

cURL
curl -X PUT \
  'https://www.digicert.com/services/v2/order/certificate/{{order_id}}/status' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
    "status": "CANCELED",
    "note": "Message about the cancellation."
}'
204 No Content
// empty

Completar validación de control de dominio (DCV)

Con el pedido DV enviado, ahora debe probar que tiene el control de los dominios que figuran en el pedido.

Sin importar el método DCV elegido, debe completar la DCV para cada dominio que el certificado protegerá. Por ejemplo, si se eligió el método dns-txt-token, debe crear un registro DNS TXT para cada dominio en el pedido.

Método DCV por correo electrónico

Si la matriz dcv_emails se incluyó en el cuerpo de la respuesta, entonces los correos electrónicos DCV se envían a las direcciones definidas en la matriz. De lo contrario, los correos electrónicos DCV se envían a estas direcciones:

  • Todas las direcciones de correo electrónico que se encuentran en el registro WHOIS del dominio
  • Estas cinco direcciones de correo electrónico formadas:
    • admin@[domain_name]
    • administrator@[domain_name]
    • webmaster@[domain_name]
    • hostmaster@[domain_name]
    • postmaster@[domain_name]

Para completar la DCV por correo electrónico, en la bandeja de entrada de su cliente de correo electrónico, localice el correo electrónico que tenga el asunto [Acción requerida] Aprobar solicitud de certificado para[sudominio] {N.º de pedido} y siga las indicaciones.

Si debe reenviar los correos electrónicos DCV para un pedido enviado, puede usar el terminal DV SSL: reenviar correos electrónicos (reemplace el marcador de posición {{order_id}} con la Id. de pedido devuelto en el cuerpo de la respuesta cuando envió el pedido).

Método DCV DNS TXT

Si ya no tiene el valor aleatorio o debe generar uno nuevo, puede usar el terminal DV SSL: generar autentificador DCV, y reemplace el marcador de posición {{order_id}} con la Id. de pedido que se incluyó en el cuerpo de la respuesta cuando envió el pedido.

Siga estos pasos para completar la DCV DNS TXT y demostrar que tiene el control de sus dominios:

  1. Copie el dcv_random_value que se devolvió en el cuerpo de la respuesta cuando hizo el pedido.
  2. Vaya al sitio de su proveedor de DNS y cree un nuevo registro TXT.
  3. En el campo Valor TXT, ingrese el valor aleatorio que copió.
  4. Campo Host
    1. Dominio base (por ejemplo,[sudominio].com)
      ¿Está validando el dominio base? Deje el campo Host en blanco o agregue el símbolo de arroba (según los requisitos de su proveedor de DNS).
    2. Subdominio (por ejemplo,[su.dominio].com)
      ¿Está validando un subdominio? En el campo Host, agregue el subdominio que está validando.
  5. En el campo de tipo de registro (o equivalente), seleccione TXT.
  6. Seleccione un valor Período de vida (TTL) o utilice el valor predeterminado de su proveedor de DNS.
  7. Guarde el registro.
  8. Repita los pasos anteriores para cada dominio que figura en el pedido.

Una vez que haya agregado el registro DNS TXT para todos los dominios que figuran en el pedido, está listo para que verifiquemos los registros TXT (vea Verificar DCV).

Método DCV autentificador HTTP

Siga estos pasos para completar la DCV autentificador HTTP y demostrar que tiene el control de sus dominios:

  1. Copie el dcv_random_value que se devolvió en el cuerpo de la respuesta cuando hizo el pedido.
  2. En su editor de texto preferido, pegue el valor aleatorio que copió.
  3. Guarde el archivo con un nombre de archivo fileauth.txt.
  4. En su servidor web, cargue el archivo fileauth.txt en esta ubicación: [sudominio]/.well-known/pki-validation/fileauth.txt.

Realizar verificación DCV

Con el autentificador aleatorio agregado al registro DNS TXT (método DNS TXT) o el archivo fileauth.txt cargado en la ubicación especificada (método DCV por HTTP) para cada dominio que figura en el pedido, está listo para realizar una verificación DCV. Esto se hace con un PUT en el terminal DV SSL: verificar DCV.

Un PUT en este terminal devuelve cuatro respuestas posibles:

  • 200 OK: La DCV se completó correctamente.
  • 400 Solicitud Errónea: Hay tres posibles códigos de errores con esta respuesta:
    • invalid_dns_txt: No se pudo encontrar el registro DNS TXT o contiene el valor aleatorio incorrecto para uno o más dominios. Verifique que todos los dominios que figuran en el pedido tengan el registro DNS TXT adecuado con el valor aleatorio correcto.
    • file_random_value_not_found: No se pudo encontrar el archivo fileauth.txt o contiene el valor aleatorio incorrecto para uno o más dominios. Verifique que, para todos los dominios que figuran en el pedido, el archivo esté en el directorio correcto, que esté públicamente disponible y que contenga el valor aleatorio correcto.
    • invalid_dns_method: El método DCV para el pedido está configurado para correo electrónico. Localice el correo electrónico enviado y complete las instrucciones DCV o cambie el método DCV.
cURL
curl -X PUT \
  'https://www.digicert.com/services/v2/order/certificate/{{order_id}}/check-dcv' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}'
200 OK
{
  "order_status": "pending",
  "certificate_id": 123456,
  "dcv_status": "valid"
}
400 (dns-txt-token)
{
  "errors": [
    {
      "code": "invalid_dns_txt",
      "message": "Could not find a valid TXT record for one or more domains."
    }
  ]
}
400 (http-token)
{
  "errors": [
    {
      "code": "file_random_value_not_found",
      "message": "Could not find the random value at the expected file location for one or more domains."
    }
  ]
}
400 (email)
{
  "errors": [
    {
      "code": "invalid_dns_method",
      "message": "An error occurred while processing your request."
    }
  ]
}

Verificar estado del pedido

Después de enviar un pedido y de completar la DV para cada dominio, querrá saber cuándo cambia su estado y cuándo el certificado está listo para descargar. La mejor forma de hacerlo es con un GET en el terminal Estado de la lista de cambios.

Un GET en este terminal devuelve tres respuestas posibles:

  • 200 OK (matriz orders): La matriz de los pedidos mencionan todos los pedidos cuyos estados han cambiado en el período especificado. Cuando el estado de su pedido cambia de pendiente a emitido, aparecerá en la lista. Si se devuelven varios pedidos, use la Id. de pedido o la Id. de certificado para localizar el pedido.
  • 200 OK (objeto vacío): Una respuesta con un objeto vacío ({}) significa que ningún pedido tuvo un cambio de estado en el período especificado. Aumente el período o espere para enviar otra solicitud.
  • 400 Solicitud errónea: Una respuesta con un código de error time_frame_too_long significa que el período especificado en la cadena de consulta de la URL supera el valor máximo. Reduzca el período a un valor inferior a 10 080 minutos (7 días).

cURL
curl -X GET \
  'https://www.digicert.com/services/v2/order/certificate/status-changes?minutes=10' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}'
200 OK
{
  "orders": [
    {
      "order_id": 112233,
      "certificate_id": 123456,
      "status": "issued"
    }
  ]
}
200 OK (no orders found)
{}
400 Bad Request
{
  "errors": [
    {
      "code": "time_frame_too_long",
      "message": "An error occurred while processing your request."
    }
  ]
}

Descargar certificado DV

Una vez que el estado del pedido cambia de pendiente a emitido, su certificado está listo para ser descargado. Según sus necesidades, hay cuatro terminales que puede usar para descargar su certificado:

Reemitir certificado DV

Reemitir un certificado le permite agregar, eliminar o cambiar los nombres de dominio, actualizar la CSR, o modificar el cifrado de firma de un certificado sin enviar un nuevo pedido. Un certificado reemitido tendrá un nuevo Id. de certificado, pero el mismo Id. de pedido. Después de que se aprueba una reemisión, se emite un nuevo certificado que debe volver a instalarse.

Cuando reemite un certificado, debe brindar esta información:

Incluso si algunos de los detalles antes mencionados permanecerán iguales, igual debe incluirlos en la solicitud de reemisión.

Tenga en cuenta que ciertos cambios, como agregar SAN adicionales («dns_names») puede generar costos extras.

Tal vez, sea necesario realizar la DCV para algunos de los dominios o para todos ellos.

El terminal Reemitir certificado acepta los siguientes parámetros opcionales:

  • comentarios: Agrega un mensaje a la solicitud para el aprobador.
  • skip_approval: Permite que la solicitud se envíe inmediatamente para su validación, lo que omite la necesidad de aprobar la solicitud de reemisión.
cURL
curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/{{order_id}}/reissue' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
  "certificate": {
    "common_name": "example.com",
    "dns_names": [
        "sub.example.com"
    ],
    "csr": "<csr>",
    "server_platform": {
      "id": 2
    },
    "signature_hash": "sha256"
    "skip_approval": true
  }
}'
201 Created
{
  "id": 112233,
  "requests": [
    {
      "id": 332211
    }
  ]
}
201 skip_approval
{
  "id": 112233,
  "certificate_id": 111112
}

Después de que se complete una reemisión, descargue el nuevo certificado (vea Descargar certificado DV).

Puede obtener un historial de reemisión completo para un pedido usando el terminal Mostrar reemisiones.

Revocar certificado DV

Una vez que se emite su pedido, puede enviar una solicitud de revocación si fuera necesario.

Un administrador debe aprobar todas las solicitudes de revocación en CertCentral antes de que DigiCert revoque el certificado. Este paso de aprobación es obligatorio y no puede omitirse.

Puede revocar un certificado usando una de dos terminales:

Ambas terminales usan los mismos parámetros del cuerpo de la solicitud.

Después de enviar la solicitud de revocación, un administrador debe aprobar la solicitud usando el terminal Actualizar el estado de la solicitud.

cURL
curl -X PUT \
  'https://www.digicert.com/services/v2/certificate/{{certificate_id}}/revoke' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
  "comments": "I no longer need this cert."
}'
201 Created
{
  "id": 1,
  "date": "2016-02-10T17:06:15+00:00",
  "type": "revoke",
  "status": "pending",
  "requester": {
    "id": 14,
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@digicert.com"
  },
  "comments": "I no longer need this cert."
}