Жизненный цикл сертификата DV

Жизненный цикл сертификата DV состоит из следующих основных этапов:

Подготовка запроса на сертификат DV
Направление заказа на сертификат DV
(Необязательно) Отмена заказа на сертификат
Завершение процедуры подтверждения полномочий управления доменом (DCV)
Проверка статуса заказа
Скачивание выпущенного сертификата

После выдачи сертификата вы можете выполнить любое из следующих действий:

Повторно выпустить сертификат
Отозвать сертификат

Подготовка запроса на сертификат DV

Чтобы создать тело запроса и отправить запрос, необходимо собрать несколько ключевых элементов информации:

Доменное имя (имена), которое будет защищено сертификатом
Запрос на подпись сертификата (CSR), сгенерированный на сервере, где будет установлен сертификат
Срок действия сертификата (продолжительность времени, в течение которого будет действовать сертификат)
Метод DCV, используемый для демонстрации полномочий управлять доменом (доменами)

Доменное имя (имена)

После того как вы подготовите доменные имена для защиты сертификатом, их следует указать в один из двух параметров тела запроса.

Параметр	Тип	Описание
`common_name`	строка	Первичный домен, который будет защищен сертификатом.
`dns_names`	массив	Дополнительные домены, которые будут защищены сертификатом. Добавление доменов в данный параметр может повлечь за собой дополнительные расходы.

Все заказы на сертификаты DV включают функцию «плюс», которая позволяет вам включать как корневой, так и www-субдомен вашего домена без дополнительных затрат. При написании тела запроса добавьте базовый домен ([your-domain].com) к параметру common_name, а затем другую версию домена (www.[your-domain].com) к массиву dns_names.

Запрос на подпись сертификата (CSR)

Запрос на подпись сертификата (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 по электронной почте — это метод 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_emails

При использовании метода DCV с использованием электронной почты можно указать адреса электронной почты, которые следует использовать при отправке электронной почты DCV. Для этого включите массив dcv_emails в тело запроса и добавьте запись для каждого домена в заказе.

При использовании этого параметра введенные адреса электронной почты должны быть указаны в записи WHOIS домена или быть одним из адресов электронной почты по умолчанию для домена (определенные отраслевыми стандартами как: админ, администратор, веб-мастер, хост-мастер и (или) администратор электронной почты @[domain_name]). Кроме того, мы будем отправлять электронную почту DCV только по указанным адресам.

Например, если вы указали john.doe@,[domain_name], мы не будем отправлять электронные письма DCV на какие-либо адреса электронной почты по умолчанию. Или, если вы указали admin@[domain.com,], мы не будем отправлять электронную почту DCV по адресу 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"
  }
]

Направление заказа на сертификат DV

Теперь, когда вы собрали вышеуказанную информацию, вы готовы создать тело запроса и отправить запрос на оформление заказа. Это осуществляется с помощью команды POST для конечной точки заказа SSL DV.

Успешное выполнение команды POST для данной конечной приведет к отображению кода HTTP-ответа 201 Создан. В теле ответа содержатся некоторые ключевые сведения, которые используются для проверки статуса заказа, а также для скачивания сертификата после его выдачи.

id – Идентификатор заказа, используемый для проверки деталей заказа и выполнения действий DCV.
certificate_id – Идентификатор сертификата, используемый для скачивания выданного сертификата.
dcv_random_value – Произвольно сгенерированный токен, используемый для методов DCV dns-txt-token и http-token. Срок действия этого токена истекает через 30 дней.

Для ознакомления с более подробной информацией о каждом параметре, используемом в теле запроса, см. таблицу Заказ DV SSL – Параметры запроса.

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

После отправки заказа вы можете использовать конечную точку Информация о заказе для получения данных о заказе и просмотра предоставленной информации.

(Необязательно) Отмена заказа на сертификат

После размещения заказа могут возникать ситуации, вынуждающие вас отменить его. Для отмены заказа необходимо изменить статус с «находящегося на рассмотрении» на «отмененный». Это осуществляется с помощью команды PUT для конечной точки Обновить статус заказа.

Успешное выполнение команды PUT для данной конечной точки приведет к появлению кода HTTP-ответа 204 Нет контента.

Параметр status допускает только значение CANCELED (с учетом регистра клавиатуры).

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

Завершение процедуры подтверждения полномочий управления доменом (DCV)

Отправив заказ DV, вам необходимо подтвердить полномочия управления доменами в заказе.

