Класс KeyStore

public class KeyStore
extends Object

Этот класс представляет собой хранилище криптографических ключей и сертификатов.

Управляющий KeyStore управляет различными типами записей. Каждый тип записи реализует интерфейс KeyStore.Entry. Предоставляются три основных реализации KeyStore.Entry:

• KeyStore.PrivateKeyEntry

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

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

• KeyStore.SecretKeyEntry

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

• KeyStore.TrustedCertificateEntry

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

  Этот тип записи можно использовать для аутентификации других сторон.

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

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

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

Типичные способы запроса объекта KeyStore включают использование типа по умолчанию и предоставление конкретного типа хранилища.

• Чтобы использовать тип по умолчанию:

  KeyStore ks = KeyStore.getInstance(KeyStore.getDefaultType());

  Система вернёт реализацию хранилища для типа по умолчанию.
• Чтобы указать конкретный тип хранилища:

  KeyStore ks = KeyStore.getInstance("JKS");

  Система вернёт наиболее предпочтительную реализацию указанного типа хранилища, доступного в среде.

Перед доступом к хранилищу необходимо loaded.

KeyStore ks = KeyStore.getInstance(KeyStore.getDefaultType());

    // get user password and file input stream
    char[] password = getPassword();

    try (FileInputStream fis = new FileInputStream("keyStoreName")) {
        ks.load(fis, password);
    }

Для создания пустого хранилища с помощью вышеупомянутого load метода передайте null в качестве InputStream аргумента.

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

KeyStore.ProtectionParameter protParam =
        new KeyStore.PasswordProtection(password);

    // get my private key
    KeyStore.PrivateKeyEntry pkEntry = (KeyStore.PrivateKeyEntry)
        ks.getEntry("privateKeyAlias", protParam);
    PrivateKey myPrivateKey = pkEntry.getPrivateKey();

    // save my secret key
    javax.crypto.SecretKey mySecretKey;
    KeyStore.SecretKeyEntry skEntry =
        new KeyStore.SecretKeyEntry(mySecretKey);
    ks.setEntry("secretKeyAlias", skEntry, protParam);

    // store away the keystore
    try (FileOutputStream fos = new FileOutputStream("newKeyStoreName")) {
        ks.store(fos, password);
    }

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

Каждая реализация Java платформы должна поддерживать следующие стандартные KeyStore тип:

• PKCS12

Этот тип описан в разделе KeyStore документации по стандартным именам алгоритмов Java Cryptography Architecture. Обратитесь к документации к вашей реализации, чтобы узнать, поддерживаются ли какие-либо другие типы.

Конструкторы

KeyStore

protected KeyStore(KeyStoreSpi keyStoreSpi,
                   Provider provider,
                   String type)

Создаёт объект KeyStore указанного типа и инкапсулирует в нём указанную реализацию поставщика (объект SPI).

Параметры:

keyStoreSpi - реализация поставщика.

provider - поставщик.

type - тип хранилища ключей.

Методы

getInstance

public static KeyStore getInstance(String type)
                            throws KeyStoreException

Параметры:

type - тип хранилища ключей. См. раздел KeyStore в Документации Java Cryptography Architecture по стандартным именам алгоритмов для получения информации о стандартных типах хранилищ ключей.

Возвращает:

объект хранилища ключей указанного типа.

Исключения:

KeyStoreException - если ни один поставщик не поддерживает реализацию KeyStoreSpi для указанного типа.

См. также:

Provider

getInstance

public static KeyStore getInstance(String type,
                                   String provider)
                            throws KeyStoreException,
                                   NoSuchProviderException

Параметры:

type - тип хранилища ключей. См. раздел KeyStore в Документации Java Cryptography Architecture по стандартным именам алгоритмов для получения информации о стандартных типах хранилищ ключей.

provider - имя поставщика.

Возвращает:

объект хранилища ключей указанного типа.

Исключения:

KeyStoreException - если реализация KeyStoreSpi для указанного типа недоступна от указанного поставщика.

