OpenJDK 27 · javax.crypto.Cipher · APIdia, the JavaDoc alternative

This class provides the functionality of a cryptographic cipher for encryption and decryption. It forms the core of the Java Cryptographic Extension (JCE) framework.

In order to create a Cipher object, the application calls the cipher's getInstance method, and passes the name of the requested transformation to it. Optionally, the name of a provider may be specified.

A transformation is a string that describes the operation (or set of operations) to be performed on the given input, to produce some output. A transformation always includes the name of a cryptographic algorithm (e.g., AES), and may be followed by a feedback mode and padding scheme.

A transformation is of the form:

"algorithm/mode/padding" or
"algorithm"

(in the latter case, provider-specific default values for the mode and padding scheme are used). For example, the following is a valid transformation:

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

Using modes such as CFB and OFB, block ciphers can encrypt data in units smaller than the cipher's actual block size. When requesting such a mode, you may optionally specify the number of bits to be processed at a time by appending this number to the mode name as shown in the "AES/CFB8/NoPadding" and "AES/OFB32/PKCS5Padding" transformations. If no such number is specified, a provider-specific default is used. (See the JDK Providers Documentation for the JDK Providers default values.) Thus, block ciphers can be turned into byte-oriented stream ciphers by using an 8 bit mode such as CFB8 or OFB8.

Modes such as Authenticated Encryption with Associated Data (AEAD) provide authenticity assurances for both confidential data and Additional Associated Data (AAD) that is not encrypted. (Please see RFC 5116 for more information on AEAD and AAD algorithms.) Both confidential and AAD data can be used when calculating the authentication tag (similar to a Mac). This tag is appended to the ciphertext during encryption, and is verified on decryption.

AEAD modes perform all AAD authenticity calculations before starting the ciphertext authenticity calculations. To avoid implementations having to internally buffer ciphertext, all AAD data must be supplied to their implementations (via the updateAAD methods) before the ciphertext is processed (via the update and doFinal methods).

When a doFinal method completes the operation, the Cipher object will attempt to reset the state to the most recent call to init, allowing for additional operations. A successful reset depends on the mode (ENCRYPT_MODE or DECRYPT_MODE) and the algorithm. AEAD algorithms may not reset, in order to prevent forgery attacks due to Key and IV uniqueness requirements.

An IllegalStateException will be thrown when calling update or doFinal methods if a reset did not occur. A call to init will re-initialize the Cipher object with new parameters.

Every implementation of the Java platform is required to support the following standard Cipher object transformations with the keysizes in parentheses:

AES/CBC/NoPadding (128)
AES/CBC/PKCS5Padding (128)
AES/ECB/NoPadding (128)
AES/ECB/PKCS5Padding (128)
AES/GCM/NoPadding (128, 256)
ChaCha20-Poly1305
PBEWithHmacSHA256AndAES_128
PBEWithHmacSHA256AndAES_256
RSA/ECB/OAEPWithSHA-1AndMGF1Padding (1024, 2048)
RSA/ECB/OAEPWithSHA-256AndMGF1Padding (1024, 2048)

These transformations are described in the Cipher section of the Java Security Standard Algorithm Names Specification. Consult the release documentation for your implementation to see if any other transformations are supported.

Modifier and Type	Class and Description
private static class	Cipher.Transform Nested class to deal with modes and paddings.

Modifier and Type	Field and Description
private static final String	ATTR_MODE
private static final String	ATTR_PAD
private CryptoPermission	cryptoPerm
private static final Debug	debug
public static final int	DECRYPT_MODE Constant used to initialize cipher to decryption mode.
public static final int	ENCRYPT_MODE Constant used to initialize cipher to encryption mode.
private ExemptionMechanism	exmech
private Provider.Service	firstService
private CipherSpi	firstSpi
private static final int	I_CERT
private static final int	I_KEY
private static final int	I_PARAMS
private static final int	I_PARAMSPEC
private boolean	initialized
private final Object	lock
private int	opmode
private static final Debug	pdebug
public static final int	PRIVATE_KEY Constant used to indicate the to-be-unwrapped key is a "private key".
private Provider	provider
public static final int	PUBLIC_KEY Constant used to indicate the to-be-unwrapped key is a "public key".
private static final int	S_MAYBE
private static final int	S_NO
private static final int	S_YES
public static final int	SECRET_KEY Constant used to indicate the to-be-unwrapped key is a "secret key".
private Iterator<Provider.Service>	serviceIterator
private static final boolean	skipDebug
private CipherSpi	spi
private final String	transformation
private List<Cipher.Transform>	transforms
public static final int	UNWRAP_MODE Constant used to initialize cipher to key-unwrapping mode.
private static int	warnCount
public static final int	WRAP_MODE Constant used to initialize cipher to key-wrapping mode.

