Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Руководство разработчика

Attachments

Table of Contents
maxLevel3
outlinetrue
stylenone
excludeРуководство разработчика

Введение

Данный документ содержит описание Java-провайдера JRT11 и способов его использования.

...

Провайдер JRT11 выполнен в стандартном интерфейсе JCA и может использоваться непосредственно через него или же через свой собственный интерфейс.

Использование провайдера JRT11 через интерфейс JCA

JCA представляет собой часть платформы Java, предоставляющую API для криптографических операций электронной подписи, вычисления хеш-суммы сообщений, работы с сертификатами и проверки подлинности сертификатов, шифрования (симметричного/асимметричного, блочного/потокового), генерации ключей и управления ключами. JCA упрощает интеграцию функций безопасности в Java-приложения, избавляя разработчиков от необходимости реализовывать криптографические алгоритмы.

...

Стандартная схема работы с классами этого пакета выглядит примерно одинаково для всех алгоритмов и не вызовет трудностей даже у начинающего разработчика.

Подключение провайдера

JCA имеет архитектуру, основанную на криптопровайдерах – независимых модулях, непосредственно выполняющих криптографические операции по определенным алгоритмам. Программа может просто отправить запрос с определённым типом объекта, реализующего какой-либо криптографический сервис (например, подпись данных по алгоритму ГОСТ 34.10-2001), и получить реализацию от одного из установленных криптопровайдеров.

Для использования провайдера JRT11 в стандартном интерфейсе JCA его необходимо установить и зарегистрировать в списке провайдеров динамическим или статическим способом.

Установка провайдера

Чтобы провайдер считался установленным расширением, его необходимо поместить в стандартную директорию расширений, имеющую адрес

...

где <jre> – директория с установленным JRE или JDK.

Динамическая регистрация провайдера

Провайдер JRT11 реализован классом ru.rutoken.jrt11.JRT11Provider, который наследуется от стандартного класса Provider и может быть добавлен/удален в списке провайдеров по необходимости. Провайдер регистрируется под именем "JRT11".

...

Code Block
languagejava
titleЛистинг 1. Динамическая регистрация провайдера
Security.addProvider(new ru.rutoken.jrt11.JRT11Provider());

Статическая регистрация провайдера

Статическое подключение провайдера выполняется добавлением в конфигурационный файл

...

Подробнее о конфигурационном файле и его назначении см. раздел Сценарии задания конфигурации.

Общая схема работы с классами java.security

Создание объектов JCA

Для осуществления любой криптографической операции, как шифрование/подпись данных или генерация ключевой пары, первым шагом создается объект, реализующий алгоритм, с помощью метода getInstance(). Этот метод является статическим и возвращает ссылку на класс, который обеспечивает выполнение требуемой операции. В качестве аргумента методу getInstance() необходимо передать имя алгоритма. Вторым необязательным аргументом может быть передано либо имя провайдера либо сам объект провайдера. Настоятельно рекомендуется использовать форму getInstance(String algorithm, String provider) или getInstance(String algorithm, Provider provider) с указанием провайдера. Явное указание имени провайдера позволит обеспечить использование алгоритма из нужного провайдера и избавит от возможных конфликтов между различными провайдерами.

Code Block
languagejava
titleЛистинг 3.1 Пример создания объекта хеширования
MessageDigest digest = MessageDigest.getInstance("rtGOST3411", "JRT11");

Использование параметров через интерфейс AlgorithmParameterSpec

После создания объекта его можно инициализировать. В некоторых случаях при инициализации класса предусмотрена возможность передачи параметров, реализующих интерфейс AlgorithmParameterSpec (например, KeyPairGenerator.initialize(java.security.spec.AlgorithmParameterSpec) или Signature.setParameter(java.security.spec.AlgorithmParameterSpec)). Полный список методов, использующих AlgorithmParameterSpec,  доступен по следующей ссылке.

...

Code Block
languagejava
titleЛистинг 3.2 Пример использования расширенных имен алгоритмов
KeyPairGenerator generator = KeyPairGenerator.getInstance("rtGOST3410/1.2.643.2.2.35.1", "JRT11");

Генерация ключей

Генерация ключей шифрования

Провайдер JRT11 позволяет осуществлять генерацию ключей для шифрования данных по алгоритму ГОСТ 28147-89 через стандартный интерфейс JCA при помощи класса KeyGenerator.

...

Code Block
languagejava
titleЛистинг 4. Пример генерации ключа для шифрования по алгоритму ГОСТ 28147-89
KeyGenerator generator = KeyGenerator.getInstance("rt11GOST28147", "JRT11");
SecretKey secret = generator.generateKey();

Генерация ключей подписи