Независимо от выбранного метода DCV необходимо заполнить DCV для каждого домена, который будет защищен сертификатом. Например, если был выбран метод dns-txt-token, необходимо создать запись DNS TXT для каждого домена в заказе.

Метод DCV с использованием электронной почты

Если массив dcv_emails был включен в тело ответа, тогда письма DCV будут направляться на адреса, заданные в массиве. В противном случае электронные сообщения DCV будут направляться на следующие адреса электронной почты:

Все адреса электронной почты, найденные в записи WHOIS домена
Данные пять созданных адресов электронной почты:
- admin@[domain_name]
- administrator@[domain_name]
- webmaster@[domain_name]
- hostmaster@[domain_name]
- postmaster@[domain_name]

Чтобы оформить электронную почту DCV, в почтовом ящике своего почтового клиента найдите письмо с темой [Требуемое действие] Утверждение запроса на сертификат для[yourdomain] {Заказ №} и следуйте инструкциям.

Если вам необходимо повторно отправить электронные письма DCV для размещенного заказа, вы можете использовать конечную точку DV SSL: Отправить сообщение повторно (замените {{order_id}} символ-заполнитель идентификатором заказа, возвращенным в теле ответа после размещения вами заказа).

Метод DNS TXT DCV

Если у вас больше нет произвольного значения или вам нужно сгенерировать новое, вы можете использовать конечную точку DV SSL: Создать токен DCV, заменив {{order_id}} символ-заполнитель идентификатором заказа, который был включен в тело ответа после размещения вами заказа.

Выполните следующие действия, чтобы завершить DNS TXT DCV и продемонстрировать полномочия управления своими доменами:

Скопируйте dcv_random_value, указанное в теле ответа при размещении заказа.
Перейдите на сайт вашего провайдера DNS и создайте новую запись TXT.
В поле «Значение TXT» вставьте скопированное произвольное значение.
Поле Узел
1. Базовый домен (например,[yourdomain].com)
  Вы проверяете достоверность базового домена? Оставьте поле «Узел» пустым или добавьте символ @ (в зависимости от требований вашего провайдера DNS).
2. Субдомен (например,[your.domain].com)
  Вы проверяете достоверность субдомена? В поле «Узел» добавьте субдомен, достоверность которого вы проверяете.
В поле типа записи (или в другом аналогичном поле) выберите TXT.
Выберите значение времени жизни (TTL) либо используйте значение по умолчанию, установленное вашим провайдером DNS.
Сохраните запись.
Повторите указанные выше действия для каждого домена в заказе.

После того, как вы добавите запись DNS TXT для всех доменов в заказе, мы проверим записи TXT (см. «Проверка DCV»).

Метод DCV с использованием токена HTTP

Выполните следующие действия, чтобы завершить DCV с использованием токена HTTP и продемонстрировать полномочия управления своими доменами:

Скопируйте dcv_random_value, указанное в теле ответа при размещении заказа.
Вставьте произвольное значение, которое вы скопировали, в выбранном вами текстовом редакторе.
Сохраните файл с именем файла fileauth.txt.
На своем веб-сервере загрузите файл fileauth.txt в это место: [yourdomain]/.well-known/pki-validation/fileauth.txt.

Выполните проверку DCV

После добавления произвольного токена в запись TXT DNS (метод DNS TXT) или загрузки файла fileauth.txt в указанное местоположение (метод HTTP DCV) для каждого домена в заказе вы готовы выполнить проверку DCV. Это осуществляется с помощью команды PUT для конечной точки DV SSL: Проверка DCV.

PUT для этой конечной точки возвращает четыре возможных ответа:

200 OK – DCV успешно завершена
400 Неверный запрос – Существует три возможных кода ошибки с этим ответом:
- invalid_dns_txt – запись DNS TXT не найдена или содержит неправильное произвольное значение для одного или нескольких доменов. Убедитесь, что все домены в заказе имеют соответствующую запись TXT DNS с правильным произвольным значением.
- file_random_value_not_found – fileauth.txt не удалось найти или он содержит неправильное произвольное значение для одного или нескольких доменов. Убедитесь, что для всех доменов, указанных в заказе, файл находится в правильном каталоге, он общедоступен и содержит правильное произвольное значение.
- invalid_dns_method – В качестве метода DCV для заказа выбрана электронная почта. Либо найдите отправленное письмо и выполните инструкции DCV, либо измените метод 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."
    }
  ]
}

Проверка статуса заказа