Access	Constructor and Description
protected	Cipher(CipherSpi the delegate cipherSpi, Provider the provider provider, String the transformation transformation) Creates a `Cipher` object.
pack-priv	Cipher(CipherSpi the delegate cipherSpi, String the transformation transformation) Creates a `Cipher` object.
private	Cipher(CipherSpi firstSpi, Provider.Service firstService, Iterator<Provider.Service> serviceIterator, String transformation, List<Cipher.Transform> transforms)

Method Summary

Modifier and Type	Method and Description
private void	checkCipherState() Ensures that `Cipher` object is in a valid state for update() and doFinal() calls - should be initialized and in `ENCRYPT_MODE` or `DECRYPT_MODE`.
private void	checkCryptoPerm(CipherSpi checkSpi, Key key)
private void	checkCryptoPerm(CipherSpi checkSpi, Key key, AlgorithmParameterSpec params)
private void	checkCryptoPerm(CipherSpi checkSpi, Key key, AlgorithmParameters params)
private static void	checkOpmode(int opmode)
pack-priv void	chooseFirstProvider() Choose the Spi from the first provider available.
private void	chooseProvider(int initType, int opmode, Key key, AlgorithmParameterSpec paramSpec, AlgorithmParameters params, SecureRandom random)
public final byte[]	Returns: the new buffer with the result doFinal() Finishes a multiple-part encryption or decryption operation, depending on how this `Cipher` object was initialized.
public final int	Returns: the number of bytes stored in `output` doFinal(byte[] the buffer for the result output, int the offset in `output` where the result is stored outputOffset) Finishes a multiple-part encryption or decryption operation, depending on how this `Cipher` object was initialized.
public final byte[]	Returns: the new buffer with the result doFinal(byte[] the input buffer input) Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation.
public final byte[]	Returns: the new buffer with the result doFinal(byte[] the input buffer input, int the offset in `input` where the input starts inputOffset, int the input length inputLen) Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation.
public final int	Returns: the number of bytes stored in `output` doFinal(byte[] the input buffer input, int the offset in `input` where the input starts inputOffset, int the input length inputLen, byte[] the buffer for the result output) Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation.
public final int	Returns: the number of bytes stored in `output` doFinal(byte[] the input buffer input, int the offset in `input` where the input starts inputOffset, int the input length inputLen, byte[] the buffer for the result output, int the offset in `output` where the result is stored outputOffset) Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation.
public final int	Returns: the number of bytes stored in `output` doFinal(ByteBuffer the input ByteBuffer input, ByteBuffer the output ByteBuffer output) Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation.
public final String	Returns: the algorithm name of this `Cipher` object getAlgorithm() Returns the algorithm name of this `Cipher` object.
private AlgorithmParameterSpec	getAlgorithmParameterSpec(AlgorithmParameters params)
public final int	Returns: the block size (in bytes), or 0 if this cipher is not a block cipher getBlockSize() Returns the block size (in bytes).
private static CryptoPermission	getConfiguredPermission(String transformation)
public final ExemptionMechanism	Returns: the exemption mechanism object used with this `Cipher` object, or `null` if this `Cipher` object does not use any exemption mechanism. getExemptionMechanism() Returns the exemption mechanism object used with this `Cipher` object.
public static final Cipher	Returns: a `Cipher` object that implements the requested transformation getInstance(String the name of the transformation, e.g., AES/CBC/PKCS5Padding. See the Cipher section in the Java Security Standard Algorithm Names Specification for information about standard transformation names. transformation) Returns a `Cipher` object that implements the specified transformation.
public static final Cipher	Returns: a `Cipher` object that implements the requested transformation getInstance(String the name of the transformation, e.g., AES/CBC/PKCS5Padding. See the Cipher section in the Java Security Standard Algorithm Names Specification for information about standard transformation names. transformation, String the name of the provider provider) Returns a `Cipher` object that implements the specified transformation.
public static final Cipher	Returns: a `Cipher` object that implements the requested transformation getInstance(String the name of the transformation, e.g., AES/CBC/PKCS5Padding. See the Cipher section in the Java Security Standard Algorithm Names Specification for information about standard transformation names. transformation, Provider the provider provider) Returns a `Cipher` object that implements the specified transformation.
public final byte[]	Returns: the initialization vector in a new buffer, or `null` if this cipher does not use an IV, or if the IV has not yet been set. getIV() Returns the initialization vector (IV) in a new buffer.
public static final int	Returns: the maximum key length in bits or `Integer.MAX_VALUE` getMaxAllowedKeyLength(String the cipher transformation transformation) Returns the maximum key length for the specified transformation according to the installed JCE jurisdiction policy files.
public static final AlgorithmParameterSpec	Returns: an `AlgorithmParameterSpec` object which holds the maximum value or `null` getMaxAllowedParameterSpec(String the cipher transformation transformation) Returns an `AlgorithmParameterSpec` object which contains the maximum `Cipher` parameter value according to the jurisdiction policy file.
public final int	Returns: the required output buffer size (in bytes) getOutputSize(int the input length (in bytes) inputLen) Returns the length in bytes that an output buffer would need to be in order to hold the result of the next `update` or `doFinal` operation, given the input length `inputLen` (in bytes).
public final AlgorithmParameters	Returns: the parameters used with this cipher, or `null` getParameters() Returns the parameters used with this `Cipher` object.
public final Provider	Returns: the provider of this `Cipher` object getProvider() Returns the provider of this `Cipher` object.
private String	getProviderName()
private static Cipher.Transform	getTransform(Provider.Service s, List<Cipher.Transform> transforms)
private static List<Cipher.Transform>	getTransforms(String transformation)
private void	implInit(CipherSpi thisSpi, int type, int opmode, Key key, AlgorithmParameterSpec paramSpec, AlgorithmParameters params, SecureRandom random)
pack-priv static int	indexOfRealSlash(String s, int fromIndex)
public final void	init(int the operation mode of this `Cipher` object (this is one of the following: `ENCRYPT_MODE`, `DECRYPT_MODE`, `WRAP_MODE` or `UNWRAP_MODE`) opmode, Key the key key) Initializes this `Cipher` object with a key.
public final void	init(int the operation mode of this `Cipher` object (this is one of the following: `ENCRYPT_MODE`, `DECRYPT_MODE`, `WRAP_MODE` or `UNWRAP_MODE`) opmode, Key the encryption key key, SecureRandom the source of randomness random) Initializes this `Cipher` object with a key and a source of randomness.
public final void	init(int the operation mode of this `Cipher` object (this is one of the following: `ENCRYPT_MODE`, `DECRYPT_MODE`, `WRAP_MODE` or `UNWRAP_MODE`) opmode, Key the encryption key key, AlgorithmParameterSpec the algorithm parameters params) Initializes this `Cipher` object with a key and a set of algorithm parameters.
public final void	init(int the operation mode of this `Cipher` object (this is one of the following: `ENCRYPT_MODE`, `DECRYPT_MODE`, `WRAP_MODE` or `UNWRAP_MODE`) opmode, Key the encryption key key, AlgorithmParameterSpec the algorithm parameters params, SecureRandom the source of randomness random) Initializes this `Cipher` object with a key, a set of algorithm parameters, and a source of randomness.
public final void	init(int the operation mode of this `Cipher` object this is one of the following: `ENCRYPT_MODE`, `DECRYPT_MODE`, `WRAP_MODE` or `UNWRAP_MODE`) opmode, Key the encryption key key, AlgorithmParameters the algorithm parameters params) Initializes this `Cipher` object with a key and a set of algorithm parameters.
public final void	init(int the operation mode of this `Cipher` object (this is one of the following: `ENCRYPT_MODE`, `DECRYPT_MODE`, `WRAP_MODE` or `UNWRAP_MODE`) opmode, Key the encryption key key, AlgorithmParameters the algorithm parameters params, SecureRandom the source of randomness random) Initializes this `Cipher` object with a key, a set of algorithm parameters, and a source of randomness.
public final void	init(int the operation mode of this `Cipher` object (this is one of the following: `ENCRYPT_MODE`, `DECRYPT_MODE`, `WRAP_MODE` or `UNWRAP_MODE`) opmode, Certificate the certificate certificate) Initializes this `Cipher` object with the public key from the given certificate.
public final void	init(int the operation mode of this `Cipher` object (this is one of the following: `ENCRYPT_MODE`, `DECRYPT_MODE`, `WRAP_MODE` or `UNWRAP_MODE`) opmode, Certificate the certificate certificate, SecureRandom the source of randomness random) Initializes this `Cipher` object with the public key from the given certificate and a source of randomness.
private void	initCryptoPermission()
private boolean	passCryptoPermCheck(CipherSpi checkSpi, Key key, AlgorithmParameterSpec params)
pack-priv static String	reqNonEmpty(String in, String msg)
private static String[]	tokenizeTransformation(String transformation)
public String	Returns: a String describing this `Cipher` object toString() Overrides java.lang.Object.toString. Returns a `String` representation of this `Cipher` object.
public final Key	Returns: the unwrapped key unwrap(byte[] the key to be unwrapped wrappedKey, String the algorithm associated with the wrapped key wrappedKeyAlgorithm, int the type of the wrapped key. This must be one of `SECRET_KEY`, `PRIVATE_KEY`, or `PUBLIC_KEY` wrappedKeyType) Unwrap a previously wrapped key.
public final byte[]	Returns: the new buffer with the result, or `null` if this cipher is a block cipher and the input data is too short to result in a new block update(byte[] the input buffer input) Continues a multiple-part encryption or decryption operation (depending on how this `Cipher` object was initialized), processing another data part.
public final byte[]	Returns: the new buffer with the result, or `null` if this cipher is a block cipher and the input data is too short to result in a new block. update(byte[] the input buffer input, int the offset in `input` where the input starts inputOffset, int the input length inputLen) Continues a multiple-part encryption or decryption operation (depending on how this `Cipher` object was initialized), processing another data part.
public final int	Returns: the number of bytes stored in `output` update(byte[] the input buffer input, int the offset in `input` where the input starts inputOffset, int the input length inputLen, byte[] the buffer for the result output) Continues a multiple-part encryption or decryption operation (depending on how this `Cipher` object was initialized), processing another data part.
public final int	Returns: the number of bytes stored in `output` update(byte[] the input buffer input, int the offset in `input` where the input starts inputOffset, int the input length inputLen, byte[] the buffer for the result output, int the offset in `output` where the result is stored outputOffset) Continues a multiple-part encryption or decryption operation (depending on how this `Cipher` object was initialized), processing another data part.
public final int	Returns: the number of bytes stored in `output` update(ByteBuffer the input ByteBuffer input, ByteBuffer the output ByteByffer output) Continues a multiple-part encryption or decryption operation (depending on how this `Cipher` object was initialized), processing another data part.
public final void	updateAAD(byte[] the buffer containing the Additional Authentication Data src) Continues a multi-part update of the Additional Authentication Data (AAD).
public final void	updateAAD(byte[] the buffer containing the AAD src, int the offset in `src` where the AAD input starts offset, int the number of AAD bytes len) Continues a multi-part update of the Additional Authentication Data (AAD), using a subset of the provided buffer.
public final void	updateAAD(ByteBuffer the buffer containing the AAD src) Continues a multi-part update of the Additional Authentication Data (AAD).
public final byte[]	Returns: the wrapped key wrap(Key the key to be wrapped key) Wrap a key.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

public Class Cipher

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary