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

This class enables a programmer to create an object and protect its confidentiality with a cryptographic algorithm.

Given any Serializable object, one can create a SealedObject that encapsulates the original object, in serialized format (i.e., a "deep copy"), and seals (encrypts) its serialized contents, using a cryptographic algorithm such as AES, to protect its confidentiality. The encrypted content can later be decrypted (with the corresponding algorithm using the correct decryption key) and de-serialized, yielding the original object.

Note that the Cipher object must be fully initialized with the correct algorithm, key, padding scheme, etc., before being applied to a SealedObject.

The original object that was sealed can be recovered in two different ways:

by using the getObject method that takes a Cipher object.
This method requires a fully initialized Cipher object, initialized with the exact same algorithm, key, padding scheme, etc., that were used to seal the object.
This approach has the advantage that the party who unseals the sealed object does not require knowledge of the decryption key. For example, after one party has initialized the cipher object with the required decryption key, it could hand over the cipher object to another party who then unseals the sealed object.
by using one of the getObject methods that take a Key object.
In this approach, the getObject method creates a cipher object for the appropriate decryption algorithm and initializes it with the given decryption key and the algorithm parameters (if any) that were stored in the sealed object.
This approach has the advantage that the party who unseals the object does not need to keep track of the parameters (e.g., an IV) that were used to seal the object.

Field Summary

Modifier and Type	Field and Description
protected byte[]	encodedParams The cryptographic parameters used by the sealing `Cipher` object, encoded in the default format.
private byte[]	encryptedContent The serialized object contents in encrypted format.
private String	paramsAlg The algorithm of the parameters used.
private final String	sealAlg The algorithm that was used to seal this object.
pack-priv static final long	serialVersionUID

Constructor Summary

Access	Constructor and Description
public	SealedObject(Serializable the object to be sealed; can be `null`. object, Cipher the cipher used to seal the object. c) Constructs a `SealedObject` from any `Serializable` object.
protected	SealedObject(SealedObject a `SealedObject` object so) Constructs a `SealedObject` object from the passed-in `SealedObject`.

Method Summary

Modifier and Type	Method and Description
public final String	Returns: the algorithm that was used to seal this object. getAlgorithm() Returns the algorithm that was used to seal this object.
private ObjectInputStream	getExtObjectInputStream(Cipher c)
public final Object	Returns: the original object. getObject(Key the key used to unseal the object. key) Retrieves the original (encapsulated) object.
public final Object	Returns: the original object. getObject(Cipher the cipher used to unseal the object c) Retrieves the original (encapsulated) object.
public final Object	Returns: the original object. getObject(Key the key used to unseal the object. key, String the name of the provider of the algorithm to unseal the object. provider) Retrieves the original (encapsulated) object.
private void	readObject(ObjectInputStream the object input stream. s) Restores the state of the `SealedObject` from a stream.
private Object	unseal(Key key, String provider)

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

Field Detail

encodedParams back to summary

encodedParams	back to summary
protected byte[] encodedParams The cryptographic parameters used by the sealing `Cipher` object, encoded in the default format. That is, `Cipher.getParameters().getEncoded()`.

protected byte[] encodedParams

The cryptographic parameters used by the sealing Cipher object, encoded in the default format.

That is, Cipher.getParameters().getEncoded().

encryptedContent	back to summary
private byte[] encryptedContent The serialized object contents in encrypted format.

paramsAlg	back to summary
private String paramsAlg The algorithm of the parameters used.

sealAlg	back to summary
private final String sealAlg The algorithm that was used to seal this object.

serialVersionUID	back to summary
pack-priv static final long serialVersionUID Annotations @Serial

Constructor Detail

SealedObject back to summary

SealedObject	back to summary
public SealedObject(Serializable object, Cipher c) throws IOException, IllegalBlockSizeException Constructs a `SealedObject` from any `Serializable` object. The given object is serialized, and its serialized contents are encrypted using the given `Cipher` object, which must be fully initialized. Any algorithm parameters that may be used in the encryption operation are stored inside the new `SealedObject`. Parameters object:Serializable the object to be sealed; can be `null`. c:Cipher the cipher used to seal the object. Exceptions IOException: if an error occurs during serialization IllegalBlockSizeException: if the given cipher is a block cipher, no padding has been requested, and the total input length (i.e., the length of the serialized object contents) is not a multiple of the cipher's block size NullPointerException: if the given cipher is `null`.

