Класс KJUR.asn1.x509.Certificate

KJUR.asn1.x509.Certificate — класс библиотеки jsrsasign, предназначенный для формирования структуры X.509 сертификата и его последующего кодирования в ASN.1/DER формат. В рамках экосистемы Jsrsasign он используется совместно с криптографическими модулями (RSA/ECDSA), обеспечивая полный цикл создания самоподписанных и подписанных удостоверяющими центрами сертификатов.

Объект сертификата в X.509 представляет собой строго определённую ASN.1 структуру, включающую:

  • версию стандарта
  • серийный номер
  • алгоритм подписи
  • данные издателя (issuer)
  • период действия (validity)
  • данные субъекта (subject)
  • публичный ключ субъекта
  • расширения (extensions)
  • подпись

В KJUR.asn1.x509.Certificate все эти элементы формируются через методы класса, а затем сериализуются в DER и PEM форматы.

Основная идея заключается в том, что разработчик не работает напрямую с ASN.1 деревом, а оперирует высокоуровневыми объектами, которые затем преобразуются в бинарное представление.

Создание экземпляра сертификата

Базовая инициализация:

const cert = new KJUR.asn1.x509.Certificate();

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

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

X.509 поддерживает версии v1, v2 и v3, однако на практике почти всегда используется v3:

cert.setVersionByParam({ version: 3 });

Версия влияет на возможность использования расширений (extensions), которые критичны для современных TLS-сертификатов.

Серийный номер

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

cert.setSerialNumberByParam({ int: "01a3f4b2c9" });

Допустимы как hex-строки, так и десятичные значения.

Период действия сертификата

Время действия задаётся через поля notBefore и notAfter:

cert.setNotBeforeByParam({ str: "230101000000Z" });
cert.setNotAfterByParam({ str: "250101000000Z" });

Формат времени соответствует ASN.1 UTCTime или GeneralizedTime в зависимости от диапазона дат.

Данные субъекта (Subject)

Subject описывает владельца сертификата:

cert.setSubjectByParam({
  str: "/C=RU/O=Example Corp/CN=example.com"
});

DN (Distinguished Name) поддерживает стандартные атрибуты:

  • C — страна
  • O — организация
  • OU — подразделение
  • CN — общее имя
  • L — город
  • ST — регион

Структура DN строго соответствует X.500.

Данные издателя (Issuer)

Issuer определяет удостоверяющий центр, выпустивший сертификат:

cert.setIssuerByParam({
  str: "/C=RU/O=Example CA/CN=Example Root CA"
});

В случае самоподписанного сертификата issuer и subject совпадают.

Публичный ключ

Ключ является центральным элементом сертификата. Он передаётся в объекте ключа Jsrsasign:

const rsaKey = KEYUTIL.generateKeypair("RSA", 2048).pubKeyObj;

cert.setPublicKey(rsaKey);

Поддерживаются RSA и ECDSA ключи, при условии совместимости с KJUR.crypto модулями.

Алгоритм подписи

Алгоритм определяется явно при создании подписи:

cert.signByParam({
  dsa: "SHA256withRSA",
  priKey: privateKey
});

Чаще всего используются:

  • SHA256withRSA
  • SHA384withRSA
  • SHA256withECDSA

Алгоритм должен соответствовать типу ключа.

Формирование самоподписанного сертификата

Типичный сценарий включает генерацию ключевой пары и создание сертификата:

const kp = KEYUTIL.generateKeypair("RSA", 2048);

const cert = new KJUR.asn1.x509.Certificate();

cert.setSerialNumberByParam({ int: "01" });
cert.setIssuerByParam({ str: "/C=RU/O=Test/CN=Test CA" });
cert.setSubjectByParam({ str: "/C=RU/O=Test/CN=example.com" });

cert.setNotBeforeByParam({ str: "240101000000Z" });
cert.setNotAfterByParam({ str: "260101000000Z" });

cert.setPublicKey(kp.pubKeyObj);

cert.signByParam({
  dsa: "SHA256withRSA",
  priKey: kp.prvKeyObj
});

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

Получение PEM представления

Финальный сертификат обычно экспортируется в PEM:

const pem = cert.getPEM();

PEM представляет собой Base64-кодированный DER с заголовками:

-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----

Работа с ASN.1 структурой

Внутри KJUR.asn1.x509.Certificate формируется ASN.1 дерево следующего вида:

  • TBSCertificate

    • version
    • serialNumber
    • signature
    • issuer
    • validity
    • subject
    • subjectPublicKeyInfo
    • extensions (optional)

  • signatureAlgorithm

  • signatureValue

Метод getEncodedHex() позволяет получить DER в hex-формате:

const hex = cert.getEncodedHex();

Расширения сертификата (Extensions)

Для версии v3 поддерживаются расширения:

  • BasicConstraints
  • KeyUsage
  • SubjectAltName
  • ExtendedKeyUsage

Пример добавления:

cert.setExtBasicConstraints({
  cA: false
});

cert.setExtKeyUsage({
  critical: true,
  name: ["digitalSignature", "keyEncipherment"]
});

Расширения критичны для TLS и определения роли сертификата.

Особенности работы с датами

Jsrsasign использует строковое представление времени ASN.1, поэтому важно соблюдать формат:

  • UTCTime: YYMMDDHHMMSSZ
  • GeneralizedTime: YYYYMMDDHHMMSSZ

Ошибки формата приводят к некорректной валидации сертификата на стороне OpenSSL и браузеров.

Валидация и внутренние проверки

Класс не выполняет криптографическую проверку доверия цепочки сертификатов. Он отвечает только за:

  • корректность ASN.1 структуры
  • криптографическую подпись
  • сериализацию данных

Проверка цепочек осуществляется отдельными модулями Jsrsasign (KJUR.x509.Certificate parser и verifier).

Совместимость с TLS-инфраструктурой

Сгенерированные сертификаты совместимы с:

  • OpenSSL
  • Nginx
  • Apache HTTP Server
  • Node.js TLS modules

При условии корректного выбора алгоритмов и длины ключа.

Типичные ошибки при использовании

Неправильная настройка issuer и subject приводит к:

  • невозможности построения цепочки доверия
  • ошибкам браузеров TLS

Несоответствие алгоритма подписи и типа ключа вызывает:

  • bad signature algorithm
  • ошибки при валидации в OpenSSL

Отсутствие расширений в v3 сертификатах часто делает сертификат непригодным для HTTPS.

Взаимодействие с другими компонентами Jsrsasign

KJUR.asn1.x509.Certificate тесно связан с:

  • KEYUTIL — генерация и импорт ключей
  • KJUR.crypto.Signature — криптографическая подпись
  • X509 — парсинг и проверка сертификатов

Типичный рабочий процесс включает генерацию ключа, формирование сертификата и последующую проверку через X.509 парсер.

Оглавление