Жизненный цикл сертификата DV состоит из следующих основных этапов:
После выдачи сертификата вы можете выполнить любое из следующих действий:
Чтобы создать тело запроса и отправить запрос, необходимо собрать несколько ключевых элементов информации:
После того как вы подготовите доменные имена для защиты сертификатом, их следует указать в один из двух параметров тела запроса.
Параметр | Тип | Описание |
---|---|---|
common_name
|
строка | Первичный домен, который будет защищен сертификатом. |
dns_names
|
массив |
Дополнительные домены, которые будут защищены сертификатом. Добавление доменов в данный параметр может повлечь за собой дополнительные расходы. |
Все заказы на сертификаты DV включают функцию «плюс», которая позволяет вам включать как корневой, так и www-субдомен вашего домена без дополнительных затрат. При написании тела запроса добавьте базовый домен ([your-domain].com) к параметру common_name
, а затем другую версию домена (www.[your-domain].com) к массиву dns_names
.
Запрос на подпись сертификата (CSR) должен быть сгенерирован на сервере, где будет установлен сертификат. После создания введите CSR в формате PEM в параметр csr
тела запроса. См. Создать запрос на подпись сертификата (CSR) для ознакомления с дополнительной информацией.
При оформлении заказа на сертификат необходимо указать срок действия сертификата. Вы можете использовать любой из этих параметров, чтобы определить срок действия сертификата.
Параметр | Тип | Описание |
---|---|---|
validity_years
|
int |
Используйте этот параметр при указании срока действия сертификата в годах. Допустимые значения: 1 , 2
|
validity_days
|
int | Используйте этот параметр при указании срока действия сертификата в днях. |
custom_expiration_date
|
строка |
Используйте этот параметр, чтобы указать конкретную дату истечения срока действия сертификата. Формат: yyyy-MM-dd
|
Если в тело запроса включено несколько параметров действительности, мы расставляем их приоритеты следующим образом: custom_expiration_date
> validity_days
> validity_years
.
DCV по электронной почте — это метод DCV по умолчанию, используемый для заказов на сертификаты DV. При желании вы можете изменить метод DCV по умолчанию, включив параметр dcv_method
в тело запроса. Параметр dcv_method
принимает эти значения:
Значение | Описание |
---|---|
email
|
Отправляет электронные письма DCV на любой адрес электронной почты (например, администратора и контактного лица по техническим вопросам), который мы находим в записи WHOIS домена, и на пять созданных адресов электронной почты для домена (админ, администратор, веб-мастер, хост-мастер и администратор электронной почты). @[domain_name]). При использовании этого метода вы можете определить конкретный диапазон электронной почты, включив объект dcv_emails .
|
dns‑txt‑token
|
Возвращает токен с произвольным значением в теле ответа, который будет добавлен к записи TXT DNS в домене. Использование данного метода требует наличия возможности изменения доменных DNS-записей. |
http‑token
|
Возвращает токен с произвольным значением в теле ответа для размещения в текстовом файле на веб-сайте, который должен быть защищен сертификатом. Использование этого метода требует возможности загрузки файлов на веб-сервер. |
См. Метод подтверждения полномочий управления доменом (DCV) для ознакомления с более подробной информацией о различных методах DCV и как способах их выбора.
При использовании метода DCV с использованием электронной почты можно указать адреса электронной почты, которые следует использовать при отправке электронной почты DCV. Для этого включите массив dcv_emails
в тело запроса и добавьте запись для каждого домена в заказе.
При использовании этого параметра введенные адреса электронной почты должны быть указаны в записи WHOIS домена или быть одним из адресов электронной почты по умолчанию для домена (определенные отраслевыми стандартами как: админ, администратор, веб-мастер, хост-мастер и (или) администратор электронной почты @[domain_name]). Кроме того, мы будем отправлять электронную почту DCV только по указанным адресам.
Например, если вы указали john.doe@,[domain_name], мы не будем отправлять электронные письма DCV на какие-либо адреса электронной почты по умолчанию. Или, если вы указали admin@[domain.com,], мы не будем отправлять электронную почту DCV по адресу john.doe@[domain_name].
"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"
}
]
Теперь, когда вы собрали вышеуказанную информацию, вы готовы создать тело запроса и отправить запрос на оформление заказа. Это осуществляется с помощью команды POST для конечной точки заказа SSL DV.
Успешное выполнение команды POST для данной конечной приведет к отображению кода HTTP-ответа 201 Создан. В теле ответа содержатся некоторые ключевые сведения, которые используются для проверки статуса заказа, а также для скачивания сертификата после его выдачи.
id
– Идентификатор заказа, используемый для проверки деталей заказа и выполнения действий DCV.certificate_id
– Идентификатор сертификата, используемый для скачивания выданного сертификата.dcv_random_value
– Произвольно сгенерированный токен, используемый для методов DCV dns-txt-token и http-token. Срок действия этого токена истекает через 30 дней.Для ознакомления с более подробной информацией о каждом параметре, используемом в теле запроса, см. таблицу Заказ DV SSL – Параметры запроса.
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"
}
]
}'
{
"id": 112233,
"certificate_id": 123456
}
{
"id": 112233,
"certificate_id": 123456,
"dcv_random_value": "icru1984rnekfj"
}
После отправки заказа вы можете использовать конечную точку Информация о заказе для получения данных о заказе и просмотра предоставленной информации.
После размещения заказа могут возникать ситуации, вынуждающие вас отменить его. Для отмены заказа необходимо изменить статус с «находящегося на рассмотрении» на «отмененный». Это осуществляется с помощью команды PUT для конечной точки Обновить статус заказа.
Успешное выполнение команды PUT для данной конечной точки приведет к появлению кода HTTP-ответа 204 Нет контента.
Параметр status
допускает только значение CANCELED
(с учетом регистра клавиатуры).
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."
}'
// empty
Отправив заказ DV, вам необходимо подтвердить полномочия управления доменами в заказе.
Независимо от выбранного метода DCV необходимо заполнить DCV для каждого домена, который будет защищен сертификатом. Например, если был выбран метод dns-txt-token
, необходимо создать запись DNS TXT для каждого домена в заказе.
Если массив dcv_emails
был включен в тело ответа, тогда письма DCV будут направляться на адреса, заданные в массиве. В противном случае электронные сообщения DCV будут направляться на следующие адреса электронной почты:
Чтобы оформить электронную почту DCV, в почтовом ящике своего почтового клиента найдите письмо с темой [Требуемое действие] Утверждение запроса на сертификат для[yourdomain] {Заказ №} и следуйте инструкциям.
Если вам необходимо повторно отправить электронные письма DCV для размещенного заказа, вы можете использовать конечную точку DV SSL: Отправить сообщение повторно (замените {{order_id}} символ-заполнитель идентификатором заказа, возвращенным в теле ответа после размещения вами заказа).
Если у вас больше нет произвольного значения или вам нужно сгенерировать новое, вы можете использовать конечную точку DV SSL: Создать токен DCV, заменив {{order_id}} символ-заполнитель идентификатором заказа, который был включен в тело ответа после размещения вами заказа.
Выполните следующие действия, чтобы завершить DNS TXT DCV и продемонстрировать полномочия управления своими доменами:
dcv_random_value
, указанное в теле ответа при размещении заказа.После того, как вы добавите запись DNS TXT для всех доменов в заказе, мы проверим записи TXT (см. «Проверка DCV»).
Выполните следующие действия, чтобы завершить DCV с использованием токена HTTP и продемонстрировать полномочия управления своими доменами:
dcv_random_value
, указанное в теле ответа при размещении заказа.После добавления произвольного токена в запись TXT DNS (метод DNS TXT) или загрузки файла fileauth.txt в указанное местоположение (метод HTTP DCV) для каждого домена в заказе вы готовы выполнить проверку DCV. Это осуществляется с помощью команды PUT для конечной точки DV SSL: Проверка DCV.
PUT для этой конечной точки возвращает четыре возможных ответа:
invalid_dns_txt
– запись DNS TXT не найдена или содержит неправильное произвольное значение для одного или нескольких доменов. Убедитесь, что все домены в заказе имеют соответствующую запись TXT DNS с правильным произвольным значением.file_random_value_not_found
– fileauth.txt не удалось найти или он содержит неправильное произвольное значение для одного или нескольких доменов. Убедитесь, что для всех доменов, указанных в заказе, файл находится в правильном каталоге, он общедоступен и содержит правильное произвольное значение.invalid_dns_method
– В качестве метода DCV для заказа выбрана электронная почта. Либо найдите отправленное письмо и выполните инструкции DCV, либо измените метод DCV.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}}'
{
"order_status": "pending",
"certificate_id": 123456,
"dcv_status": "valid"
}
{
"errors": [
{
"code": "invalid_dns_txt",
"message": "Could not find a valid TXT record for one or more domains."
}
]
}
{
"errors": [
{
"code": "file_random_value_not_found",
"message": "Could not find the random value at the expected file location for one or more domains."
}
]
}
{
"errors": [
{
"code": "invalid_dns_method",
"message": "An error occurred while processing your request."
}
]
}
После отправки своего заказа и завершения DCV для каждого домена вам понадобится узнать, когда изменится статус заказа и готов ли сертификат к скачиванию. Лучшим способом для этого является использование команды GET для конечной точки Список изменений статуса.
GET для этой конечной точки возвращает три возможных ответа:
orders
) – В массиве заказов перечислены все заказы, которые сменили статус за указанный период времени. Когда статус вашего заказа изменится с «находящегося на рассмотрении» на «выданный», он появится в списке. Если возвращается несколько заказов, используйте либо идентификатор заказа, либо идентификатор сертификата, чтобы найти заказ.{}
) означает, что ни один заказ не сменил статус за указанный период времени. Либо увеличьте период времени, либо дождитесь отправки другого запроса.time_frame_too_long
означает, что период времени, указанный в строке запроса URL-адреса, превышает максимальное значение. Уменьшите период времени до значения менее 10080 минут (7 дней).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}}'
{
"orders": [
{
"order_id": 112233,
"certificate_id": 123456,
"status": "issued"
}
]
}
{}
{
"errors": [
{
"code": "time_frame_too_long",
"message": "An error occurred while processing your request."
}
]
}
Как только статус заказа изменится с «находящегося на рассмотрении» на «выданный», ваш сертификат готов к скачиванию. В зависимости от ваших потребностей для скачивания сертификата вы можете использовать четыре конечные точки:
Повторный выпуск сертификата позволяет добавлять, удалять или изменять доменные имена, обновлять CSR или изменять хэш подписи сертификата без отправки нового заказа. У переизданного сертификата будет новый идентификатор сертификата, но тот же идентификатор заказа. После утверждения повторного выпуска выдается новый сертификат, который необходимо переустановить.
При переоформлении сертификата вам необходимо предоставить следующую информацию:
Даже если некоторые из вышеперечисленных данных остаются прежними, вам все равно необходимо включить их в запрос на повторный выпуск.
Обратите внимание на то, что определенные изменения, например, добавление дополнительных альтернативных имен субъектов («dns_names»), могут повлечь за собой дополнительные расходы.
Может возникнуть необходимость выполнить DCV для некоторых или всех доменов.
Конечная точка Повторный выпуск сертификатов принимает следующие необязательные параметры:
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
}
}'
{
"id": 112233,
"requests": [
{
"id": 332211
}
]
}
{
"id": 112233,
"certificate_id": 111112
}
После завершения повторного выпуска скачайте новый сертификат (см. Скачать сертификат DV).
Вы можете просмотреть полные статистические данные повторного выпуска для заказа, используя конечную точку Список повторных выпусков.
После того, как ваш заказ будет оформлен, вы можете отправить запрос на отзыв, если это необходимо.
Все запросы на отзыв должны быть утверждены администратором CertCentral, прежде чем DigiCert отзовет сертификат. Этот шаг утверждения является обязательным, его нельзя пропустить.
Вы можете отозвать сертификат, используя одну из двух конечных точек:
Обе конечные точки используют одинаковые параметры тела запроса.
После отправки запроса на отзыв запрос должен быть утвержден администратором с использованием конечной точки Состояние запроса на обновление.
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."
}'
{
"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."
}