NoSuchProviderException - если указанный поставщик не зарегистрирован в списке поставщиков безопасности.

IllegalArgumentException - если имя поставщика равно null или пустое.

См. также:

Provider

getInstance

public static KeyStore getInstance(String type,
                                   Provider provider)
                            throws KeyStoreException

Параметры:

type - тип хранилища ключей. См. раздел KeyStore в Документации Java Cryptography Architecture по стандартным именам алгоритмов для получения информации о стандартных типах хранилищ ключей.

provider - поставщик.

Возвращает:

объект хранилища ключей указанного типа.

Исключения:

KeyStoreException - если реализация KeyStoreSpi для указанного типа недоступна от указанного объекта поставщика.

IllegalArgumentException - если указанный поставщик равен null.

С тех пор как:

1.4

См. также:

Provider

getDefaultType

public static final String getDefaultType()

Возвращает:

тип хранилища ключей по умолчанию, как указано в свойстве безопасности keystore.type, или строку "jks", если такое свойство не существует.

См. также:

security properties

getProvider

public final Provider getProvider()

Возвращает поставщика этого хранилища ключей.

Возвращает:

поставщик этого хранилища ключей.

getType

public final String getType()

Возвращает тип этого хранилища ключей.

Возвращает:

тип этого хранилища ключей.

getKey

public final Key getKey(String alias,
                        char[] password)
                 throws KeyStoreException,
                        NoSuchAlgorithmException,
                        UnrecoverableKeyException

Возвращает ключ, связанный с заданным псевдонимом, используя заданный пароль для его восстановления. Ключ должен был быть связан с псевдонимом вызовом setKeyEntry, или вызовом setEntry с PrivateKeyEntry или SecretKeyEntry.

Параметры:

alias - имя псевдонима

password - пароль для восстановления ключа

Возвращает:

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

Исключения:

KeyStoreException - если хранилище ключей не было инициализировано (загружено).

NoSuchAlgorithmException - если алгоритм восстановления ключа не найден

UnrecoverableKeyException - если ключ не может быть восстановлен (например, заданный пароль неверный).

getCertificateChain

public final Certificate[] getCertificateChain(String alias)
                                        throws KeyStoreException

Возвращает цепочку сертификатов, связанную с заданным псевдонимом. Цепочка сертификатов должна была быть связана с псевдонимом вызовом setKeyEntry, или вызовом setEntry с PrivateKeyEntry.

Параметры:

alias - имя псевдонима

Возвращает:

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

Исключения:

KeyStoreException - если хранилище ключей не было инициализировано (загружено).

getCertificate

public final Certificate getCertificate(String alias)
                                 throws KeyStoreException

Параметры:

alias - имя псевдонима

Возвращает:

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

Исключения:

KeyStoreException - если хранилище ключей не было инициализировано (загружено).

getCreationDate

public final Date getCreationDate(String alias)
                           throws KeyStoreException

Возвращает дату создания записи, идентифицированной данным псевдонимом.

Параметры:

alias - имя псевдонима

Возвращает:

дата создания этой записи или null, если заданного псевдонима не существует

Исключения:

KeyStoreException - если хранилище ключей не было инициализировано (загружено).

setKeyEntry

public final void setKeyEntry(String alias,
                              Key key,
                              char[] password,
                              Certificate[] chain)
                       throws KeyStoreException

Параметры:

alias - имя псевдонима

key - ключ, который нужно связать с псевдонимом

password - пароль для защиты ключа

chain - цепочка сертификатов для соответствующего открытого ключа (требуется только если заданный ключ типа java.security.PrivateKey).

Исключения:

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

setKeyEntry

public final void setKeyEntry(String alias,
                              byte[] key,
                              Certificate[] chain)
                       throws KeyStoreException

Параметры:

alias - имя псевдонима

key - ключ (в защищённом формате) для привязки к псевдониму

chain - цепочка сертификатов для соответствующего открытого ключа (полезно только если защищённый ключ типа java.security.PrivateKey).

Исключения:

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

