Ciclo de vida do certificado OV/EV

O ciclo de vida do certificado OV/EV tem estas etapas principais:

  • Preparar solicitação de certificados
  • Enviar seu pedido de certificado
  • (Opcional) Cancelar pedido de certificado
  • Completar validação de controle do domínio
  • Completar validação da organização
  • Verificar status do pedido
  • Baixar certificado emitido

Depois que um certificado tiver sido emitido, é possível realizar qualquer uma destas ações:

  • Reemitir um certificado
  • Revogar um certificado

Preparar solicitação de certificados

Para construir o seu corpo de solicitação e enviar uma solicitação de pedido, é necessário coletar algumas peças-chave de informações:

  • Nome(s) de domínio a ser protegido pelo certificado.
  • Solicitação de assinatura do certificado (CSR) gerada no servidor em que o certificado estará instalado.
  • Período de validade do certificado (quantidade de tempo que o certificado deve ser válido).
  • Método DCV a usar ao demonstrar controle sobre o(s) domínio(s).
  • O nome jurídico e informações de registro para a Organização sendo validada.

Nome(s) do domínio

Depois de ter coletado o(s) nome(s) de domínio a ser protegido pelo certificado, ele deve ser inserido em um de dois parâmetros do corpo da solicitação.

Parâmetro Tipo Descrição
common_name string Domínio primário a ser protegido pelo certificado.
dns_names matriz Quaisquer domínios adicionais a serem protegidos pelo certificado.
Adicionar domínios a este parâmetro pode gerar custos adicionais.

Todos os pedidos de certificados OV/EV lhe permitem incluir uma SAN adicional específica em certificados de domínio exclusivo gratuitamente. Ao construir o seu corpo de solicitação, adicione o domínio base ([your-domain].com) ao parâmetro common_name e depois a outra versão do domínio (www.[your-domain].com) à matriz dns_names.

Solicitação de Assinatura de Certificado (CSR)

O CSR deve ser gerado no servidor em que o certificado estará instalado. Depois de gerado, insira o CSR formato em PEM no parâmetro csr do corpo da solicitação. Veja Criar um CSR (Solicitação de Assinatura de Certificado) para informações adicionais.

Período de validade

Ao pedir um certificado, é necessário especificar o período de validade do certificado. É possível usar qualquer um destes parâmetros para determinar quanto tempo um certificado será válido.

Parâmetro Tipo Descrição
validity_years int Use este parâmetro ao especificar validade do certificado em anos.
Valores permitidos: 1, 2
validity_days int Use este parâmetro ao especificar validade do certificado em dias.
custom_expiration_date string Use este parâmetro para especificar uma data específica em que o certificado deve expirar.
Formato: yyyy-MM-dd

Se mais de um parâmetro de validade for incluído no corpo da solicitação, iremos priorizá-los da seguinte forma: custom_expiration_date > validity_days > validity_years.

Método DCV

DCV de e-mail é o método DCV padrão usado para pedidos de certificados OV/EV. Se desejado, é possível alterar o método DCV padrão ao incluir o parâmetro dcv_method no corpo da solicitação. O parâmetro dcv_method aceita estes valores:

Valor Descrição
email Envia e-mails de DCV a quaisquer endereços de e-mail (por ex.., administrador e contatos técnicos) que encontrarmos no registro WHOIS do domínio e a cinco endereços de e-mail construídos para o domínio (admin, administrador, webmaster, hostmaster e postmaster
@[domain_name]).
Ao usar este método, é possível definir um escopo de e-mail específico ao incluir o objeto dcv_emails.
dns-cname-token Retorna um token de valor aleatório no corpo de resposta para ser adicionado a um registro DNS CNAME no domínio. Usar este método exigia a capacidade de modificar registros DNS do domínio.
dns‑txt‑token Retorna um token de valor aleatório no corpo de resposta para ser adicionado a um registro DNS TXT no domínio. Usar este método exigia a capacidade de modificar registros DNS do domínio.
http‑token Retorna um token de valor aleatório no corpo da resposta para ser colocado em um arquivo .txt no site a ser protegido pelo certificado. Usar este método exige a capacidade de carregar arquivos ao servidor web.

Consulte Demonstrar controle sobre domínios em um pedido de certificado pendente para mais informações sobre diferentes métodos DCV e como completá-los.

(Opcional) matriz dcv_emails

Ao usar este método DCV de e-mail, é possível especificar os endereços de e-mail que devem ser usados ao enviar os e-mails DCV. Para fazer isso, inclua a matriz dcv_emails no corpo da solicitação e adicione uma entrada para cada domínio no pedido.

Ao usar este parâmetro, endereços de e-mail inseridos devem ser especificados no registro WHOIS do domínio ou serem um dos endereços de e-mail para o domínio (definido por padrões da indústria como: admin, administrator, webmaster, hostmaster, e/ou postmaster @[domain_name]). Além disso, só enviaremos o e-mail DCV aos endereços especificados.

Por exemplo, se você especificar john.doe@[domain_name], não enviaremos e-mails DCV a qualquer um dos endereços de e-mail padrão. Ou se você especificar admin@[domain.com], não enviaremos o e-mail DCV para 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 seu pedido de certificado

Agora que você coletou as informações acima, você está pronto para construir o seu corpo de solicitação e enviar sua solicitação do pedido. Isso é feito com um POST ao ponto de extremidade Order OV/EV SSL . Note que a linha de produtos Secure Site é pedida através de um ponto de extremidade separado.

Os detalhes e contato da organização são enviados aqui no objeto organization. Se a organização já tiver uma ID atribuída, é possível simplesmente passá-la com a string id em vez de fornecer as informações completas da organização.

Um POST bem-sucedido a este ponto de extremidade retornará um código de resposta HTTP 201 Created. O corpo da resposta inclui algumas peças-chave de informações que são usadas para verificar o status do pedido, bem como baixar o certificado depois de sua emissão.

  • id – ID do pedido usada para verificar detalhes do pedido e realizar ações DCV.
  • certificate_id – ID do certificado usada para baixar o certificado emitido.
  • dcv_random_value – Token aleatoriamente gerado usado para métodos DCV dns-txt-token e http-token. Este token expira após 30 dias.

Para mais informações sobre cada parâmetro usado no corpo da solicitação, consulte a tabela parâmetros de Order OV/EV SSL – Request.