public SealedObject(Serializable object, Cipher c) throws IOException, IllegalBlockSizeException

Constructs a SealedObject from any Serializable object.

The given object is serialized, and its serialized contents are encrypted using the given Cipher object, which must be fully initialized.

Any algorithm parameters that may be used in the encryption operation are stored inside the new SealedObject.

Parameters

object:Serializable: the object to be sealed; can be null.
c:Cipher: the cipher used to seal the object.

Exceptions

IOException:: if an error occurs during serialization
IllegalBlockSizeException:: if the given cipher is a block cipher, no padding has been requested, and the total input length (i.e., the length of the serialized object contents) is not a multiple of the cipher's block size
NullPointerException:: if the given cipher is null.

SealedObject back to summary

SealedObject	back to summary
protected SealedObject(SealedObject so) Constructs a `SealedObject` object from the passed-in `SealedObject`. Parameters so:SealedObject a `SealedObject` object Exceptions NullPointerException: if the given sealed object is `null`.

protected SealedObject(SealedObject so)

Constructs a SealedObject object from the passed-in SealedObject.

Parameters

so:SealedObject: a SealedObject object

Exceptions

NullPointerException:: if the given sealed object is null.

Method Detail

getAlgorithm	back to summary
public final String getAlgorithm() Returns the algorithm that was used to seal this object. Returns:String the algorithm that was used to seal this object.

getAlgorithm

back to summary

public final String getAlgorithm()

Returns the algorithm that was used to seal this object.

Returns:String: the algorithm that was used to seal this object.

getExtObjectInputStream	back to summary
private ObjectInputStream getExtObjectInputStream(Cipher c) throws BadPaddingException, IllegalBlockSizeException, IOException

getObject back to summary

getObject	back to summary
public final Object getObject(Key key) throws IOException, ClassNotFoundException, NoSuchAlgorithmException, InvalidKeyException Retrieves the original (encapsulated) object. This method creates a cipher for the algorithm that had been used in the sealing operation. If the default provider package provides an implementation of that algorithm, a `Cipher` object containing that implementation is used. If the algorithm is not available in the default package, other packages are searched. The `Cipher` object is initialized for decryption, using the given `key` and the parameters (if any) that had been used in the sealing operation. The encapsulated object is unsealed and de-serialized, before it is returned. Parameters key:Key the key used to unseal the object. Returns:Object the original object. Exceptions IOException: if an error occurs during de-serialization. ClassNotFoundException: if an error occurs during de-serialization. NoSuchAlgorithmException: if the algorithm to unseal the object is not available. InvalidKeyException: if the given key cannot be used to unseal the object (e.g., it has the wrong algorithm). NullPointerException: if `key` is null.

public final Object getObject(Key key) throws IOException, ClassNotFoundException, NoSuchAlgorithmException, InvalidKeyException

Retrieves the original (encapsulated) object.

This method creates a cipher for the algorithm that had been used in the sealing operation. If the default provider package provides an implementation of that algorithm, a Cipher object containing that implementation is used. If the algorithm is not available in the default package, other packages are searched. The Cipher object is initialized for decryption, using the given key and the parameters (if any) that had been used in the sealing operation.

The encapsulated object is unsealed and de-serialized, before it is returned.

Parameters

key:Key: the key used to unseal the object.

Returns:Object

the original object.

Exceptions

IOException:: if an error occurs during de-serialization.
ClassNotFoundException:: if an error occurs during de-serialization.
NoSuchAlgorithmException:: if the algorithm to unseal the object is not available.
InvalidKeyException:: if the given key cannot be used to unseal the object (e.g., it has the wrong algorithm).
NullPointerException:: if key is null.

getObject back to summary

getObject	back to summary
public final Object getObject(Cipher c) throws IOException, ClassNotFoundException, IllegalBlockSizeException, BadPaddingException Retrieves the original (encapsulated) object. The encapsulated object is unsealed (using the given `Cipher` object, assuming that the `Cipher` object is already properly initialized) and de-serialized, before it is returned. Parameters c:Cipher the cipher used to unseal the object Returns:Object the original object. Exceptions IOException: if an error occurs during de-serialization ClassNotFoundException: if an error occurs during de-serialization IllegalBlockSizeException: if the given cipher is a block cipher, no padding has been requested, and the total input length is not a multiple of the cipher's block size BadPaddingException: if the given cipher has been initialized for decryption, and padding has been specified, but the input data does not have proper expected padding bytes NullPointerException: if the given cipher is `null`.