setCertificateEntry

public final void setCertificateEntry(String alias,
                                      Certificate cert)
                               throws KeyStoreException

Параметры:

alias - имя псевдонима

cert - сертификат

Исключение:

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

deleteEntry

public final void deleteEntry(String alias)
                       throws KeyStoreException

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

Параметры:

alias - имя псевдонима

Исключение:

KeyStoreException - если хранилище ключей не было инициализировано или запись не может быть удалена.

aliases

public final Enumeration<String> aliases()
                                  throws KeyStoreException

Перечисляет все имена псевдонимов данного хранилища ключей.

Возвращает:

перечисление имен псевдонимов

Исключение:

KeyStoreException - если хранилище ключей не было инициализировано (загружено).

containsAlias

public final boolean containsAlias(String alias)
                            throws KeyStoreException

Проверяет, существует ли данный псевдоним в этом хранилище ключей.

Параметры:

alias - имя псевдонима

Возвращает:

true, если псевдоним существует, false в противном случае

Исключение:

KeyStoreException - если хранилище ключей не было инициализировано (загружено).

size

public final int size()
               throws KeyStoreException

Возвращает количество записей в этом хранилище ключей.

Возвращает:

количество записей в этом хранилище ключей

Исключение:

KeyStoreException - если хранилище ключей не было инициализировано (загружено).

isKeyEntry

public final boolean isKeyEntry(String alias)
                         throws KeyStoreException

Возвращает true, если запись, идентифицированная заданным псевдонимом, была создана вызовом setKeyEntry, или создана вызовом setEntry с PrivateKeyEntry или SecretKeyEntry.

Параметры:

alias - псевдоним записи хранилища ключей, подлежащей проверке

Возвращает:

true, если запись, идентифицированная заданным псевдонимом, является записью, связанной с ключом, иначе — false.

Исключение:

KeyStoreException - если хранилище ключей не было инициализировано (загружено).

isCertificateEntry

public final boolean isCertificateEntry(String alias)
                                 throws KeyStoreException

Возвращает true, если запись, идентифицированная заданным псевдонимом, была создана вызовом setCertificateEntry, или создана вызовом setEntry с TrustedCertificateEntry.

Параметры:

alias - псевдоним записи хранилища ключей, подлежащей проверке

Возвращает:

true, если запись, идентифицированная заданным псевдонимом, содержит доверенный сертификат, иначе — false.

Исключение:

KeyStoreException - если хранилище ключей не было инициализировано (загружено).

getCertificateAlias

public final String getCertificateAlias(Certificate cert)
                                 throws KeyStoreException

Параметры:

cert - сертификат для сопоставления.

Возвращает:

имя псевдонима первой записи с соответствующим сертификатом или null, если такая запись не существует в этом хранилище ключей.

Исключение:

KeyStoreException - если хранилище ключей не было инициализировано (загружено).

store

public final void store(OutputStream stream,
                        char[] password)
                 throws KeyStoreException,
                        IOException,
                        NoSuchAlgorithmException,
                        CertificateException

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

Параметры:

stream - поток вывода, в который записывается это хранилище ключей.

password - пароль для генерации проверки целостности хранилища ключей

Исключение:

KeyStoreException - если хранилище ключей не было инициализировано (загружено).

IOException - если возникла проблема ввода-вывода с данными

NoSuchAlgorithmException - если алгоритм проверки целостности данных не был найден

CertificateException - если любой из сертификатов, включенных в данные хранилища ключей, не может быть сохранён

store

public final void store(KeyStore.LoadStoreParameter param)
                 throws KeyStoreException,
                        IOException,
                        NoSuchAlgorithmException,
                        CertificateException

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

Параметры:

param - LoadStoreParameter, который определяет способ сохранения хранилища ключей, который может быть null

Исключение:

IllegalArgumentException - если заданный LoadStoreParameter ввод не распознан

KeyStoreException - если хранилище ключей не было инициализировано (загружено)

IOException - если возникла проблема ввода-вывода с данными

