Общие сведения о работе с сертификатами

Для работы с сертификатами пользователя используются методы:

Метод	Android	iOS	Описание
Policy.getCaParams	Перейти	Перейти	Получение параметров выпуска сертификата.
Cert.getCert	Перейти	Перейти	Создание запроса на сертификат c хранением ключа подписи на сервере.
Cert.getClientCert	Перейти	Перейти	Создание запроса на сертификат c хранением ключа подписи в мобильном устройстве.
Cert.createKeyAndSignRequest	Перейти	Перейти	Создание ключа подписи в мобильном устройстве и подписание запроса на сертификат, отправка запроса на сервер.
Cert.signRequest	Перейти	Перейти	Создание ключа подписи в мобильном устройстве и подписание запроса на сертификат.
Cert.sendSingRequest	Перейти	Перейти	Отправка запроса на сертификат на сервер.
Cert.setCert	Перейти	Перейти	Установка сертификата пользователя на сервере.
Cert.installCertificate	Перейти	Перейти	Установка сертификата пользователя в ключевой контейнер на мобильном устройстве и регистрация сертификата на сервере.
Cert.deleteCert	Перейти	Перейти	Удаление сертификата или запроса на сертификат.
Cert.getCertList	Перейти	Перейти	Получение списка сертификатов пользователя и запросов на сертификаты.
Cert.setNameCert	Перейти	Перейти	Установка дружественного (отображаемого) имени сертификата.
Cert.setDefaultCert	Перейти	Перейти	Установка сертификата по умолчанию.
Cert.revokeCert	Перейти	Перейти	Отзыв сертификата.
Cert.suspendCert	Перейти	Перейти	Приостановка действия сертификата.
Cert.resumeCert	Перейти	Перейти	Восстановление действия сертификата.

Обработка сертификатов и запросов на сертификаты

Обработка сертификатов и запросов на сертификаты осуществляется при помощи подключаемых модулей Удостоверяющих Центров (УЦ).

На сервере могут быть настроены один и более модулей УЦ.

Модуль УЦ может быть двух типов:

Модуль КриптоПро УЦ 2.0,
Модуль стороннего УЦ.

Оба модуля УЦ поддерживают следующие действия:

создание запроса на сертификат,
получение списка сертификатов и запросов на сертификаты,
удаление сертификатов и запросов на сертификаты,
установка сертификата,
назначение дружественного имени сертификата,
установка сертификата по умолчанию.

Дополнительно Модуль КриптоПро УЦ 2.0 поддерживает следующие функции:

отзыв сертификата,
приостановление действия сертификата,
восстановление действия сертификата.

Основные отличия Модуля КриптоПро УЦ 2.0 от Модуля стороннего УЦ:

автоматическая отправка запроса на сертификат в УЦ,
автоматическое получение выпущенного по запросу сертификата,
поддержка отзыва, приостановления и восстановления сертификата.

Модуль стороннего УЦ позволяет только создать запрос на сертификат. Далее запрос на сертификат должен быть выгружен с использованием одного из следующих способов взаимодействия:

REST API сервера,
Веб-интерфейс,
API SDK.

Далее запрос на сертификат должен быть передан в УЦ для обработки и выпуска сертификата.

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

REST API сервера,
Веб-интерфейс,
API SDK.

Мобильное приложение может сохранять информацию о сертификатах и запросах на сертификаты пользователя. Но фактическим источником данных о сертификатах и их статусах является сервер. Мобильное приложение может, например, сохранять информацию о сертификатах в сессии (на время работы приложения). При этом мобильное приложение должно предоставить пользователю возможность запросить актуальные данные по сертификатам и запросам на сертификаты (метод getCertList).

Свойства сертификатов и запросов на сертификаты

Метод getCertList ( Android , iOS ) возвращает список объектов Certificate.

Объект Certificate ( Android , iOS ) представляет собой сертификат или запрос на сертификат пользователя.

У каждого объекта Certificate есть следующие свойства:

type - тип объекта: crt - сертификат, req - запрос на сертификат
caId - идентификатор модуля УЦ, используемого для обработки сертификата и запроса на сертификат.

По идентификатору модуля УЦ можно определить тип модуля УЦ и действия, которые можно производить с сертификатом. Тип модуля УЦ можно определить, зная идентификатор модуля УЦ и получив параметры выпуска сертификатов при помощи метода getCaParams.

Поля rid, cid содержат идентификатор запроса на сертификат или идентификатор сертификата соответственно.
- Если тип объекта crt (сертификат), то заполнено поле cid,
- Если тип объекта req (запрос), то заполнено поле rid. Если по запросу на сертификат выпущен и установлен сертификат, то у объектов типа req будут заполнены оба поля rid, cid. Т.е. запрос на сертификат указывает на соответствующий ему сертификат.
Поле content содержит запрос на сертификат или сертификат в кодировке Base64 и позволяет сохранить сертификат или запроса на сертификат в файл.
- Сертификат представлен в формате X.509.
- Запрос на сертификат представлен в формате PKCS#10
Поле state содержит статус объекта сертификат или запроса на сертификат. Набор статусов зависит от типа объекта.
Поле isDefault содержит флаг, указывающий, что сертификат назначен сертификатом по умолчанию. Используется только для объектов сертификатов (crt)
- Поля notAfter, notBefore содержат сроки действия сертификата в формате Unix Time. Используются только для объектов сертификатов (crt).
Поле dn содержит имя субъекта. Представляет собой словарь - набор компонентов имени субъекта. Каждый компонент представляет собой пару "Объектный идентификатор (OID) - значение". Отображаемые имена и короткие имена можно получить и для параметров модуля УЦ, который используется для обработки запросов на сертификат и сертификатов (метод getCaParams).
Поле issuer содержит имя издателя. Представляет собой словарь - набор компонентов имени субъекта. Каждый компонент представляет собой пару "Объектный идентификатор (OID) - значение". Отображаемые имена и короткие имена можно получить и для параметров модуля УЦ, который исполизуется для обработки запросов на сертификат и сертификатов (метод getCaParams).
Поле serialNumber содержит серийный номер сертификата (HEX-строка).
Поле friendlyName содержит дружественное имя сертификата. Используется только для объектов сертификатов (crt).
Поле isClient содержит флаг, указывающий, хранится ли ключ на устройстве\внешнем носителе (в случае False ключ сохранен на сервере).
ПолеisArchived содержит флаг, указывающий, архивирован ли ключ на сервере.

Статусы запросов на сертификат

У объектов Certificate ( Android , iOS ) типа (type) req могут быть следующие статусы (state). Статус (state) определяет действия, которые можно выполнить с запросом на сертификат.

SIGN_WAIT - Требуется создать ключ подписи в мобильном приложении и подписать запрос на сертификат

Статус возможен только у объектов объектов Certificate типа (type) req с установленным флагом isClient:true.

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

Cert.createKeyAndSignRequest - Android , iOS
Cert.signRequest - Android , iOS
REGISTRATION - Первый запрос на сертификат к КриптоПро УЦ 2.0

Статус применим только для "Модуля КриптоПро УЦ 2.0". Для возможности установки сертификата из файла запрос должен перейти в статус PENDING.

PENDING - Запрос на сертификат принят к обработке в Удостоверяющем Центре

Запросы в данном статусе поддерживают установку сертификата из файла, используя метод setCert Android , iOS .

ACCEPTED - Установлен сертификат, выпущенный по данному запросу

Конечный статус запроса на сертификат. Запрос в данном статусе могут быть только удалены. У запросов на сертификат будут заполнены оба идентификатора rid, cid.

REJECTED - Запрос на сертификат отклонен

Конечный статус запроса на сертификат. Запрос в данном статусе могут быть только удалены.

Запрос на сертификат может пройти следующую цепочку статусов: (SIGN_WAIT) -> (REGISTRATION) -> PENDING -> ACCEPTED/REJECTED. Статусы в круглых скобках опциональны. Переход в данные статусы зависит от способа хранения ключа подписи и типа модуля УЦ.

Статусы сертификата

У объектов Certificate типа (type) crt могут быть следующие статусы (state):

ACTIVE - сертификат действителен и проверен на отзыв,
OUT_OF_ORDER - сертификат действителен, но не проверялся на отзыв.

Сертификаты в статусе ACTIVE и OUT_OF_ORDER могут быть использованы для подписания.

NOT_VALID - сертификат не действителен.

Сертификат не может быть использован для подписания. Возможные причины:

истек срок действия,
корневой сертификат не установлен на сервере,
произошла ошибка при доступе к закрытому ключу сертификата,
модуль КриптоПро УЦ 2.0 вернул неизвестный статус сертификата.

Проверка срока действия сертификата должна дополнительно выполняться локально с использованием полей notAfter, notBefore.

Пользователь должен быть предупрежден о скором истечении срока действия сертификата (за 1-2 недели до окончания срока действия).

REVOKED - сертификат отозван

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

HOLD - сертификат приостановлен

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

Сертификат по умолчанию

Цель назначения сертификата по умолчанию - возможность не передавать идентификатор сертификата в запросах на подпись. Вместо фактического идентификатора должно быть передано значение 0.

Если в запросе на подпись передано значение 0, но сертификат по умолчанию не назначен, сервер вернет ошибку.

Если в серверной операции подписи в description указан идентификатор 0, это означает, что при создании операции подписи использовался сертификат по умолчанию. Для отображения сведений о нем мобильному приложению следует в списке сертификатов (getCertList) найти сертификат (type - crt) с установленным флагом IsDefault.

Выбор модуля УЦ

Метод getCaParams Android , iOS возвращает объект CaParams ( Android , iOS ) содержащий в поле caPolicies список модулей УЦ.

У каждого модуля УЦ есть следующие свойства:

id - идентификатор модуля УЦ. Значение данного поля указывается в объекте Certificate в свойстве caId.
name - отображаемое имя модуля УЦ. Данное значение должно быть отображено пользователю.
caType - тип модуля УЦ:
- DSSOutOfBandEnroll - модуль стороннего УЦ,
- CryptoProCA20Enroll - модуль КриптоПро УЦ 2.0.

Тип модуля УЦ определяет набор действий, которые можно выполнить над сертификатом. Отзыв, приостановление, восстановление возможно только для сертификатов, выпущенных через модуль типа CryptoProCA20Enroll.

namePolicy - шаблон имени субъекта.
ekuTemplates - список шаблонов сертификатов.

Примечание

Другие поля объекта CAPolicy зарезервированы для будущего использования.

Шаблон имени субъекта (namePolicy)

Шаблон имени субъекта представляет собой список из следующих элементов:

oid - Объектный идентификатор компонента имени
name - Отображаемое имя компонента имени
stringIdentifier - Короткое имя компонента имени
isRequired - Требование к заполнению (обязательное/опциональное)
order - Порядковый номер в списке
value - значение по умолчанию

Пользователю должны быть отображены Отображаемое имя и строковый идентификатор.

Пример:

Общее имя (CN)
Адрес (Street)
ИНН (INN)

При создании запроса на сертификат должны быть заполнены обязательные компоненты имени. Опциональные компоненты имени могут остаться незаполненными.

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

Заполненное имя субъекта передается в поле dn метода getCert. Поле dn представляет собой словарь, где в ключе передается OID компонента имени, а в значении - заполненное пользователем значение.

Свойство namePolicy может быть использовано для отображения данных имени субъекта (dn) и издателя (issuer) Certificate. Поля dn и issuer содержат только OID компонентов имени. Отображаемые имена и строковые идентификаторы должны быть получены из namePolicy.

Шаблоны сертификатов (ekuTemplates)

Представляет собой словарь "Имя шаблона - набор OID". Имя шаблона должно быть отображено пользователю.

Набор OID'ов, соответствующий выбранному пользователем именем, должен быть передан при создании запроса на сертификат (getCert). Если набор OID'ов состоит из более чем одного элемента, то все элементы списка объединяются в одну строку через запятую. Сформированная строка шаблона передается в поле tID метода getCert.

Установка сертификата из файла

При установке сертификата из файла setCert ( Android | iOS ) на сервер передается только сертификат. Сервис самостоятельно попытается подобрать соответствующий ему запрос на сертификат. Если запрос на сертификат не был найден, то сервер вернет ошибку.