Класс CipherSpi

public abstract class CipherSpi
extends Object

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

Для создания экземпляра Cipher, который инкапсулирует экземпляр этого класса CipherSpi, приложение вызывает один из методов фабрики getInstance класса движка Cipher и указывает требуемую трансформацию. Приложение также может указать имя поставщика.

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

Трансформация имеет вид:

• "алгоритм/режим/заполнение" или
• "алгоритм"

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

Cipher c = Cipher.getInstance("AES/CBC/PKCS5Padding");

Поставщик может предоставить отдельный класс для каждой комбинации алгоритм/режим/заполнение или решить предоставить более общие классы, представляющие подтрансформации, соответствующие алгоритм или алгоритм/режим или алгоритм//заполнение (обратите внимание на двойные слэши), в этом случае запрашиваемый режим и/или схема заполнения устанавливаются автоматически методами getInstance класса Cipher, которые вызывают методы engineSetMode и engineSetPadding подкласса поставщика класса CipherSpi.

Свойство Cipher в классе-мастере поставщика может иметь один из следующих форматов:

• // provider's subclass of "CipherSpi" implements "algName" with
       // pluggable mode and padding
       Cipher.algName

• // provider's subclass of "CipherSpi" implements "algName" in the
       // specified "mode", with pluggable padding
       Cipher.algName/mode

• // provider's subclass of "CipherSpi" implements "algName" with the
       // specified "padding", with pluggable mode
       Cipher.algName//padding

• // provider's subclass of "CipherSpi" implements "algName" with the
       // specified "mode" and "padding"
       Cipher.algName/mode/padding

Например, поставщик может предоставить подкласс CipherSpi, который реализует AES/ECB/PKCS5Padding, один, который реализует AES/CBC/PKCS5Padding, один, который реализует AES/CFB/PKCS5Padding, и ещё один, который реализует AES/OFB/PKCS5Padding. У этого поставщика в его классе-мастере будут следующие свойства Cipher:

• Cipher.AES/ECB/PKCS5Padding

• Cipher.AES/CBC/PKCS5Padding

• Cipher.AES/CFB/PKCS5Padding

• Cipher.AES/OFB/PKCS5Padding

Другой поставщик может реализовать класс для каждого из вышеперечисленных режимов (т. е. один класс для ECB, один для CBC, один для CFB и один для OFB), один класс для PKCS5Padding и общий класс AES, который наследуется от CipherSpi. У этого поставщика в его классе-мастере будут следующие свойства Cipher:

• Cipher.AES

Метод фабрики getInstance класса движка Cipher следует этим правилам для создания реализации поставщика CipherSpi для трансформации вида "алгоритм":

1. Проверить, зарегистрировал ли поставщик подкласс CipherSpi для заданного "алгоритм".

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

   Если ответ НЕТ, выбросить исключение NoSuchAlgorithmException.

Метод фабрики getInstance класса движка Cipher следует этим правилам для создания реализации поставщика CipherSpi для трансформации вида "алгоритм/режим/заполнение":

1. Проверить, зарегистрировал ли поставщик подкласс CipherSpi для заданной трансформации "алгоритм/режим/заполнение".

   Если ответ ДА, создать его экземпляр.

   Если ответ НЕТ, перейти к следующему шагу.

2. Проверить, зарегистрировал ли поставщик подкласс CipherSpi для подтрансформации "алгоритм/режим".

   Если ответ ДА, создать его экземпляр и вызвать метод engineSetPadding(padding) для нового экземпляра.

   Если ответ НЕТ, перейти к следующему шагу.

3. Проверить, зарегистрировал ли поставщик подкласс CipherSpi для подтрансформации "алгоритм//заполнение" (обратите внимание на двойные слэши).

   Если ответ ДА, создать его экземпляр и вызвать метод engineSetMode(mode) для нового экземпляра.

   Если ответ НЕТ, перейти к следующему шагу.

4. Проверить, зарегистрировал ли поставщик подкласс CipherSpi для подтрансформации "алгоритм".

   Если ответ ДА, создать его экземпляр и вызвать методы engineSetMode(mode) и engineSetPadding(padding) для нового экземпляра.

   Если ответ НЕТ, выбросить исключение NoSuchAlgorithmException.

Краткое описание конструкторов

CipherSpi

public CipherSpi()

Краткое описание методов

engineSetMode

protected abstract void engineSetMode(String mode)
                               throws NoSuchAlgorithmException

Устанавливает режим шифра.

Параметры:

mode - режим шифра

Исключения:

NoSuchAlgorithmException - если запрашиваемый режим шифра не существует

engineSetPadding

protected abstract void engineSetPadding(String padding)
                                  throws NoSuchPaddingException

Устанавливает механизм заполнения этого шифра.

Параметры:

padding - механизм заполнения

Исключения:

NoSuchPaddingException - если запрашиваемый механизм заполнения не существует

engineGetBlockSize

protected abstract int engineGetBlockSize()

Возвращает размер блока (в байтах).

Возвращает:

размер блока (в байтах) или 0, если базовый алгоритм не является блочным шифром

engineGetOutputSize

protected abstract int engineGetOutputSize(int inputLen)

Параметры:

inputLen - длина входных данных (в байтах)

Возвращает:

требуемый размер выходного буфера (в байтах)

engineGetIV

protected abstract byte[] engineGetIV()

Возвращает:

вектор инициализации в новом буфере или null, если базовый алгоритм не использует IV или если IV еще не установлен.

engineGetParameters

protected abstract AlgorithmParameters engineGetParameters()

Возвращает:

параметры, используемые с этим шифром, или null, если этот шифр не использует никаких параметров.

engineInit

protected abstract void engineInit(int opmode,
                                   Key key,
                                   SecureRandom random)
                            throws InvalidKeyException

Параметры:

opmode - режим работы этого шифра (это один из следующих: ENCRYPT_MODE, DECRYPT_MODE, WRAP_MODE или UNWRAP_MODE)

key - ключ шифрования

random - источник случайности

Исключения:

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

UnsupportedOperationException - если opmode является WRAP_MODE или UNWRAP_MODE не реализован шифром.

engineInit

protected abstract void engineInit(int opmode,
                                   Key key,
                                   AlgorithmParameterSpec params,
                                   SecureRandom random)
                            throws InvalidKeyException,
                                   InvalidAlgorithmParameterException

Параметры:

opmode - режим работы этого шифра (это один из следующих: ENCRYPT_MODE, DECRYPT_MODE, WRAP_MODE или UNWRAP_MODE)

key - ключ шифрования

params - параметры алгоритма

random - источник случайности

Исключения:

InvalidKeyException - если данный ключ не подходит для инициализации этого шифра

InvalidAlgorithmParameterException - если заданные параметры алгоритма не подходят для этого шифра или если этот шифр требует параметров алгоритма, и params равен null.

UnsupportedOperationException - если opmode является WRAP_MODE или UNWRAP_MODE не реализован шифром.

engineInit

protected abstract void engineInit(int opmode,
                                   Key key,
                                   AlgorithmParameters params,
                                   SecureRandom random)
                            throws InvalidKeyException,
                                   InvalidAlgorithmParameterException

Параметры:

opmode - режим работы этого шифра (это один из следующих: ENCRYPT_MODE, DECRYPT_MODE, WRAP_MODE или UNWRAP_MODE)

key - ключ шифрования

params - параметры алгоритма

random - источник случайности

Исключения:

InvalidKeyException - если данный ключ не подходит для инициализации этого шифра

InvalidAlgorithmParameterException - если заданные параметры алгоритма не подходят для этого шифра или если этот шифр требует параметров алгоритма, и params равен null.

UnsupportedOperationException - если opmode является WRAP_MODE или UNWRAP_MODE не реализован шифром.

engineUpdate

protected abstract byte[] engineUpdate(byte[] input,
                                       int inputOffset,
                                       int inputLen)

Параметры:

input - входной буфер

inputOffset - смещение в input, где начинается вход

inputLen - длина входных данных

Возвращает:

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

engineUpdate

protected abstract int engineUpdate(byte[] input,
                                    int inputOffset,
                                    int inputLen,
                                    byte[] output,
                                    int outputOffset)
                             throws ShortBufferException

Параметры:

input - буфер ввода

inputOffset - смещение в input, где начинается ввод

inputLen - длина ввода

output - буфер для результата

outputOffset - смещение в output, где хранится результат

Возвращает:

количество байтов, записанных в output

Выбрасывает:

ShortBufferException - если предоставленный буфер вывода слишком мал для хранения результата

engineUpdate

protected int engineUpdate(ByteBuffer input,
                           ByteBuffer output)
                    throws ShortBufferException

Параметры:

input - входной буфер ByteBuffer

output - выходной буфер ByteByffer

Возвращает:

количество байтов, записанных в output

Выбрасывает:

ShortBufferException - если в буфере вывода недостаточно места

NullPointerException - если любой из параметров null

С:

1.5

engineDoFinal

protected abstract byte[] engineDoFinal(byte[] input,
                                        int inputOffset,
                                        int inputLen)
                                 throws IllegalBlockSizeException,
                                        BadPaddingException

Параметры:

input - буфер ввода

inputOffset - смещение в input где начинается ввод

inputLen - длина ввода

Возвращает:

новый буфер с результатом

Выбрасывает:

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

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

AEADBadTagException - если этот шифр дешифрует в режиме AEAD (таком как GCM/CCM), и полученный тег аутентификации не совпадает с вычисленным значением

engineDoFinal

protected abstract int engineDoFinal(byte[] input,
                                     int inputOffset,
                                     int inputLen,
                                     byte[] output,
                                     int outputOffset)
                              throws ShortBufferException,
                                     IllegalBlockSizeException,
                                     BadPaddingException

Параметры:

input - буфер ввода

inputOffset - смещение в input где начинается ввод

inputLen - длина ввода

output - буфер для результата

outputOffset - смещение в output где хранится результат

Возвращает:

количество байтов, записанных в output

Выбрасывает:

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

ShortBufferException - если предоставленный буфер вывода слишком мал для хранения результата

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

AEADBadTagException - если этот шифр дешифрует в режиме AEAD (таком как GCM/CCM), и полученный тег аутентификации не совпадает с вычисленным значением

engineDoFinal

protected int engineDoFinal(ByteBuffer input,
                            ByteBuffer output)
                     throws ShortBufferException,
                            IllegalBlockSizeException,
                            BadPaddingException

Параметры:

input - входной буфер ByteBuffer

output - выходной буфер ByteByffer

Возвращает:

количество байтов, записанных в output

Выбрасывает:

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

ShortBufferException - если в буфере вывода недостаточно места

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

AEADBadTagException - если этот шифр дешифрует в режиме AEAD (таком как GCM/CCM), и полученный тег аутентификации не совпадает с вычисленным значением

NullPointerException - если любой из параметров null

С:

1.5

engineWrap

protected byte[] engineWrap(Key key)
                     throws IllegalBlockSizeException,
                            InvalidKeyException

Параметры:

key - ключ, который нужно обернуть.

Возвращает:

обернутый ключ.

Выбрасывает:

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

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

UnsupportedOperationException - если этот метод не поддерживается.

engineUnwrap

protected Key engineUnwrap(byte[] wrappedKey,
                           String wrappedKeyAlgorithm,
                           int wrappedKeyType)
                    throws InvalidKeyException,
                           NoSuchAlgorithmException

Параметры:

wrappedKey - ключ, который необходимо распаковать.

wrappedKeyAlgorithm - алгоритм, связанный с упакованным ключом.

wrappedKeyType - тип упакованного ключа. Это один из SECRET_KEY, PRIVATE_KEY, или PUBLIC_KEY.

Возвращает:

распакованный ключ.

Выбрасывает:

NoSuchAlgorithmException - если ни один из установленных поставщиков не может создать ключи типа wrappedKeyType для wrappedKeyAlgorithm.

InvalidKeyException - если wrappedKey не представляет собой упакованный ключ типа wrappedKeyType для wrappedKeyAlgorithm.

UnsupportedOperationException - если этот метод не поддерживается.

engineGetKeySize

protected int engineGetKeySize(Key key)
                        throws InvalidKeyException

Параметры:

key - объект ключа.

Возвращает:

размер ключа заданного объекта ключа.

Выбрасывает:

InvalidKeyException - если key недействителен.

engineUpdateAAD

protected void engineUpdateAAD(byte[] src,
                               int offset,
                               int len)

Параметры:

src - буфер, содержащий AAD

offset - смещение в src, где начинается ввод AAD

len - количество байтов AAD

Выбрасывает:

IllegalStateException - если этот шифр находится в неправильном состоянии (например, не был инициализирован), не принимает AAD или если работает в режимах GCM или CCM и один из методов update уже был вызван для активной операции шифрования/дешифрования.

UnsupportedOperationException - если этот метод не был переопределён реализацией

С:

1.7

engineUpdateAAD

protected void engineUpdateAAD(ByteBuffer src)

Параметры:

src - буфер, содержащий AAD

Выбрасывает:

IllegalStateException - если этот шифр находится в неправильном состоянии (например, не был инициализирован), не принимает AAD или если работает в режимах GCM или CCM и один из методов update уже был вызван для активной операции шифрования/дешифрования.

UnsupportedOperationException - если этот метод не был переопределён реализацией

С:

1.7