cURL
curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/{{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,
    "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",
    "organization": {
        "name": "Epigyne Unwieldiness llc",
        "assumed_name": "Epigyne Unwieldiness",
        "country": "us",
        "address": "932 Prospect Street",
        "address2": "Floor 08",
        "city": "Minneapolis",
        "state": "mn",
        "zip": "40849",
        "telephone": "666-186-6450",
        "container": {
            "id": 93288
        },
        "organization_contact": {
            "first_name": "Gia",
            "last_name": "Booth",
            "job_title": "Clinical Laboratory Technician",
            "email": "gia.booth@inbox.com",
            "telephone": "666-186-6450",
            "telephone_extension": "736"
        }
    },
    "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"
}

Após enviar o pedido, é possível usar o ponto de extremidade Order info para obter detalhes do pedido e revisar as informações enviadas.

(Opcional) Cancelar pedido de certificado

Após fazer um pedido, poderá haver momentos em que o seu cancelamento será necessário. Para cancelar um pedido, é preciso alterar o status de pendente para cancelado. Isso é feito com um PUT ao ponto de extremidade Update order status.

Um PUT bem-sucedido a este ponto de extremidade retorna uma resposta HTTP 204 No Content.

O parâmetro status só permite um valor de CANCELED (sensível a maiúsculas e 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 validação de controle do domínio

Com o pedido OV/EV enviado, agora é preciso provar controle sobre os domínios no pedido.

Independentemente do método DCV escolhido, você deve completar o DCV para cada domínio a ser protegido pelo certificado. Por exemplo, se o método dns-txt-token foi escolhido, você deve criar um registro DNS TXT para cada domínio no pedido.

Método DCV do e-mail

Se a matriz dcv_emails foi incluída no corpo de resposta, os e-mails DCV são enviados aos endereços definidos na matriz. De outra forma, e-mails DCV são enviados a estes endereços:

  • Todos os endereços de e-mail encontrados no registro WHOIS do domínio
  • Estes cinco endereços de e-mail construídos:
    • admin@[domain_name]
    • administrator@[domain_name]
    • webmaster@[domain_name]
    • hostmaster@[domain_name]
    • postmaster@[domain_name]

Para completar o DCV de e-mail, na sua caixa de entrada do cliente do e-mail, localize o e-mail com o assunto [Ação necessária] Aprovar solicitação de certificado para[yourdomain] {Pedido Nº} e siga as instruções.

Caso seja necessário reenviar os e-mails DCV para um pedido enviado, é possível usar o ponto de extremidade Resend emails (substitua o espaço reservado {{order_id}} pela ID do pedido retornado no corpo da resposta quando tiver enviado o pedido).

Método DNS CNAME DCV

Siga estas etapas para completar o DNS CNAME DCV e demonstrar controle sobre os seus domínios:

  1. Copie dcv_random_value que foi gerado quando o pedido foi feito. Para pedidos OV/EV, é possível recuperar este valor ao usar o ponto de extremidade de informações do domínio e incluir a string de consulta URL include_dcv=true.
  2. Visite o site do seu provedor DNS e crie um novo registro CNAME.
  3. No campo hostname (ou equivalente), insira o valor aleatório copiado.
  4. No campo tipo de registro (ou equivalente), selecione CNAME.
  5. No campo host de destino (ou equivalente), insira dcv.digicert.com (isso aponta o registro CNAME a dcv.digicert.com).
  6. Selecione um valor para Vida útil (TTL) ou use seu valor padrão do provedor DNS.
  7. Salve o registro.
  8. Repita as etapas acima para cada domínio no pedido.

Depois de ter adicionado o registro DNS CNAME para todos os domínios no pedido, você estará pronto para a nossa verificação dos registros CNAME.

Método DNS TXT DCV

Siga estas etapas para completar o DNS TXT DCV e demonstrar controle sobre os seus domínios:

  1. Copie dcv_random_value que foi gerado quando o pedido foi feito. Para pedidos OV/EV, é possível recuperar este valor ao usar o ponto de extremidade de informações do domínio e incluir a string de consulta URL include_dcv=true.
  2. Visite o site do seu provedor DNS e crie um novo registro TXT.
  3. No campo Valor TXT, insira o valor aleatório copiado.
  4. Campo Host
    1. Domínio base (por exemplo,[yourdomain].com)
      Você está validando o domínio base? Deixe o campo Host em branco ou adicione o símbolo @ (dependendo dos requisitos do seu fornecedor DNS).
    2. Subdomínio (por exemplo,[your.domain].com)
      Você está validando um subdomínio? No campo Host, adicione o subdomínio que você está validando.
  5. No campo tipo de registro (ou equivalente), selecione TXT.
  6. Selecione um valor para Vida útil (TTL) ou use seu valor padrão do provedor DNS.
  7. Salve o registro.
  8. Repita as etapas acima para cada domínio no pedido.

Depois de ter adicionado o registro DNS TXT para todos os domínios no pedido, você estará pronto para a nossa verificação dos registros TXT.

Método DCV de token HTTP

Siga estas etapas para completar o DCV de token HTTP e demonstrar controle sobre os seus domínios:

  1. Na CertCentral, copie as informações do token HTTP a partir da página de Detalhes do pedido.
  2. No seu editor de texto preferido, cole o valor aleatório copiado.
  3. Salve o arquivo com o nome do arquivo de fileauth.txt.
  4. No seu servidor web, carregue o arquivo fileauth.txt neste local: [yourdomain]/.well-known/pki-validation/fileauth.txt.

Realizar verificação de DCV

Com este token aleatório adicionado ao registro DNS TXT (método DNS TXT) ou o fileauth.txt carregado no local especificado (método DCV de HTTP) para cada domínio no pedido, você está pronto para realizar uma verificação de DCV. Isso é feito através da página Detalhes do pedido na CertCentral.

Na seção de status do Pedido da página, clique em cada domínio ainda listado como DCV pendente e depois clique em "Verificar" para fazer com que o método DCV seja verificado e confirmado.

Validação da organização

Além da validação do domínio, todos os pedidos OV/EV também exigem validação da organização. Depois que um pedido é enviado, a equipe de validação da DigiCert começará a trabalhar no processo de validação da organização OV/EV.

Ambas as validações de organização e domínio devem ser concluídas antes que o certificado possa ser emitido.

Verificar status da validação

É possível verificar o status atual da validação para uma organização com um GET para o pon de extremidade Organization Validation details.

Um GET bem-sucedido a este ponto de extremidade retorna uma resposta HTTP 200 OK.

cURL
curl -X GET \
  'https://www.digicert.com/services/v2/organization/{{organization_id}}/validation' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}'
200 OK
{
  "validations": [
    {
      "type": "ov",
      "name": "OV",
      "description": "Normal Organization Validation",
      "status": "pending"
    },
    {
      "type": "ev",
      "name": "EV",
      "description": "Extended Organization Validation (EV)",
      "status": "pending",
      "verified_users": [
        {
          "id": 12,
          "first_name": "John",
          "last_name": "Smith"
        }
      ]
    }
  ]
}

Verificar status do pedido

Após enviar seu pedido e completar o DCV para cada domínio, você desejará saber quando o status do pedido mudar e o certificado estiver pronto para download. A melhor forma de fazer isso é com um GET ao ponto de extremidade Status change list.

Um GET neste ponto de extremidade retorna três respostas possíveis:

  • 200 OK (matriz orders) – A matriz de pedidos lista todos os pedidos que mudaram de status no período especificado. Quando seu status do pedido mudar de pendente para emitido, ele aparecerá na lista. Se diversos pedidos forem retornados, use a ID do pedido ou ID do certificado para localizar o pedido.
  • 200 OK (objeto vazio) – Uma resposta com um objeto vazio ({}) significa que nenhum pedido teve alteração de status no período especificado. Aumente o período ou aguarde para enviar outra solicitação.
  • 400 Bad Request – Uma resposta com o código de erro time_frame_too_long significa que o período especificado na string de consulta da URL excede o valor máximo. Reduza o período para um valor menor que 10080 minutos (7 dias).

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."
    }
  ]
}