public final Object getObject(Cipher c) throws IOException, ClassNotFoundException, IllegalBlockSizeException, BadPaddingException

Retrieves the original (encapsulated) object.

The encapsulated object is unsealed (using the given Cipher object, assuming that the Cipher object is already properly initialized) and de-serialized, before it is returned.

Parameters

c:Cipher: the cipher used to unseal the object

Returns:Object

the original object.

Exceptions

IOException:: if an error occurs during de-serialization
ClassNotFoundException:: if an error occurs during de-serialization
IllegalBlockSizeException:: if the given cipher is a block cipher, no padding has been requested, and the total input length is not a multiple of the cipher's block size
BadPaddingException:: if the given cipher has been initialized for decryption, and padding has been specified, but the input data does not have proper expected padding bytes
NullPointerException:: if the given cipher is null.

getObject back to summary

getObject	back to summary
public final Object getObject(Key key, String provider) throws IOException, ClassNotFoundException, NoSuchAlgorithmException, NoSuchProviderException, InvalidKeyException Retrieves the original (encapsulated) object. This method creates a cipher for the algorithm that had been used in the sealing operation, using an implementation of that algorithm from the given `provider`. The `Cipher` object is initialized for decryption, using the given `key` and the parameters (if any) that had been used in the sealing operation. The encapsulated object is unsealed and de-serialized, before it is returned. Parameters key:Key the key used to unseal the object. provider:String the name of the provider of the algorithm to unseal the object. Returns:Object the original object. Exceptions IOException: if an error occurs during de-serialization. ClassNotFoundException: if an error occurs during de-serialization. NoSuchAlgorithmException: if the algorithm to unseal the object is not available. NoSuchProviderException: if the given provider is not configured. InvalidKeyException: if the given key cannot be used to unseal the object (e.g., it has the wrong algorithm). IllegalArgumentException: if the given provider is `null` or empty. NullPointerException: if `key` is null.

public final Object getObject(Key key, String provider) throws IOException, ClassNotFoundException, NoSuchAlgorithmException, NoSuchProviderException, InvalidKeyException

Retrieves the original (encapsulated) object.

This method creates a cipher for the algorithm that had been used in the sealing operation, using an implementation of that algorithm from the given provider. The Cipher object is initialized for decryption, using the given key and the parameters (if any) that had been used in the sealing operation.

The encapsulated object is unsealed and de-serialized, before it is returned.

Parameters

key:Key: the key used to unseal the object.
provider:String: the name of the provider of the algorithm to unseal the object.

Returns:Object

the original object.

Exceptions

IOException:: if an error occurs during de-serialization.
ClassNotFoundException:: if an error occurs during de-serialization.
NoSuchAlgorithmException:: if the algorithm to unseal the object is not available.
NoSuchProviderException:: if the given provider is not configured.
InvalidKeyException:: if the given key cannot be used to unseal the object (e.g., it has the wrong algorithm).
IllegalArgumentException:: if the given provider is null or empty.
NullPointerException:: if key is null.

readObject back to summary

readObject	back to summary
private void readObject(ObjectInputStream s) throws IOException, ClassNotFoundException Restores the state of the `SealedObject` from a stream. Parameters s:ObjectInputStream the object input stream. Annotations @Serial Exceptions IOException: if an I/O error occurs ClassNotFoundException: if a serialized class cannot be loaded NullPointerException: if s is `null`

private void readObject(ObjectInputStream s) throws IOException, ClassNotFoundException

Restores the state of the SealedObject from a stream.

Parameters

s:ObjectInputStream: the object input stream.

Annotations

@Serial

Exceptions

IOException:: if an I/O error occurs
ClassNotFoundException:: if a serialized class cannot be loaded
NullPointerException:: if s is null

unseal	back to summary
private Object unseal(Key key, String provider) throws IOException, ClassNotFoundException, NoSuchAlgorithmException, NoSuchProviderException, InvalidKeyException, IllegalBlockSizeException, BadPaddingException

public Class SealedObject

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail