Ciclo del certificato OV/EV

Il ciclo del certificato OV/EV è composto da questi punti principali:

  • Prepara la richiesta di certificato
  • Invia l’ordine di certificato
  • (Opzionale) Annulla l’ordine di certificato
  • Completa Domain Control Validation (DCV)
  • Completa la convalida organizzazione
  • Controlla stato ordine
  • Scarica il certificato emesso

Una volta emesso un certificato, puoi eseguire una di queste azioni:

  • Riemetti un certificato
  • Revoca un certificato

Prepara la richiesta di certificato

Per costruire il corpo della tua richiesta e inviare una richiesta d’ordine, devi raccogliere alcune informazioni importanti:

  • Nomi dominio da proteggere con il certificato.
  • Richiesta di firma certificato (CSR) generata sul server dove sarà installato il certificato.
  • Periodo di validità del certificato (quantità di tempo in cui sarà valido il certificato).
  • Metodo DCV da usare quando dimostri il controllo sui domini.
  • Nome legale e informazioni sulla registrazione per l’Organizzazione da convalidare.

Nomi dominio

Una volta raccolti i nomi dominio da proteggere con il certificato, devono essere inseriti in uno dei due parametri del corpo della richiesta.

Parametro Tipo Descrizione
common_name stringa Dominio principale da proteggere con il certificato.
dns_names matrice Qualsiasi dominio aggiuntivo da proteggere con il certificato.
L’aggiunta di domini a questo parametro può prevedere costi aggiuntivi.

Tutti gli ordini di certificato OV/EV ti consentono di includere gratuitamente un altro SAN specifico sui certificati single domain. Quando costruisci il corpo della tua richiesta, aggiungi il dominio base ([il tuo dominio].com) al parametro common_name, quindi l’altra versione del dominio (www.[il tuo dominio].com) alla matrice dns_names.

Richiesta di firma certificato (CSR)

La CSR deve essere generata sul server dove sarà installato il certificato. Una volta generata, inserisci la CSR formattata PEM nel parametro csr del corpo della richiesta. Per ulteriori informazioni consulta Crea una CSR (richiesta di firma certificato).

Periodo di validità

Quando si ordina un certificato, devi specificare il periodo di validità del certificato. Puoi usare uno qualsiasi di questi parametri per determinare per quanto tempo sarà valido un certificato.

Parametro Tipo Descrizione
validity_years int Usa questo parametro quando specifichi la validità del certificato in anni.
Valori consentiti: 1, 2
validity_days int Usa questo parametro quando specifichi la validità del certificato in giorni.
custom_expiration_date stringa Usa questo parametro per specificare una data specifica in cui scadrà il certificato.
Formato: yyyy-MM-dd

Se nel corpo della richiesta vengono inclusi più parametri di validità, li prioritizziamo come segue: custom_expiration_date > validity_days > validity_years.

Metodi DCV

DCV e-mail è il metodo DCV predefinito usato per gli ordini di certificato OV/ EV. Se lo desideri, puoi cambiare il metodo DCV predefinito includendo il parametro dcv_method nel corpo della richiesta. Il parametro dcv_method accetta questi valori:

Valore Descrizione
email Invia e-mail DCV a tutti gli indirizzi e-mail (ad es. amministratore e contatti tecnici) che troviamo nel record WHOIS del dominio e ai cinque indirizzi e-mail costruiti per il dominio (admin, amministratore, webmaster, hostmaster e postmaster
@[domain_name]).
Quando usi questo metodo, puoi definire un ambito di e-mail specifico includendo l’oggetto dcv_emails.
dns-cname-token Riporta un token di valore casuale nel corpo della risposta da aggiungere ad un record DNS CNAME sul dominio. L’uso di questo metodo richiede la possibilità di modificare i record DNS del dominio.
dns‑txt‑token Riporta un token di valore casuale nel corpo della risposta da aggiungere ad un record DNS TXT sul dominio. L’uso di questo metodo richiede la possibilità di modificare i record DNS del dominio.
http‑token Riporta un token di valore casuale nel corpo della risposta da posizionare in un file .txt sul sito web da proteggere con il certificato. L’uso di questo metodo richiede la possibilità di caricare i file nel server web.