Baixar certificado

Após o status do pedido mudar de pendente para emitido, seu certificado está pronto para ser baixado. Dependendo das suas necessidades, há quatro pontos de extremidade que você pode usar para baixar o certificado:

Reemitir certificado

Reemitir um certificado lhe permite adicionar, remover ou trocar nomes de domínios, atualizar o CSR ou alterar o hash de assinatura de um certificado sem enviar um novo pedido. Um certificado reemitido terá uma nova ID do certificado, mas a mesma ID do pedido. Após a aprovação da reemissão, um novo certificado é emitido e precisa ser instalado.

Ao reemitir um certificado, é necessário fornecer estas informações:

  • Nome comum
  • SANs (incluem as SANs atuais no parâmetro dns_names e quaisquer SANs adicionais a serem protegidas)
  • CSR (para obter e reusar o CSR atual, use o ponto de extremidade Request info)
  • ID da plataforma do servidor (opções listadas aqui)

Mesmo se alguns dos detalhes acima permanecerem os mesmos, ainda é necessário inclui-los na solicitação de reemissão.

Note que certas alterações, como adição de SANs extras (’dns_names’) pode causar custos adicionais.

Pode ser necessário realizar DCV para alguns ou todos os domínios.

O ponto de extremidade Reissue certificate aceita os seguintes parâmetros opcionais:

  • comentários – Adiciona uma mensagem à solicitação para o aprovador.
  • skip_approval -‑ Permite que a solicitação seja imediatamente enviada para validação, ignorando a necessidade de aprovar a solicitação de reemissão.
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
}

Após uma reemissão for concluída, baixe o novo certificado (consulte Baixar certificado).

Você pode obter o histórico completo de reemissão para um pedido ao usar o ponto de extremidade List reissues.

Revogar certificado

Após a emissão do seu certificado, é possível enviar uma solicitação de revogação se necessário.

Todas as solicitações de revogação devem ser aprovadas por um administrador na CertCentral antes da revogação do certificado pela DigiCert. Esta etapa de aprovação é requerida e não pode ser pulada.

Você pode revogar um certificado usando um de dois pontos de extremidade:

  • Revoke certificate – Use este ponto de extremidade para revogar um certificado específico usando a ID do certificado.
  • Revoke order certificate – Use este ponto de extremidade para revogar todos os certificados associados a uma ID do pedido.

Ambos os pontos de extremidade usam os mesmos parâmetros do corpo de solicitação.

Após enviar a solicitação de revogação, a solicitação precisa ser aprovada por um administrador usando o ponto de extremidade Update request status.

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."
}