Ciclo del certificato DV

Il ciclo del certificato DV è composto da questi punti principali:

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

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

  • Riemetti un certificato
  • Revoca un certificato
Ciclo generale del certificato DV

Prepara la richiesta di certificato DV

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

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 DV includono una funzione “più” che ti consente di coprire il sottodominio sia principale che www del tuo dominio senza costi aggiuntivi. 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 DV. 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‑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 Metodi di convalida del controllo del dominio (DCV) 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 un ordine di certificato DV

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 DV SSL.

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 DV SSL – Parametri della richiesta.

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

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 DV 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 DV SSL: 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 TXT DCV

Se non hai più il valore casuale o devi generarne uno nuovo, puoi usare l’endpoint DV SSL: Genera token DCV, sostituendo il segnaposto {{order_id}} con l’ID ordine incluso nel corpo della risposta quando hai inviato l’ordine.

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

  1. Copia il dcv_random_value che è stato riportato nel corpo della risposta quando è stato effettuato l’ordine.
  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 (consulta Verifica DCV).

Metodo HTTP token DCV

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

  1. Copia il dcv_random_value che è stato riportato nel corpo della risposta quando è stato effettuato l’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 con un PUT all’endpoint DV SSL: Verifica DCV.

Un PUT a questo endpoint riporta quattro risposte possibili:

  • 200 OK – DCV completata correttamente
  • 400 richiesta sbagliata – Con questa risposta sono possibili tre codici di errore:
    • invalid_dns_txt – Impossibile trovare record DNS TXT oppure contiene il valore casuale sbagliato per uno o più domini. Verifica che tutti i domini indicati sull’ordine abbiano il record DNS TXT appropriato con il valore casuale corretto.
    • file_random_value_not_found – Impossibile trovare fileauth.txt oppure contiene il valore casuale sbagliato per uno o più domini. Verifica che per tutti i domini indicati sull’ordine il file sia nella directory corretta, sia disponibile pubblicamente e contenga il valore casuale corretto.
    • invalid_dns_method – Il metodo DCV per l’ordine viene impostato su e-mail. Individua l’e-mail inviata e completa le istruzioni DCV o cambia il metodo 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."
    }
  ]
}

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 DV

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 DV

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 DV).

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

Revoca certificato DV

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