Consulta Dimostra il controllo sui domini in un tuo ordine di certificato in sospeso per ulteriori informazioni sui diversi metodi DCV e su come completarli.

(Opzionale) Matrice dcv_emails

Quando si usa il metodo DCV e-mail, è possibile specificare gli indirizzi e-mail che devono essere usati quando si inviano le e-mail DCV. Per farlo, includi la matrice dcv_emails nel corpo della richiesta e aggiungi una voce per ciascun dominio sull’ordine.

Quando si usa questo parametro, gli indirizzi e-mail inseriti devono essere specificati nel record WHOIS del dominio o devono essere uno degli indirizzo e-mail predefiniti per il dominio (definito dagli standard di settore come: admin, amministratore, webmaster, hostmaster e/o postmaster @[domain_name]). Inoltre, invieremo l’e-mail DCV solo agli indirizzi specificati.

Ad esempio, se specifichi mario.bianchi@[domain_name], non invieremo e-mail DCV a nessuno degli indirizzi e-mail predefiniti. Oppure se specifichi admin@[dominio.com], non invieremo l’e-mail DCV a mario.bianchi@[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"
  }
]

Invia l’ordine di certificato

Ora che hai raccolto le informazioni sopra indicate, sei pronto per costruire il corpo della tua richiesta e inviare la tua richiesta d’ordine. Ciò avviene con un POST all’endpoint Ordina OV/EV SSL. Nota: la linea di prodotti Secure Site viene ordinata tramite un endpoint separato.

I dettagli organizzazione e i contatti vengono inviati qui nell’oggetto organization. Se l’organizzazione ha già un ID assegnato, puoi semplicemente passarlo con la stringa id anziché fornire le informazioni organizzazione complete.

Un POST corretto a questo endpoint riporterà un codice di risposta HTTP 201 creato. Il corpo della risposta include alcune informazioni importanti che vengono usate per controllare lo stato dell’ordine e scaricare il certificato una volta emesso.

  • id – ID ordine usato per controllare i dettagli dell’ordine ed eseguire le azioni DCV.
  • certificate_id – ID certificato usato per scaricare il certificato emesso.
  • dcv_random_value – Token generato casualmente usando per i metodi DCV dns-txt-token e http-token. Questo token scade dopo 30 giorni.

Per altre informazioni su ciascun parametro usato nel corpo della richiesta, consulta la tabella Ordina OV/EV SSL – Parametri della richiesta.

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

Dopo aver inviato l’ordine, puoi usare l’endpoint Informazioni sull'ordine per ottenere i dettagli sull’ordine e revisionare le informazioni inviate.

(Opzionale) Annulla l’ordine di certificato

Dopo aver effettuato un ordine, talvolta potresti doverlo annullare. Per annullare un ordine, devi cambiare lo stato da in attesa ad annullato. Ciò avviene con un PUT all’endpoint Aggiorna stato ordine.

Un PUT corretto a questo endpoint genera una risposta HTTP 204 nessun contenuto.

Il parametro status consente solo un valore CANCELED (osserva le maiuscole/minuscole).

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

Completa Domain Control Validation (DCV)

Con l’ordine OV/EV inviato, ora devi dimostrare il controllo sui domini indicati nell’ordine.

Indipendentemente dal metodo DCV scelto, devi completare la DCV per ciascun dominio da proteggere con il certificato. Ad esempio, se è stato scelto il metodo dns-txt-token, devi creare un record DNS TXT per ciascun dominio indicato sull’ordine.

Metodo DCV e-mail

Se la matrice dcv_emails è stata inclusa nel corpo della risposta, le e-mail DCV vengono inviate agli indirizzi definiti nella matrice. Diversamente, le e-mail DCV vengono inviate a questi indirizzi:

  • Tutti gli indirizzi e-mail trovati nel record WHOIS del dominio
  • Questi cinque indirizzi e-mail costruiti:
    • admin@[domain_name]
    • amministratore@[domain_name]
    • webmaster@[domain_name]
    • hostmaster@[domain_name]
    • postmaster@[domain_name]

Per completare la DCV e-mail, nella casella di posta client della tua e-mail individua l’e-mail con l’oggetto [Azione necessaria] Approva la richiesta di certificato per[iltuodominio] {Ordine n.} e segui le istruzioni.

