Cipher

public class Cipher extends Object
Known Direct Subclasses

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., DES), 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("DES/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 "DES/CFB8/NoPadding" and "DES/OFB32/PKCS5Padding" transformations. If no such number is specified, a provider-specific default is used. (For example, the SunJCE provider uses a default of 64 bits for DES.) 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 AEAD algorithms such as GCM/CCM.) 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 such as GCM/CCM 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 GCM/CCM implementations (via the updateAAD methods) before the ciphertext is processed (via the update and doFinal methods).

     GCMParameterSpec s = new GCMParameterSpec(...);
     cipher.init(..., s);

     // If the GCMParameterSpec is needed again
     cipher.getParameters().getParameterSpec(GCMParameterSpec.class));

     cipher.updateAAD(...);  // AAD
     cipher.update(...);     // Multi-part update
     cipher.doFinal(...);    // conclusion of operation
 

Android provides the following Cipher transformations:

Name Supported (API Levels)
AES/CBC/ISO10126Padding 1+
AES/CBC/NoPadding 1+
AES/CBC/PKCS5Padding 1+
AES/CFB/ISO10126Padding 1+
AES/CFB/NoPadding 1+
AES/CFB/PKCS5Padding 1+
AES/CTR/ISO10126Padding 1+
AES/CTR/NoPadding 1+
AES/CTR/PKCS5Padding 1+
AES/CTS/ISO10126Padding 1+
AES/CTS/NoPadding 1+
AES/CTS/PKCS5Padding 1+
AES/ECB/ISO10126Padding 1+
AES/ECB/NoPadding 1+
AES/ECB/PKCS5Padding 1+
AES/OFB/ISO10126Padding 1+
AES/OFB/NoPadding 1+
AES/OFB/PKCS5Padding 1+
ARCFOUR/ECB/NoPadding 10+
BLOWFISH/CBC/ISO10126Padding 10+
BLOWFISH/CBC/NoPadding 10+
BLOWFISH/CBC/PKCS5Padding 10+
BLOWFISH/CFB/ISO10126Padding 10+
BLOWFISH/CFB/NoPadding 10+
BLOWFISH/CFB/PKCS5Padding 10+
BLOWFISH/CTR/ISO10126Padding 10+
BLOWFISH/CTR/NoPadding 10+
BLOWFISH/CTR/PKCS5Padding 10+
BLOWFISH/CTS/ISO10126Padding 10+
BLOWFISH/CTS/NoPadding 10+
BLOWFISH/CTS/PKCS5Padding 10+
BLOWFISH/ECB/ISO10126Padding 10+
BLOWFISH/ECB/NoPadding 10+
BLOWFISH/ECB/PKCS5Padding 10+
BLOWFISH/OFB/ISO10126Padding 10+
BLOWFISH/OFB/NoPadding 10+
BLOWFISH/OFB/PKCS5Padding 10+
DES/CBC/ISO10126Padding 1+
DES/CBC/NoPadding 1+
DES/CBC/PKCS5Padding 1+
DES/CFB/ISO10126Padding 1+
DES/CFB/NoPadding 1+
DES/CFB/PKCS5Padding 1+
DES/CTR/ISO10126Padding 1+
DES/CTR/NoPadding 1+
DES/CTR/PKCS5Padding 1+
DES/CTS/ISO10126Padding 1+
DES/CTS/NoPadding 1+
DES/CTS/PKCS5Padding 1+
DES/ECB/ISO10126Padding 1+
DES/ECB/NoPadding 1+
DES/ECB/PKCS5Padding 1+
DES/OFB/ISO10126Padding 1+
DES/OFB/NoPadding 1+
DES/OFB/PKCS5Padding 1+
DESede/CBC/ISO10126Padding 1+
DESede/CBC/NoPadding 1+
DESede/CBC/PKCS5Padding 1+
DESede/CFB/ISO10126Padding 1+
DESede/CFB/NoPadding 1+
DESede/CFB/PKCS5Padding 1+
DESede/CTR/ISO10126Padding 1+
DESede/CTR/NoPadding 1+
DESede/CTR/PKCS5Padding 1+
DESede/CTS/ISO10126Padding 1+
DESede/CTS/NoPadding 1+
DESede/CTS/PKCS5Padding 1+
DESede/ECB/ISO10126Padding 1+
DESede/ECB/NoPadding 1+
DESede/ECB/PKCS5Padding 1+
DESede/OFB/ISO10126Padding 1+
DESede/OFB/NoPadding 1+
DESede/OFB/PKCS5Padding 1+
PBEwithMD5andDES/CBC/ISO10126Padding 1+
PBEwithMD5andDES/CBC/NoPadding 1+
PBEwithMD5andDES/CBC/PKCS5Padding 1+
PBEwithMD5andDES/CFB/ISO10126Padding 1+
PBEwithMD5andDES/CFB/NoPadding 1+
PBEwithMD5andDES/CFB/PKCS5Padding 1+
PBEwithMD5andDES/CTR/ISO10126Padding 1+
PBEwithMD5andDES/CTR/NoPadding 1+
PBEwithMD5andDES/CTR/PKCS5Padding 1+
PBEwithMD5andDES/CTS/ISO10126Padding 1+
PBEwithMD5andDES/CTS/NoPadding 1+
PBEwithMD5andDES/CTS/PKCS5Padding 1+
PBEwithMD5andDES/ECB/ISO10126Padding 1+
PBEwithMD5andDES/ECB/NoPadding 1+
PBEwithMD5andDES/ECB/PKCS5Padding 1+
PBEwithMD5andDES/OFB/ISO10126Padding 1+
PBEwithMD5andDES/OFB/NoPadding 1+
PBEwithMD5andDES/OFB/PKCS5Padding 1+
PBEwithSHA1andDESede/CBC/ISO10126Padding 1+
PBEwithSHA1andDESede/CBC/NoPadding 1+
PBEwithSHA1andDESede/CBC/PKCS5Padding 1+
PBEwithSHA1andDESede/CFB/ISO10126Padding 1+
PBEwithSHA1andDESede/CFB/NoPadding 1+
PBEwithSHA1andDESede/CFB/PKCS5Padding 1+
PBEwithSHA1andDESede/CTR/ISO10126Padding 1+
PBEwithSHA1andDESede/CTR/NoPadding 1+
PBEwithSHA1andDESede/CTR/PKCS5Padding 1+
PBEwithSHA1andDESede/CTS/ISO10126Padding 1+
PBEwithSHA1andDESede/CTS/NoPadding 1+
PBEwithSHA1andDESede/CTS/PKCS5Padding 1+
PBEwithSHA1andDESede/ECB/ISO10126Padding 1+
PBEwithSHA1andDESede/ECB/NoPadding 1+
PBEwithSHA1andDESede/ECB/PKCS5Padding 1+
PBEwithSHA1andDESede/OFB/ISO10126Padding 1+
PBEwithSHA1andDESede/OFB/NoPadding 1+
PBEwithSHA1andDESede/OFB/PKCS5Padding 1+
RC4/ECB/NoPadding 10+
RSA/ECB/NoPadding 1+
RSA/ECB/OAEPPadding 1+
RSA/ECB/OAEPwithSHA-1andMGF1Padding 10+
RSA/ECB/OAEPwithSHA-256andMGF1Padding 10+
RSA/ECB/PKCS1Padding 1+
RSA/NONE/NoPadding 1+
RSA/NONE/OAEPPadding 1+
RSA/NONE/OAEPwithSHA-1andMGF1Padding 10+
RSA/NONE/OAEPwithSHA-256andMGF1Padding 10+
RSA/NONE/PKCS1Padding 1+
These transformations are described in the Cipher section of the Java Cryptography Architecture Standard Algorithm Name Documentation.