После отправки своего заказа и завершения DCV для каждого домена вам понадобится узнать, когда изменится статус заказа и готов ли сертификат к скачиванию. Лучшим способом для этого является использование команды GET для конечной точки Список изменений статуса.

GET для этой конечной точки возвращает три возможных ответа:

200 OK (массив orders) – В массиве заказов перечислены все заказы, которые сменили статус за указанный период времени. Когда статус вашего заказа изменится с «находящегося на рассмотрении» на «выданный», он появится в списке. Если возвращается несколько заказов, используйте либо идентификатор заказа, либо идентификатор сертификата, чтобы найти заказ.
200 OK (пустой объект) – Ответ с пустым объектом ({}) означает, что ни один заказ не сменил статус за указанный период времени. Либо увеличьте период времени, либо дождитесь отправки другого запроса.
400 Неверный запрос – Ответ с кодом ошибки time_frame_too_long означает, что период времени, указанный в строке запроса URL-адреса, превышает максимальное значение. Уменьшите период времени до значения менее 10080 минут (7 дней).

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

Скачать сертификат DV

Как только статус заказа изменится с «находящегося на рассмотрении» на «выданный», ваш сертификат готов к скачиванию. В зависимости от ваших потребностей для скачивания сертификата вы можете использовать четыре конечные точки:

Использование идентификатора сертификата:
- Скачать сертификат
- Скачать сертификат по формату
Использование идентификатора заказа:
- Скачать сертификат (order_id)
- Скачать сертификат по формату (order_id)

Повторный выпуск сертификата DV

Повторный выпуск сертификата позволяет добавлять, удалять или изменять доменные имена, обновлять CSR или изменять хэш подписи сертификата без отправки нового заказа. У переизданного сертификата будет новый идентификатор сертификата, но тот же идентификатор заказа. После утверждения повторного выпуска выдается новый сертификат, который необходимо переустановить.

При переоформлении сертификата вам необходимо предоставить следующую информацию:

Общее имя
Альтернативные имена субъектов (SAN) (включите в параметр dns_names как текущие SAN, так и любые дополнительные SAN, которые необходимо защитить)
CSR (чтобы получить и повторно использовать текущий CSR, используйте конечную точку Запрос информации)
Идентификатор платформы сервера (параметры указаны здесь)

Даже если некоторые из вышеперечисленных данных остаются прежними, вам все равно необходимо включить их в запрос на повторный выпуск.

Обратите внимание на то, что определенные изменения, например, добавление дополнительных альтернативных имен субъектов («dns_names»), могут повлечь за собой дополнительные расходы.

Может возникнуть необходимость выполнить DCV для некоторых или всех доменов.

Конечная точка Повторный выпуск сертификатов принимает следующие необязательные параметры:

комментарии – добавляет сообщение к запросу для утверждающего лица.
skip_approval -‑ Позволяет немедленно отправить запрос на подтверждение действительности без утверждения запроса на повторный выпуск.

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
}

После завершения повторного выпуска скачайте новый сертификат (см. Скачать сертификат DV).

Вы можете просмотреть полные статистические данные повторного выпуска для заказа, используя конечную точку Список повторных выпусков.

Отзыв сертификата DV

После того, как ваш заказ будет оформлен, вы можете отправить запрос на отзыв, если это необходимо.

Все запросы на отзыв должны быть утверждены администратором CertCentral, прежде чем DigiCert отзовет сертификат. Этот шаг утверждения является обязательным, его нельзя пропустить.

Вы можете отозвать сертификат, используя одну из двух конечных точек:

Отозвать сертификат – Используйте эту конечную точку для отзыва определенного сертификата, используя идентификатор сертификата.
Отозвать сертификат по заказу – Используйте эту конечную точку для отзыва всех сертификатов, связанных с идентификатором заказа.

Обе конечные точки используют одинаковые параметры тела запроса.

После отправки запроса на отзыв запрос должен быть утвержден администратором с использованием конечной точки Состояние запроса на обновление.

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

Подготовка запроса на сертификат DV

Доменное имя (имена)

Запрос на подпись сертификата (CSR)

Период действия

Метод DCV

(Необязательно) массив dcv_emails

Направление заказа на сертификат DV

(Необязательно) Отмена заказа на сертификат

Завершение процедуры подтверждения полномочий управления доменом (DCV)

Метод DCV с использованием электронной почты

Метод DNS TXT DCV

Метод DCV с использованием токена HTTP

Выполните проверку DCV

Проверка статуса заказа

Скачать сертификат DV

Повторный выпуск сертификата DV

Отзыв сертификата DV

О проекте