NoSuchAlgorithmException - если соответствующий алгоритм проверки целостности данных не найден

CertificateException - если любой из сертификатов, включенных в данные хранилища ключей, не может быть сохранен

Since:

1.5

load

public final void load(InputStream stream,
                       char[] password)
                throws IOException,
                       NoSuchAlgorithmException,
                       CertificateException

Параметры:

stream - поток ввода, из которого загружается хранилище ключей, или null

password - пароль, используемый для проверки целостности хранилища ключей, пароль, используемый для разблокировки хранилища ключей, или null

Исключение:

IOException - если есть проблема ввода-вывода или формата с данными хранилища ключей, если пароль необходим, но не указан, или если указанный пароль был неверным. Если ошибка вызвана неправильным паролем, cause IOException должен быть UnrecoverableKeyException

NoSuchAlgorithmException - если алгоритм проверки целостности хранилища ключей не найден

CertificateException - если любой из сертификатов в хранилище ключей не удалось загрузить

load

public final void load(KeyStore.LoadStoreParameter param)
                throws IOException,
                       NoSuchAlgorithmException,
                       CertificateException

Параметры:

param - LoadStoreParameter, который определяет способ загрузки хранилища ключей, который может быть null

Исключение:

IllegalArgumentException - если заданный LoadStoreParameter ввод не распознан

IOException - если возникла проблема ввода-вывода или формата с данными хранилища ключей. Если ошибка вызвана неправильным ProtectionParameter (например, неправильный пароль), cause IOException должен быть UnrecoverableKeyException

NoSuchAlgorithmException - если алгоритм проверки целостности хранилища ключей не найден

CertificateException - если любой из сертификатов в хранилище ключей не удалось загрузить

Since:

1.5

getEntry

public final KeyStore.Entry getEntry(String alias,
                                     KeyStore.ProtectionParameter protParam)
                              throws NoSuchAlgorithmException,
                                     UnrecoverableEntryException,
                                     KeyStoreException

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

Параметры:

alias - получить запись хранилища ключей для данного псевдонима

protParam - ProtectionParameter используемый для защиты Entry, который может быть null

Возвращает:

запись хранилища ключей для указанного псевдонима или null если такой записи нет

Исключение:

NullPointerException - если alias null

NoSuchAlgorithmException - если алгоритм извлечения записи не найден

UnrecoverableEntryException - если указанные protParam были недостаточны или неверны

UnrecoverableKeyException - если запись является PrivateKeyEntry или SecretKeyEntry и указанный protParam не содержит необходимой информации для восстановления ключа (например, неправильный пароль)

KeyStoreException - если хранилище ключей не было инициализировано (загружено).

Since:

1.5

См. также:

setEntry(String, KeyStore.Entry, KeyStore.ProtectionParameter)

setEntry

public final void setEntry(String alias,
                           KeyStore.Entry entry,
                           KeyStore.ProtectionParameter protParam)
                    throws KeyStoreException

Параметры:

alias - сохранить запись хранилища ключей под этим псевдонимом

entry - сохраняемая запись

protParam - ProtectionParameter используемый для защиты Entry, который может быть null

Исключение:

NullPointerException - если alias или entry null

KeyStoreException - если хранилище ключей не было инициализировано (загружено) или данная операция завершается неудачно по какой-либо другой причине

Since:

1.5

См. также:

getEntry(String, KeyStore.ProtectionParameter)

entryInstanceOf

public final boolean entryInstanceOf(String alias,
                                     Class<? extends KeyStore.Entry> entryClass)
                              throws KeyStoreException

Определяет, является ли запись хранилища ключей для указанного alias экземпляром или подклассом указанного entryClass.

Параметры:

alias - псевдоним

entryClass - класс записи

Возвращает:

true, если хранилище ключей Entry для указанного alias является экземпляром или подклассом указанного entryClass, в противном случае false

Исключения:

NullPointerException - если alias или entryClass null

KeyStoreException - если хранилище ключей не было инициализировано (загружено)

Начиная с:

1.5