Провайдер JRT11 позволяет осуществлять генерацию ключей для подписи данных по алгоритму ГОСТ Р 34.10-2001 через стандартный интерфейс JCA при помощи класса KeyPairGenerator.

...

Code Block
languagejava
titleЛистинг 5.1. Пример генерации ключевой пары для подписи данных по алгоритму ГОСТ Р 34-10.2001
KeyGenerator generator = KeyGenerator.getInstance("rt11GOST28147rtGOST3410", "JRT11");
SecretKeyKeyPair secretpair = generator.generateKeygenerateKeyPair();

(warning) Так как провайдер JRT11 методом KeyPairGenerator() генерирует ключевую пару сразу на Рутокен, то при ее создание следует сразу указать имя ключевой пары. Это можно сделать путем передачи методу initialize() классом ParamAlias значения имени "alias".

...

Для генерации ключевой пары по алгоритму RSA в качестве имени алгоритма надо задать "rtRSA". Размер ключа задается методом KeyPairGenerator.initialize(int).

Выработка общего сессионного ключа парной связи

Провайдер JRT11 позволяет осуществлять выработку общего ключа парной связи по алгоритму Диффи-Хеллмана через стандартный интерфейс JCA при помощи класса KeyAgreement.

...

Code Block
languagejava
titleЛистинг 6. Пример выработки общего ключа парной связи по алгоритму Диффи-Хеллмана
KeyAgreement agreement = KeyAgreement.getInstance("rtGOST3410", "JRT11");
agreement.init(privateKey, new IvParameterSpec(ivBytes));
agreement.doPhase(publicKey, true);
SecretKey secret = agreement.generateSecret("rt11GOST28147");

Шифрование и расшифрование

Провайдер JRT11 позволяет осуществлять шифрование данных и ключей по алгоритму ГОСТ 28147-89 через стандартный интерфейс JCA при помощи класса Cipher.

Шифрование и расшифрование данных

Для шифрования по алгоритму ГОСТ 28147-89 при создании объекта типа Cipher методом getInstance() в качестве имени алгоритма необходимо указать значение "rt11GOST28147".

...

Code Block
languagejava
titleЛистинг 7.2. Пример расшифрования данных по алгоритму ГОСТ 28147-89
cipher = Cipher.getInstance("rt11GOST28147", "JRT11");
cipher.init(Cipher.DECRYPT_MODE, secret, new IvParameterSpec(iv));
byte[] result = cipher.doFinal(data);

Шифрование и расшифрование ключей

Для шифрования по алгоритму ГОСТ 28147-89 при создании объекта типа Cipher методом getInstance() в качестве имени алгоритма необходимо указать значение "rt11GOST28147".

...

Code Block
languagejava
titleЛистинг 8.2. Пример расшифрования ключа по алгоритму ГОСТ 28147-89
cipher = Cipher.getInstance("rt11GOST28147", "JRT11");
cipher.init(Cipher.UNWRAP_MODE, secret);
byte[] result = cipher.unwrap(unwrappedKey);

Хеширование данных

Провайдер JRT11 позволяет осуществлять хеширование данных по алгоритму ГОСТ Р 34.11-94 через стандартный интерфейс JCA при помощи класса MessageDigest.

...

Code Block
languagejava
titleЛистинг 9. Пример вычисления хеш-суммы ГОСТ Р 34.11-94
MessageDigest messageDigest = MessageDigest.getInstance("rtGOST3411", "JRT11");
messageDigest.update("rtGOST3411".getBytes());
byte[] digestValue = messageDigest.digest();

Подпись и проверка подписи данных

Провайдер JRT11 позволяет осуществлять подпись и проверку подписи данных по алгоритму ГОСТ Р 34.10-2001 через стандартный интерфейс JCA при помощи класса Signature.

...

Для подписи ключом RSA в качестве имени алгоритма надо использовать "MD5withRSA".

Имитозащита данных

Провайдер JRT11 позволяет осуществлять имитозащиту данных по алгоритму ГОСТ 28147-89 через стандартный интерфейс JCA при помощи класса Mac.

...

Code Block
languagejava
titleЛистинг 11. Пример вычисления имитовставки по алгоритму ГОСТ 28147-89
Mac mac = Mac.getInstance("rt11GOST28147", "JRT11");
mac.init(secret);
mac.update(dataBytes);
byte[] macValue = mac.doFinal();

Генерация последовательности случайных чисел

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

...

Code Block
languagejava
titleЛистинг 12. Пример генерации последовательности псевдослучайных чисел
byte[] bytes = new byte[8];
SecureRandom random = SecureRandom.getInstance("rtRandom", "JRT11");
random.nextBytes(bytes);

Хранение ключей