Constant Summary

int DECRYPT_MODE Constant used to initialize cipher to decryption mode.
int ENCRYPT_MODE Constant used to initialize cipher to encryption mode.
int PRIVATE_KEY Constant used to indicate the to-be-unwrapped key is a "private key".
int PUBLIC_KEY Constant used to indicate the to-be-unwrapped key is a "public key".
int SECRET_KEY Constant used to indicate the to-be-unwrapped key is a "secret key".
int UNWRAP_MODE Constant used to initialize cipher to key-unwrapping mode.
int WRAP_MODE Constant used to initialize cipher to key-wrapping mode.

Protected Constructor Summary

Cipher(CipherSpi cipherSpi, Provider provider, String transformation)
Creates a Cipher object.

Public Method Summary

final int
doFinal(byte[] input, int inputOffset, int inputLen, byte[] output)
Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation.
final int
doFinal(byte[] output, int outputOffset)
Finishes a multiple-part encryption or decryption operation, depending on how this cipher was initialized.
final byte[]
doFinal()
Finishes a multiple-part encryption or decryption operation, depending on how this cipher was initialized.
final byte[]
doFinal(byte[] input)
Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation.
final int
doFinal(byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset)
Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation.
final int
doFinal(ByteBuffer input, ByteBuffer output)
Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation.
final byte[]
doFinal(byte[] input, int inputOffset, int inputLen)
Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation.
final String
getAlgorithm()
Returns the algorithm name of this Cipher object.
final int
getBlockSize()
Returns the block size (in bytes).
final ExemptionMechanism
getExemptionMechanism()
Returns the exemption mechanism object used with this cipher.
final byte[]
getIV()
Returns the initialization vector (IV) in a new buffer.
final static Cipher
getInstance(String transformation)
Returns a Cipher object that implements the specified transformation.
final static Cipher