Импорт ключей: KEYUTIL.getKey

Функция KEYUTIL.getKey из библиотеки jsrsasign предназначена для универсального импорта криптографических ключей различных форматов в единое внутреннее представление. Это ключевая точка входа при работе с RSA, EC и другими алгоритмами, поскольку большинство операций (подпись, проверка, шифрование) требуют объект ключа, а не его строковое представление.

Поддерживаются как открытые, так и закрытые ключи, включая защищённые паролем. Функция автоматически определяет формат входных данных и преобразует их в соответствующий объект (RSAKey, KJUR.crypto.ECDSA и др.).

Поддерживаемые форматы ключей

KEYUTIL.getKey обрабатывает широкий спектр форматов:

PEM (Privacy-Enhanced Mail):

  • PKCS#1 (RSA PRIVATE KEY, RSA PUBLIC KEY)
  • PKCS#8 (PRIVATE KEY, ENCRYPTED PRIVATE KEY)
  • X.509 (PUBLIC KEY)

DER (в виде hex-строки):

  • ASN.1-структуры ключей

JWK (JSON Web Key):

  • Объекты JavaScript с параметрами ключа

Сырые параметры:

  • Объекты с полями n, e, d для RSA

Базовый синтаксис

var keyObj = KEYUTIL.getKey(key, passcode);
  • key — строка, объект или hex-данные
  • passcode — пароль для зашифрованных ключей (опционально)

Импорт PEM-ключа

Пример: открытый ключ

var pubKeyPEM = `
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...
-----END PUBLIC KEY-----
`;

var pubKey = KEYUTIL.getKey(pubKeyPEM);

Результат — объект RSA, пригодный для проверки подписи или шифрования.

Импорт приватного ключа

var prvKeyPEM = `
-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA...
-----END RSA PRIVATE KEY-----
`;

var prvKey = KEYUTIL.getKey(prvKeyPEM);

Объект содержит все необходимые параметры (n, e, d, p, q).

Работа с зашифрованными ключами

Если ключ защищён паролем:

var encKeyPEM = `
-----BEGIN ENCRYPTED PRIVATE KEY-----
MIIFHjB...
-----END ENCRYPTED PRIVATE KEY-----
`;

var key = KEYUTIL.getKey(encKeyPEM, "password123");

Функция автоматически:

  • распознаёт алгоритм шифрования
  • выполняет расшифровку
  • возвращает готовый объект ключа

Импорт JWK (JSON Web Key)

var jwk = {
  kty: "RSA",
  n: "sXchv...",
  e: "AQAB",
  d: "Vwxyz..."
};

var key = KEYUTIL.getKey(jwk);

Поддерживаются как публичные, так и приватные JWK.

Импорт из hex (DER)

var hexKey = "3082010A0282010100...";
var key = KEYUTIL.getKey(hexKey);

Используется при работе с бинарными ASN.1 структурами.

Импорт из параметров RSA

var key = KEYUTIL.getKey({
  n: "a1b2c3...",
  e: "010001",
  d: "deadbeef..."
});

Полезно при ручной сборке ключей или интеграции с другими системами.

Автоопределение типа ключа

KEYUTIL.getKey самостоятельно определяет:

  • тип алгоритма (RSA, EC)
  • формат (PKCS#1, PKCS#8, JWK)
  • наличие шифрования

Это избавляет от необходимости вручную указывать формат.

Обработка ошибок

При некорректных данных возможны ошибки:

  • неверный формат PEM
  • неправильный пароль
  • повреждённая ASN.1 структура

Рекомендуется оборачивать вызов в try/catch:

try {
  var key = KEYUTIL.getKey(pem, password);
} catch (e) {
  console.error("Ошибка импорта ключа:", e);
}

Внутренние типы объектов

В зависимости от входных данных возвращаются:

  • RSAKey — для RSA
  • KJUR.crypto.ECDSA — для эллиптических кривых
  • DSA — для DSA (ограниченная поддержка)

Каждый объект содержит методы:

  • sign
  • verify
  • encrypt
  • decrypt

Пример полного цикла

var pem = `-----BEGIN PRIVATE KEY-----...`;
var key = KEYUTIL.getKey(pem);

var sig = new KJUR.crypto.Signature({ alg: "SHA256withRSA" });
sig.init(key);
sig.updateString("data");
var signature = sig.sign();

Особенности работы с EC-ключами

var ecKeyPEM = `-----BEGIN EC PRIVATE KEY-----...`;
var key = KEYUTIL.getKey(ecKeyPEM);

Возвращается объект ECDSA, содержащий:

  • кривую (curve)
  • координаты (x, y)
  • приватный параметр (d)

Безопасность и ограничения

  • Пароль не кэшируется — его нужно передавать при каждом импорте
  • PEM должен быть корректно форматирован (переносы строк обязательны)
  • Поддержка некоторых старых алгоритмов (например, DES-EDE3) ограничена

Частые проблемы

Ошибка “unsupported format”

  • неверный заголовок PEM
  • отсутствует BEGIN/END

Ошибка расшифровки

  • неправильный пароль
  • неподдерживаемый алгоритм шифрования

Некорректный JWK

  • отсутствуют обязательные поля (n, e)

Практические рекомендации

  • Использовать PKCS#8 для универсальности
  • Предпочитать JWK при работе с веб-приложениями
  • Проверять формат ключа перед импортом
  • Хранить ключи в безопасном виде (не в открытом коде)

Связанные функции

  • KEYUTIL.generateKeypair — генерация ключей
  • KEYUTIL.getPEM — экспорт ключа обратно в PEM
  • KEYUTIL.getJWKFromKey — преобразование в JWK

Поведение при разных входных типах

Тип входа Результат
PEM строка Объект ключа
Hex DER Объект ключа
JWK Объект ключа
JS объект Объект ключа

Производительность

  • Импорт PEM — быстрый (парсинг строки)
  • Расшифровка — зависит от алгоритма
  • JWK — наиболее быстрый формат

Итоговое назначение

KEYUTIL.getKey выступает универсальным преобразователем ключей, обеспечивая совместимость различных форматов и упрощая криптографические операции внутри jsrsasign.

Оглавление