Se devi reinviare le e-mail DCV per un ordine inviato, puoi usare l’endpoint Invia di nuovo e-mail (sostituisci il segnaposto {{order_id}} con l’ID ordine riportato nel corpo della risposta quando hai inviato l’ordine).

Metodo DNS CNAME DCV

Segui questa procedura per completare DNS CNAME DCV e dimostrare il controllo sui tuoi domini:

  1. Copia il dcv_random_value che è stato generato quando è stato effettuato l’ordine. Per gli ordini OV/EV, puoi recuperare questo valore usando l’endpoint info dominio e includendo la stringa di query URL include_dcv=true.
  2. Vai sul sito del tuo DNS e crea un nuovo record CNAME.
  3. Nel campo del nome host (o equivalente), inserisci il valore casuale che hai copiato.
  4. Nel campo del tipo di record (o equivalente), selezionare CNAME.
  5. Nel campo host target (o equivalente), inserisci dcv.digicert.com (questo punta il record CNAME a dcv.digicert.com).
  6. Seleziona un valore Time-to-Live (TTL) o utilizza il valore predefinito del tuo DNS provider.
  7. Salva il record.
  8. Ripeti la procedura sopra descritta per ciascun dominio indicato sull’ordine.

Una volta che hai aggiunto il record DNS CNAME per tutti i domini sull’ordine, sei pronto per chiederci di verificare i record CNAME.

Metodo DNS TXT DCV

Segui questa procedura per completare DNS TXT DCV e dimostrare il controllo sui tuoi domini:

  1. Copia il dcv_random_value che è stato generato quando è stato effettuato l’ordine. Per gli ordini OV/EV, puoi recuperare questo valore usando l’endpoint info dominio e includendo la stringa di query URL include_dcv=true.
  2. Vai sul sito del to DNS e crea un nuovo record TXT.
  3. Nel campo Valore TXT, inserisci il calore casuale che hai copiato.
  4. Campo Host
    1. Dominio base (ad esempio,[iltuodominio].com)
      Stai convalidando il dominio base? Lascia vuoto il campo Host o aggiungi il simbolo @ (in base ai requisiti del tuo DNS provider).
    2. Sottodominio (ad esempio,[tuo.dominio].com)
      Stai convalidando un sottodominio? Nel campo Host, aggiungi il sottodominio che stai convalidando.
  5. Nel campo del tipo di record (o equivalente), selezionare TXT.
  6. Seleziona un valore Time-to-Live (TTL) o utilizza il valore predefinito del tuo DNS provider.
  7. Salva il record.
  8. Ripeti la procedura sopra descritta per ciascun dominio indicato sull’ordine.

Una volta che hai aggiunto il record DNS TXT per tutti i domini sull’ordine, sei pronto per chiederci di verificare i record TXT.

Metodo HTTP token DCV

Segui questa procedura per completare la HTTP token DCV e dimostrare il controllo sui tuoi domini:

  1. In CertCentral, copia le informazioni sul token HTTP dalla pagina Dettagli ordine.
  2. Nel tuo editor di testo preferito, incolla il valore casuale che hai copiato.
  3. Salva il file con un nome file fileauth.txt.
  4. Sul server web, carica il file fileauth.txt in questa posizione: [iltuodominio]/.well-known/pki-validation/fileauth.txt.

Esegui la verifica DCV

Con il token casuale aggiunto al record DNS TXT (metodo DNS TXT) o il fileauth.txt caricato nella posizione specificata (metodo HTTP DCV) per ciascun dominio sull’ordine, sei pronto per eseguire una verifica DCV. Ciò avviene tramite la pagina Dettagli ordine in CertCentral.

Nella sezione Stato ordine della pagina, fai clic su ciascun dominio ancora elencato come DCV in attesa, quindi fai clic su "Verifica" per controllare e confermare il metodo DCV.

Convalida organizzazione

Oltre alla convalida dominio, tutti gli ordini OV/EV richiedono anche la convalida organizzazione. Una volta inviato un ordine, il team di convalida di DigiCert inizierà a lavorare sul processo di convalida organizzazione OV/EV.

La convalida sia organizzazione che dominio deve essere completata prima di poter emettere il certificato.

Controlla stato convalida

Puoi controllare lo stato convalida attuale per un’organizzazione con un GET nell’endpoint dettagli convalida organizzazione.

Un GET corretto a questo endpoint genera una risposta 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"
        }
      ]
    }
  ]
}

Controlla stato ordine

Dopo aver inviato il tuo ordine e completato la DCV per ciascun dominio, vorrai sapere quando lo stato dell’ordine cambia e quando il certificato è pronto per il download. Il modo migliore per farlo è con un GET all’endpoint elenco di modifica stato.

Un GET a questo endpoint riporta tre risposte possibili:

  • 200 OK (matrice orders) – La matrice degli ordini elenca tutti gli ordini che hanno lo stato cambiato nell’intervallo di tempo specificato. Quando lo stato dell’ordine cambia da in attesa a emesso, sarà visualizzato nell’elenco. Se vengono riportati più ordini, usa l’ID ordine o l’ID certificato per individuare l’ordine.
  • 200 OK (oggetto vuoto) – Una risposta con un oggetto vuoto ({}) significa che nessun ordine ha avuto un cambio di stato nell’intervallo di tempo specificato. Aumenta l’intervallo di tempo o aspetta di inviare un’altra richiesta.
  • 400 richiesta sbagliata – Una risposta con il codice di errore time_frame_too_long significa che l’intervallo di tempo specificato nella stringa di query URL supera il valore massimo. Riduci l’intervallo di tempo ad un valore inferiore a 10.080 minuti (7 giorni).

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

Scarica certificato

Una volta che lo stato ordine cambia da in attesa a emesso, il tuo certificato è pronto per essere scaricato. In base alle tue esigenze, sono disponibili quattro endpoint che puoi usare per scaricare il tuo certificato:

Riemetti certificato

La riemissione di un certificato ti consente di aggiungere, rimuovere o scambiare i nomi di dominio, aggiornare la CSR o cambiare l’hash firma di un certificato senza inviare un nuovo ordine. Un certificato riemesso avrà un nuovo ID certificato ma lo stesso ID ordine. Dopo l’approvazione di una riemissione, viene emesso un nuovo certificato che deve essere reinstallato.

Quando si riemette un certificato, devi fornire queste informazioni:

  • Nome comune
  • SAN (includi sia i SAN attuali nel parametro dns_names che qualsiasi SAN aggiuntivo da proteggere)
  • CSR (per ottenere e riutilizzare la CSR attuale, usa l’endpoint Informazioni richiesta)
  • ID piattaforma server (opzioni elencate qui)

Anche se alcuni dei dettagli sopra riportati rimangono gli stessi, devi ancora includerli nella richiesta di riemissione.

Nota: determinate modifiche, come l'aggiunta di altri SAN (“dns_names”), possono prevedere costi aggiuntivi.

Potrebbe essere necessario eseguire la DCV per alcuni domini o per tutti.

L’endpoint Riemetti certificato accetta i seguenti parametri:

  • commenti – Aggiunge un messaggio alla richiesta per l’approvatore.
  • skip_approval -‑ Consente di inviare immediatamente la richiesta per la convalida, bypassando la necessità di approvare la richiesta di riemissione.
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
}

Dopo il completamento di una riemissione, scarica il nuovo certificato (consulta Scarica certificato).

Puoi richiedere uno storico completo delle riemissioni per un ordine usando l’endpoint Elenca riemissioni.

Revoca certificato

Una volta emesso l’ordine, puoi inviare una richiesta di revoca, se necessario.

Tutte le richieste di revoca devono essere approvate da un amministratore in CertCentral prima che DigiCert revochi il certificato. Questa fase di approvazione è necessaria e non può essere saltata.

Puoi revocare un certificato ricorrendo ad uno di questi due endpoint:

  • Revoca certificato – Usa questo endpoint per revocare un certificato specifico usando l’ID certificato.
  • Revoca certificato ordine – Usa questo endpoint per revocare tutti i certificati associati ad un ID ordine.

Entrambi gli endpoint usano gli stessi parametri del corpo della richiesta.

Dopo aver inviato la richiesta di revoca, la richiesta deve essere approvata da un amministratore usando l’endpoint Aggiorna stato richiesta.

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