Провайдер JRT11 позволяет осуществлять извлечение ключа из хранилища через стандартный интерфейс JCA при помощи класса KeyStore. Операция извлечения используется для ключей, создаваемых с помощью класса KeyPairGenerator и записываемых сразу на Рутокен.

...

Code Block
languagejava
titleЛистинг 13.2. Пример извлечения открытого ключа из хранилища
KeyStore.Entry entry = keyStore.getEntry("alias", null);
PublicKey publicKey = ((ru.rutoken.security.KeyContainer)entry).getPublicKey();

Использование провайдера JRT11 без интерфейса JCA

Несмотря на удобства своего использования, интерфейс JCA имеет ряд недостатков:

...

Провайдер JRT11 имеет собственный интерфейс, аналогичный JCA и лишенный описанных недостатков.

Краткое описание собственного интерфейса провайдера JRT11

Аналогично интерфейсу JCA, где классы SecureRandom, MessageDigest, KeyPairGenerator, Signature располагаются в пакете java.security, аналогичные классы собственного интерфейса провайдера JRT11 SecureRandom, MessageDigest, KeyPairGenerator, Signature располагаются в пакете в пакете ru.rutoken.security. В этих классах полностью сохранен интерфейс JCA как в плане создания объекта, так и в плане использования: аналогичны используемые методы, параметры, исключения.

...

Классы для работы с шифрованием средствами JCA/JCE находятсяв пакете javax.crypto. По аналогии, классы для работы с шифрованием средствами JRT11 находятся в пакете ru.rutoken.crypto.

Очистка объектов

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

...

  • подписываемые данные,
  • закрытый ключ, с помощью которого производится подпись,
  • объект хранилища, из которого прочитан ключ,
  • PIN-код Пользователя и Администратора Рутокен,
  • и все остальные объекты, которые могут содержать конфиденциальную информацию или способствовать ее получению.

Использование параметров алгоритмов

Провайдер JRT11 позволяет работать с параметрами российских алгоритмов, описанными в стандарте RFC 4357 и обеспечивающими необходимую стойкость. Они обеспечивают совместимость с продуктами других производителей и не рекомендуются к использованию без необходимости. Использование других параметров, стойкость которых неизвестна, не допускается. Использование тестовых параметров допустимо только для целей тестирования.

...

Все алгоритмы, которые реализует провайдер JRT11, имеют параметры по умолчанию и работают без явного указания параметров. Предусмотрено два способа явного задания параметров алгоритмов.

Получениепараметров из фабрики

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

...

В целях обеспечения совместимости c java-классами все используемые параметры реализуют стандартный интерфейс java.security.spec.AlgorithmParameterSpec. Методы, позволяющие устанавливать в алгоритм параметры, реализующие интерфейс AlgorithmParameterSpec, есть в большинстве алгоритмов (см. следующую ссылку) .

Использование расширенных имен алгоритмов

Задать параметры можно непосредственно в имени алгоритма. При создании алгоритма после его имени через разделитель "/" следует указать строковое представление OID.

...

 Этот способ будет работать как при создании алгоритма стандартными средствами JCA из пакета java.security , так и при создании алгоритмов средствами пакета ru.rutoken.security.

Конфигурация PKCS#11

В состав конфигурации PKCS#11 входит 3 параметра:

...

Класс Config реализует интерфейс AlgorithmParameterSpec, поэтому его можно передавать в качестве параметра в некоторые алгоритмы, например, KeyPairGenerator.initialize(int).

Использование класса SessionFactory

Предназначение класса ru.rutoken.jrt11.SessionFactory заключается не только в определении конфигурации PKCS#11, но и выполнении предварительных действий для работы по стандарту PKCS#11: инициализации библиотеки, поиска подключенного Рутокен, открытии сессии и пр. и выдаче параметра для инициализации JCA алгоритма. Подробное описание класса доступно в JavaDoc.

...

Также можно с помощью функции getSession() получить дескриптор открытой сессии и работать с ним.

Сценарии задания конфигурации PKCS#11

Ниже перечислены различные сценарии задания конфигурации PKCS#11.

...

Вы можете выбрать один из этих вариантов, или Вы можете организовать любую комбинацию сценариев, наиболее подходящую для Ваших целей.

Related links

  1. Руководство по применению JCA: http://docs.oracle.com/javase/6/docs/technotes/guides/security/crypto/CryptoSpec.html
  2. Спецификация Java SE 6 API http://docs.oracle.com/javase/6/docs/api/index.html
  3. Загрузка JDK/JDE http://www.oracle.com/technetwork/java/javase/downloads/index.html
  4. Русскоязычное руководство по maven http://www.apache-maven.ru/index.html

Вложения

  1. JavaDoc для разработчиков jdocjrt11-0.5-javadoc.zip