EncryptedPrivateKeyInfo (Java SE 26 & JDK 26)
Description: declaration: module: java.base, package: javax.crypto, class: EncryptedPrivateKeyInfo
Keywords: javax.crypto.EncryptedPrivateKeyInfo class

# Class EncryptedPrivateKeyInfo

java.lang.Object
javax.crypto.EncryptedPrivateKeyInfo

All Implemented Interfaces:
  `DEREncodablePREVIEW`

public non-sealed class EncryptedPrivateKeyInfo extends Object implements DEREncodablePREVIEW
This class implements the `EncryptedPrivateKeyInfo` type as defined in PKCS #8.

Its ASN.1 definition is as follows:

    EncryptedPrivateKeyInfo ::=  SEQUENCE {
        encryptionAlgorithm   AlgorithmIdentifier,
        encryptedData   OCTET STRING }

    AlgorithmIdentifier  ::=  SEQUENCE  {
        algorithm              OBJECT IDENTIFIER,
        parameters             ANY DEFINED BY algorithm OPTIONAL  }

Since:
  1.4
See Also:
  - `PKCS8EncodedKeySpec`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `EncryptedPrivateKeyInfo(byte[] encoded)`
  Constructs an `EncryptedPrivateKeyInfo` from a given encrypted PKCS#8 ASN.1 encoding.
  `EncryptedPrivateKeyInfo(String algName, byte[] encryptedData)`
  Constructs an `EncryptedPrivateKeyInfo` from the encryption algorithm name and the encrypted data.
  `EncryptedPrivateKeyInfo(AlgorithmParameters algParams, byte[] encryptedData)`
  Constructs an `EncryptedPrivateKeyInfo` from the encryption algorithm parameters and the encrypted data.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static EncryptedPrivateKeyInfo`
  `encrypt(DEREncodablePREVIEW de, char[] password)`
  Preview.
  Creates an `EncryptedPrivateKeyInfo` by encrypting the specified `DEREncodable`.
  `static EncryptedPrivateKeyInfo`
  `encrypt(DEREncodablePREVIEW de, char[] password, String algorithm, AlgorithmParameterSpec params, Provider provider)`
  Preview.
  Creates an `EncryptedPrivateKeyInfo` by encrypting the specified `DEREncodable`.
  `static EncryptedPrivateKeyInfo`
  `encrypt(DEREncodablePREVIEW de, Key encryptKey, String algorithm, AlgorithmParameterSpec params, Provider provider, SecureRandom random)`
  Preview.
  Creates an `EncryptedPrivateKeyInfo` by encrypting the specified `DEREncodable`.
  `String`
  `getAlgName()`
  Returns the encryption algorithm.
  `AlgorithmParameters`
  `getAlgParameters()`
  Returns the algorithm parameters used by the encryption algorithm.
  `byte[]`
  `getEncoded()`
  Returns the ASN.1 encoding of this object.
  `byte[]`
  `getEncryptedData()`
  Returns the encrypted data.
  `PrivateKey`
  `getKey(char[] password)`
  Preview.
  Extracts and returns the enclosed `PrivateKey` using the specified password.
  `PrivateKey`
  `getKey(Key decryptKey, Provider provider)`
  Preview.
  Extracts and returns the enclosed `PrivateKey` using the specified decryption key and provider.
  `KeyPair`
  `getKeyPair(char[] password)`
  Preview.
  Extracts and returns the enclosed `KeyPair` using the specified password.
  `KeyPair`
  `getKeyPair(Key decryptKey, Provider provider)`
  Preview.
  Extracts and returns the enclosed `KeyPair` using the specified decryption key and provider.
  `PKCS8EncodedKeySpec`
  `getKeySpec(Key decryptKey)`
  Extract the enclosed PKCS8EncodedKeySpec object from the encrypted data and return it.
  `PKCS8EncodedKeySpec`
  `getKeySpec(Key decryptKey, String providerName)`
  Extract the enclosed PKCS8EncodedKeySpec object from the encrypted data and return it.
  `PKCS8EncodedKeySpec`
  `getKeySpec(Key decryptKey, Provider provider)`
  Extract the enclosed PKCS8EncodedKeySpec object from the encrypted data and return it.
  `PKCS8EncodedKeySpec`
  `getKeySpec(Cipher cipher)`
  Extract the enclosed PKCS8EncodedKeySpec object from the encrypted data and return it.

  ### Methods declared in class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`
  Modifier and Type
  Method
  Description
  `protected Object`
  `clone()`
  Creates and returns a copy of this object.
  `boolean`
  `equals(Object obj)`
  Indicates whether some other object is "equal to" this one.
  `protected void`
  `finalize()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Finalization is deprecated and subject to removal in a future release.
  `final Class<?>`
  `getClass()`
  Returns the runtime class of this `Object`.
  `int`
  `hashCode()`
  Returns a hash code value for this object.
  `final void`
  `notify()`
  Wakes up a single thread that is waiting on this object's monitor.
  `final void`
  `notifyAll()`
  Wakes up all threads that are waiting on this object's monitor.
  `String`
  `toString()`
  Returns a string representation of the object.
  `final void`
  `wait()`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
  `final void`
  `wait(long timeoutMillis)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
  `final void`
  `wait(long timeoutMillis, int nanos)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

- ## Constructor Details

  - ### EncryptedPrivateKeyInfo

    public EncryptedPrivateKeyInfo(byte[] encoded) throws IOException
    Constructs an `EncryptedPrivateKeyInfo` from a given encrypted PKCS#8 ASN.1 encoding.
    Parameters:
      `encoded` - the ASN.1 encoding of this object. The contents of the array are copied to protect against subsequent modification.
    Throws:
      `NullPointerException` - if `encoded` is `null`.
      `IOException` - if error occurs when parsing the ASN.1 encoding.

  - ### EncryptedPrivateKeyInfo

    public EncryptedPrivateKeyInfo(String algName, byte[] encryptedData) throws NoSuchAlgorithmException
    Constructs an `EncryptedPrivateKeyInfo` from the encryption algorithm name and the encrypted data.

    Note: This constructor will use `null` as the value of the algorithm parameters. If the encryption algorithm has parameters whose value is not `null`, a different constructor, e.g. EncryptedPrivateKeyInfo(AlgorithmParameters, byte[]), should be used.

    Parameters:
      `algName` - encryption algorithm name. See the Java Security Standard Algorithm Names document for information about standard Cipher algorithm names.
      `encryptedData` - encrypted data. The contents of `encryptedData` are copied to protect against subsequent modification when constructing this object.
    Throws:
      `NullPointerException` - if `algName` or `encryptedData` is `null`.
      `IllegalArgumentException` - if `encryptedData` is empty, i.e. 0-length.
      `NoSuchAlgorithmException` - if the specified algName is not supported.
    External Specifications
      - Java Security Standard Algorithm Names

  - ### EncryptedPrivateKeyInfo

    public EncryptedPrivateKeyInfo(AlgorithmParameters algParams, byte[] encryptedData) throws NoSuchAlgorithmException
    Constructs an `EncryptedPrivateKeyInfo` from the encryption algorithm parameters and the encrypted data.
    Parameters:
      `algParams` - the algorithm parameters for the encryption algorithm. `algParams.getEncoded()` should return the ASN.1 encoded bytes of the `parameters` field of the `AlgorithmIdentifier` component of the `EncryptedPrivateKeyInfo` type.
      `encryptedData` - encrypted data. The contents of `encryptedData` are copied to protect against subsequent modification when constructing this object.
    Throws:
      `NullPointerException` - if `algParams` or `encryptedData` is `null`.
      `IllegalArgumentException` - if `encryptedData` is empty, i.e. 0-length.
      `NoSuchAlgorithmException` - if the specified algName of the specified `algParams` parameter is not supported.

- ## Method Details

  - ### getAlgName

    public String getAlgName()
    Returns the encryption algorithm.

    Note: Standard name is returned instead of the specified one in the constructor when such mapping is available. See the Java Security Standard Algorithm Names document for information about standard Cipher algorithm names.

    Returns:
      the encryption algorithm name.
    External Specifications
      - Java Security Standard Algorithm Names

  - ### getAlgParameters

    public AlgorithmParameters getAlgParameters()
    Returns the algorithm parameters used by the encryption algorithm.
    Returns:
      the algorithm parameters.

  - ### getEncryptedData

    public byte[] getEncryptedData()
    Returns the encrypted data.
    Returns:
      the encrypted data. Returns a new array each time this method is called.

  - ### getKeySpec

    public PKCS8EncodedKeySpec getKeySpec(Cipher cipher) throws InvalidKeySpecException
    Extract the enclosed PKCS8EncodedKeySpec object from the encrypted data and return it.
    Note: In order to successfully retrieve the enclosed PKCS8EncodedKeySpec object, `cipher` needs to be initialized to either Cipher.DECRYPT_MODE or Cipher.UNWRAP_MODE, with the same key and parameters used for generating the encrypted data.
    Parameters:
      `cipher` - the initialized `Cipher` object which will be used for decrypting the encrypted data.
    Returns:
      the PKCS8EncodedKeySpec object.
    Throws:
      `NullPointerException` - if `cipher` is `null`.
      `InvalidKeySpecException` - if the given cipher is inappropriate for the encrypted data or the encrypted data is corrupted and cannot be decrypted.

  - ### encrypt

    public static EncryptedPrivateKeyInfo encrypt(DEREncodablePREVIEW de, char[] password, String algorithm, AlgorithmParameterSpec params, Provider provider)
    `encrypt` is a preview API of the Java platform.
    Programs can only use `encrypt` when preview features are enabled.
    Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
    Creates an `EncryptedPrivateKeyInfo` by encrypting the specified `DEREncodable`. A valid password-based encryption (PBE) algorithm and password must be specified.

    The format of the PBE algorithm string is described in the Cipher Algorithms section of the Java Security Standard Algorithm Names Specification.

    Parameters:
      `de` - the `DEREncodable` to encrypt. Supported types include `PrivateKey`, `KeyPair`, and `PKCS8EncodedKeySpec`.
      `password` - the password used for PBE encryption. This array is cloned before use.
      `algorithm` - the PBE encryption algorithm
      `params` - the `AlgorithmParameterSpec` used for encryption. If `null`, the provider’s default parameters are applied.
      `provider` - the `Provider` for `SecretKeyFactory` and `Cipher` operations. If `null`, provider defaults are used.
    Returns:
      an `EncryptedPrivateKeyInfo`
    Throws:
      `NullPointerException` - if `de`, `password`, or `algorithm` is `null`
      `IllegalArgumentException` - if `de` is an unsupported `DEREncodable`, if an error occurs while generating the PBE key, if `algorithm` or `params` are not supported by any provider, or if an error occurs during encryption.
    Since:
      26

  - ### encrypt

    public static EncryptedPrivateKeyInfo encrypt(DEREncodablePREVIEW de, char[] password)
    `encrypt` is a preview API of the Java platform.
    Programs can only use `encrypt` when preview features are enabled.
    Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
    Creates an `EncryptedPrivateKeyInfo` by encrypting the specified `DEREncodable`. A valid password must be specified. A default password-based encryption (PBE) algorithm and provider are used.
    Implementation Note:
      The `jdk.epkcs8.defaultAlgorithm` security property defines the default encryption algorithm. The `AlgorithmParameterSpec` defaults are determined by the provider.
    Parameters:
      `de` - the `DEREncodable` to encrypt. Supported types include `PrivateKey`, `KeyPair`, and `PKCS8EncodedKeySpec`.
      `password` - the password used for PBE encryption. This array is cloned before use.
    Returns:
      an `EncryptedPrivateKeyInfo`
    Throws:
      `NullPointerException` - if `de` or `password` is `null`
      `IllegalArgumentException` - if `de` is an unsupported `DEREncodable`, if an error occurs while generating the PBE key, or if the default algorithm is misconfigured
    Since:
      26

  - ### encrypt

    public static EncryptedPrivateKeyInfo encrypt(DEREncodablePREVIEW de, Key encryptKey, String algorithm, AlgorithmParameterSpec params, Provider provider, SecureRandom random)
    `encrypt` is a preview API of the Java platform.
    Programs can only use `encrypt` when preview features are enabled.
    Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
    Creates an `EncryptedPrivateKeyInfo` by encrypting the specified `DEREncodable`. A valid encryption algorithm and `Key` must be specified.

    The format of the algorithm string is described in the Cipher Algorithms section of the Java Security Standard Algorithm Names Specification.

    Parameters:
      `de` - the `DEREncodable` to encrypt. Supported types include `PrivateKey`, `KeyPair`, and `PKCS8EncodedKeySpec`.
      `encryptKey` - the key used to encrypt the encoding
      `algorithm` - the encryption algorithm, such as a password-based encryption (PBE) algorithm
      `params` - the `AlgorithmParameterSpec` used for encryption. If `null`, the provider’s default parameters are applied.
      `provider` - the `Provider` for `Cipher` operations. If `null`, the default provider list is used.
      `random` - the `SecureRandom` instance used during encryption. If `null`, the default is used.
    Returns:
      an `EncryptedPrivateKeyInfo`
    Throws:
      `NullPointerException` - if `de`, `encryptKey`, or `algorithm` is `null`
      `IllegalArgumentException` - if `de` is an unsupported `DEREncodable`, if `encryptKey` is invalid, if `algorithm` or `params` are not supported by any provider, or if an error occurs during encryption
    Since:
      26

  - ### getKey

    public PrivateKey getKey(char[] password) throws NoSuchAlgorithmException, InvalidKeyException
    `getKey` is a preview API of the Java platform.
    Programs can only use `getKey` when preview features are enabled.
    Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
    Extracts and returns the enclosed `PrivateKey` using the specified password.
    Parameters:
      `password` - the password used for PBE decryption. The array is cloned before use.
    Returns:
      the decrypted `PrivateKey`
    Throws:
      `NullPointerException` - if `password` is `null`
      `NoSuchAlgorithmException` - if the decryption algorithm is unsupported
      `InvalidKeyException` - if an error occurs during parsing, decryption, or key generation
    Since:
      25

  - ### getKey

    public PrivateKey getKey(Key decryptKey, Provider provider) throws NoSuchAlgorithmException, InvalidKeyException
    `getKey` is a preview API of the Java platform.
    Programs can only use `getKey` when preview features are enabled.
    Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
    Extracts and returns the enclosed `PrivateKey` using the specified decryption key and provider.
    Parameters:
      `decryptKey` - the decryption key. Must not be `null`.
      `provider` - the `Provider` for `Cipher` decryption and `PrivateKey` generation. If `null`, the default provider configuration is used.
    Returns:
      the decrypted `PrivateKey`
    Throws:
      `NullPointerException` - if `decryptKey` is `null`
      `NoSuchAlgorithmException` - if the decryption algorithm is unsupported
      `InvalidKeyException` - if an error occurs during parsing, decryption, or key generation
    Since:
      25

  - ### getKeyPair

    public KeyPair getKeyPair(char[] password) throws NoSuchAlgorithmException, InvalidKeyException
    `getKeyPair` is a preview API of the Java platform.
    Programs can only use `getKeyPair` when preview features are enabled.
    Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
    Extracts and returns the enclosed `KeyPair` using the specified password. If the encoded data does not contain both a public and private key, an `InvalidKeyException` is thrown.
    Parameters:
      `password` - the password used for PBE decryption. The array is cloned before use.
    Returns:
      a decrypted `KeyPair`
    Throws:
      `NullPointerException` - if `password` is `null`
      `NoSuchAlgorithmException` - if the decryption algorithm is unsupported
      `InvalidKeyException` - if the encoded data lacks a public key, or if an error occurs during parsing, decryption, or key generation
    Since:
      26

  - ### getKeyPair

    public KeyPair getKeyPair(Key decryptKey, Provider provider) throws NoSuchAlgorithmException, InvalidKeyException
    `getKeyPair` is a preview API of the Java platform.
    Programs can only use `getKeyPair` when preview features are enabled.
    Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
    Extracts and returns the enclosed `KeyPair` using the specified decryption key and provider. If the encoded data does not contain both a public and private key, an `InvalidKeyException` is thrown.
    Parameters:
      `decryptKey` - the decryption key. Must not be `null`.
      `provider` - the `Provider` for `Cipher` decryption and key generation. If `null`, the default provider configuration is used.
    Returns:
      a decrypted `KeyPair`
    Throws:
      `NullPointerException` - if `decryptKey` is `null`
      `NoSuchAlgorithmException` - if the decryption algorithm is unsupported
      `InvalidKeyException` - if the encoded data lacks a public key, or if an error occurs during parsing, decryption, or key generation
    Since:
      26

  - ### getKeySpec

    public PKCS8EncodedKeySpec getKeySpec(Key decryptKey) throws NoSuchAlgorithmException, InvalidKeyException
    Extract the enclosed PKCS8EncodedKeySpec object from the encrypted data and return it.
    Parameters:
      `decryptKey` - key used for decrypting the encrypted data.
    Returns:
      the PKCS8EncodedKeySpec object.
    Throws:
      `NullPointerException` - if `decryptKey` is `null`.
      `NoSuchAlgorithmException` - if cannot find appropriate cipher to decrypt the encrypted data.
      `InvalidKeyException` - if `decryptKey` cannot be used to decrypt the encrypted data or the decryption result is not a valid PKCS8KeySpec.
    Since:
      1.5

  - ### getKeySpec

    public PKCS8EncodedKeySpec getKeySpec(Key decryptKey, String providerName) throws NoSuchProviderException, NoSuchAlgorithmException, InvalidKeyException
    Extract the enclosed PKCS8EncodedKeySpec object from the encrypted data and return it.
    Parameters:
      `decryptKey` - key used for decrypting the encrypted data.
      `providerName` - the name of provider whose cipher implementation will be used.
    Returns:
      the PKCS8EncodedKeySpec object
    Throws:
      `NullPointerException` - if `decryptKey` or `providerName` is `null`.
      `NoSuchProviderException` - if no provider `providerName` is registered.
      `NoSuchAlgorithmException` - if cannot find appropriate cipher to decrypt the encrypted data.
      `InvalidKeyException` - if `decryptKey` cannot be used to decrypt the encrypted data or the decryption result is not a valid PKCS8KeySpec.
    Since:
      1.5

  - ### getKeySpec

    public PKCS8EncodedKeySpec getKeySpec(Key decryptKey, Provider provider) throws NoSuchAlgorithmException, InvalidKeyException
    Extract the enclosed PKCS8EncodedKeySpec object from the encrypted data and return it.
    Parameters:
      `decryptKey` - key used for decrypting the encrypted data.
      `provider` - the name of provider whose cipher implementation will be used.
    Returns:
      the PKCS8EncodedKeySpec object.
    Throws:
      `NullPointerException` - if `decryptKey` or `provider` is `null`.
      `NoSuchAlgorithmException` - if cannot find appropriate cipher to decrypt the encrypted data in `provider`.
      `InvalidKeyException` - if `decryptKey` cannot be used to decrypt the encrypted data or the decryption result is not a valid PKCS8KeySpec.
    Since:
      1.5

  - ### getEncoded

    public byte[] getEncoded() throws IOException
    Returns the ASN.1 encoding of this object.
    Returns:
      the ASN.1 encoding. Returns a new array each time this method is called.
    Throws:
      `IOException` - if error occurs when constructing its ASN.1 encoding.