Package org.bouncycastle.openpgp

## Class PGPSecretKey

- java.lang.Object
- - org.bouncycastle.openpgp.PGPSecretKey

-     public class PGPSecretKey
      extends java.lang.Object

  general class to handle and construct a PGP secret key object.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---

    `PGPSecretKey​(int certificationLevel, PGPKeyPair keyPair, java.lang.String id, PGPDigestCalculator checksumCalculator, PGPSignatureSubpacketVector hashedPcks, PGPSignatureSubpacketVector unhashedPcks, PGPContentSignerBuilder certificationSignerBuilder, PBESecretKeyEncryptor keyEncryptor)`

    Construct a PGPSecretKey using the passed in private/public key pair and binding it to the passed in id using a generated certification of certificationLevel.

    `PGPSecretKey​(int certificationLevel, PGPKeyPair keyPair, java.lang.String id, PGPSignatureSubpacketVector hashedPcks, PGPSignatureSubpacketVector unhashedPcks, PGPContentSignerBuilder certificationSignerBuilder, PBESecretKeyEncryptor keyEncryptor)`

    Construct a PGPSecretKey using the passed in private/public key pair and binding it to the passed in id using a generated certification of certificationLevel.The secret key checksum is calculated using the original non-digest based checksum.

    `PGPSecretKey​(SecretKeyPacket secret, PGPPublicKey pub)` |
    `PGPSecretKey​(PGPKeyPair masterKeyPair, PGPKeyPair keyPair, PGPDigestCalculator checksumCalculator, PGPContentSignerBuilder certificationSignerBuilder, PBESecretKeyEncryptor keyEncryptor)` | Construct a PGPSecretKey sub-key using the passed in private/public key pair and binding it to the master key pair.
    `PGPSecretKey​(PGPKeyPair masterKeyPair, PGPKeyPair keyPair, PGPDigestCalculator checksumCalculator, PGPSignatureSubpacketVector hashedPcks, PGPSignatureSubpacketVector unhashedPcks, PGPContentSignerBuilder certificationSignerBuilder, PBESecretKeyEncryptor keyEncryptor)` | Construct a PGPSecretKey sub-key using the passed in private/public key pair and binding it to the master key pair.
    `PGPSecretKey​(PGPPrivateKey privKey, PGPPublicKey pubKey, PGPDigestCalculator checksumCalculator, boolean isMasterKey, PBESecretKeyEncryptor keyEncryptor)` | Construct a PGPSecretKey using the passed in private key and public key.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static PGPSecretKey` | `copyWithNewPassword​(PGPSecretKey key, PBESecretKeyDecryptor oldKeyDecryptor, PBESecretKeyEncryptor newKeyEncryptor)` | Return a copy of the passed in secret key, encrypted using a new password and the passed in algorithm.
    `void` | `encode​(java.io.OutputStream outStream)` |
    `PGPKeyPair` | `extractKeyPair​(PBESecretKeyDecryptor decryptorFactory)` | Extract a PGPPrivate key from the SecretKey's encrypted contents.
    `PGPPrivateKey` | `extractPrivateKey​(PBESecretKeyDecryptor decryptorFactory)` | Extract a PGPPrivate key from the SecretKey's encrypted contents.
    `byte[]` | `getEncoded()` |
    `int` | `getKeyEncryptionAlgorithm()` | return the algorithm the key is encrypted with.
    `long` | `getKeyID()` | Return the keyID of the public key associated with this key.
    `PGPPublicKey` | `getPublicKey()` | Return the public key associated with this key.
    `S2K` | `getS2K()` | Return the S2K used to process this key
    `int` | `getS2KUsage()` | Return the S2K usage associated with this key.
    `java.util.Iterator<PGPUserAttributeSubpacketVector>` | `getUserAttributes()` | Return any user attribute vectors associated with the key.
    `java.util.Iterator<java.lang.String>` | `getUserIDs()` | Return any userIDs associated with the key.
    `boolean` | `isMasterKey()` | Return true if this is a master key.
    `boolean` | `isPrivateKeyEmpty()` | Detect if the Secret Key's Private Key is empty or not
    `boolean` | `isSigningKey()` | Return true if this key has an algorithm type that makes it suitable to use for signing.
    `static PGPSecretKey` | `parseSecretKeyFromSExpr​(java.io.InputStream inputStream, PBEProtectionRemoverFactory keyProtectionRemoverFactory, KeyFingerPrintCalculator fingerPrintCalculator)` | Deprecated. use org.bouncycastle.gpg.SExprParser - it will also allow you to verify the protection checksum if it is available.
    `static PGPSecretKey` | `parseSecretKeyFromSExpr​(java.io.InputStream inputStream, PBEProtectionRemoverFactory keyProtectionRemoverFactory, PGPPublicKey pubKey)` | Deprecated. use org.bouncycastle.gpg.SExprParser - it will also allow you to verify the protection checksum if it is available.
    `static PGPSecretKey` | `replacePublicKey​(PGPSecretKey secretKey, PGPPublicKey publicKey)` | Replace the passed the public key on the passed in secret key.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### PGPSecretKey

          public PGPSecretKey​(SecretKeyPacket secret,
                              PGPPublicKey pub)

    - #### PGPSecretKey

          public PGPSecretKey​(PGPPrivateKey privKey,
                              PGPPublicKey pubKey,
                              PGPDigestCalculator checksumCalculator,
                              boolean isMasterKey,
                              PBESecretKeyEncryptor keyEncryptor)
                       throws PGPException

      Construct a PGPSecretKey using the passed in private key and public key. This constructor will not add any certifications but assumes that pubKey already has what is required.
      Parameters:
        `privKey` - the private key component.
        `pubKey` - the public key component.
        `checksumCalculator` - a calculator for the private key checksum
        `isMasterKey` - true if the key is a master key, false otherwise.
        `keyEncryptor` - an encryptor for the key if required (null otherwise).
      Throws:
        `PGPException` - if there is an issue creating the secret key packet.

    - #### PGPSecretKey

          public PGPSecretKey​(int certificationLevel,
                              PGPKeyPair keyPair,
                              java.lang.String id,
                              PGPSignatureSubpacketVector hashedPcks,
                              PGPSignatureSubpacketVector unhashedPcks,
                              PGPContentSignerBuilder certificationSignerBuilder,
                              PBESecretKeyEncryptor keyEncryptor)
                       throws PGPException

      Construct a PGPSecretKey using the passed in private/public key pair and binding it to the passed in id using a generated certification of certificationLevel.The secret key checksum is calculated using the original non-digest based checksum.
      Parameters:
        `certificationLevel` - the type of certification to be added.
        `keyPair` - the public/private keys to use.
        `id` - the id to bind to the key.
        `hashedPcks` - the hashed packets to be added to the certification.
        `unhashedPcks` - the unhashed packets to be added to the certification.
        `certificationSignerBuilder` - the builder for generating the certification.
        `keyEncryptor` - an encryptor for the key if required (null otherwise).
      Throws:
        `PGPException` - if there is an issue creating the secret key packet or the certification.

    - #### PGPSecretKey

          public PGPSecretKey​(PGPKeyPair masterKeyPair,
                              PGPKeyPair keyPair,
                              PGPDigestCalculator checksumCalculator,
                              PGPContentSignerBuilder certificationSignerBuilder,
                              PBESecretKeyEncryptor keyEncryptor)
                       throws PGPException

      Construct a PGPSecretKey sub-key using the passed in private/public key pair and binding it to the master key pair. The secret key checksum is calculated using the passed in checksum calculator.
      Parameters:
        `masterKeyPair` - the master public/private keys for the new subkey.
        `keyPair` - the public/private keys to use.
        `checksumCalculator` - a calculator for the private key checksum
        `certificationSignerBuilder` - the builder for generating the certification.
        `keyEncryptor` - an encryptor for the key if required (null otherwise).
      Throws:
        `PGPException` - if there is an issue creating the secret key packet or the certification.

    - #### PGPSecretKey

          public PGPSecretKey​(PGPKeyPair masterKeyPair,
                              PGPKeyPair keyPair,
                              PGPDigestCalculator checksumCalculator,
                              PGPSignatureSubpacketVector hashedPcks,
                              PGPSignatureSubpacketVector unhashedPcks,
                              PGPContentSignerBuilder certificationSignerBuilder,
                              PBESecretKeyEncryptor keyEncryptor)
                       throws PGPException

      Construct a PGPSecretKey sub-key using the passed in private/public key pair and binding it to the master key pair. The secret key checksum is calculated using the passed in checksum calculator.
      Parameters:
        `masterKeyPair` - the master public/private keys for the new subkey.
        `keyPair` - the public/private keys to use.
        `checksumCalculator` - calculator for PGP key checksums.
        `hashedPcks` - the hashed packets to be added to the certification.
        `unhashedPcks` - the unhashed packets to be added to the certification.
        `certificationSignerBuilder` - the builder for generating the certification.
        `keyEncryptor` - an encryptor for the key if required (null otherwise).
      Throws:
        `PGPException` - if there is an issue creating the secret key packet or the certification.

    - #### PGPSecretKey

          public PGPSecretKey​(int certificationLevel,
                              PGPKeyPair keyPair,
                              java.lang.String id,
                              PGPDigestCalculator checksumCalculator,
                              PGPSignatureSubpacketVector hashedPcks,
                              PGPSignatureSubpacketVector unhashedPcks,
                              PGPContentSignerBuilder certificationSignerBuilder,
                              PBESecretKeyEncryptor keyEncryptor)
                       throws PGPException

      Construct a PGPSecretKey using the passed in private/public key pair and binding it to the passed in id using a generated certification of certificationLevel.
      Parameters:
        `certificationLevel` - the type of certification to be added.
        `keyPair` - the public/private keys to use.
        `id` - the id to bind to the key.
        `checksumCalculator` - a calculator for the private key checksum.
        `hashedPcks` - the hashed packets to be added to the certification.
        `unhashedPcks` - the unhashed packets to be added to the certification.
        `certificationSignerBuilder` - the builder for generating the certification.
        `keyEncryptor` - an encryptor for the key if required (null otherwise).
      Throws:
        `PGPException` - if there is an issue creating the secret key packet or the certification.

  - ### Method Detail

    - #### isSigningKey

          public boolean isSigningKey()

      Return true if this key has an algorithm type that makes it suitable to use for signing.

      Note: with version 4 keys KeyFlags subpackets should also be considered when present for determining the preferred use of the key.

      Returns:
        true if this key algorithm is suitable for use with signing.

    - #### isMasterKey

          public boolean isMasterKey()

      Return true if this is a master key.
      Returns:
        true if a master key.

    - #### isPrivateKeyEmpty

          public boolean isPrivateKeyEmpty()

      Detect if the Secret Key's Private Key is empty or not
      Returns:
        boolean whether or not the private key is empty

    - #### getKeyEncryptionAlgorithm

          public int getKeyEncryptionAlgorithm()

      return the algorithm the key is encrypted with.
      Returns:
        the algorithm used to encrypt the secret key.

    - #### getKeyID

          public long getKeyID()

      Return the keyID of the public key associated with this key.
      Returns:
        the keyID associated with this key.

    - #### getS2KUsage

          public int getS2KUsage()

      Return the S2K usage associated with this key.
      Returns:
        the key's S2K usage

    - #### getS2K

          public S2K getS2K()

      Return the S2K used to process this key
      Returns:
        the key's S2K, null if one is not present.

    - #### getPublicKey

          public PGPPublicKey getPublicKey()

      Return the public key associated with this key.
      Returns:
        the public key for this key.

    - #### getUserIDs

          public java.util.Iterator<java.lang.String> getUserIDs()

      Return any userIDs associated with the key.
      Returns:
        an iterator of Strings.

    - #### getUserAttributes

          public java.util.Iterator<PGPUserAttributeSubpacketVector> getUserAttributes()

      Return any user attribute vectors associated with the key.
      Returns:
        an iterator of PGPUserAttributeSubpacketVector.

    - #### extractKeyPair

          public PGPKeyPair extractKeyPair​(PBESecretKeyDecryptor decryptorFactory)
                                    throws PGPException

      Extract a PGPPrivate key from the SecretKey's encrypted contents.
      Parameters:
        `decryptorFactory` - factory to use to generate a decryptor for the passed in secretKey.
      Returns:
        PGPPrivateKey the unencrypted private key.
      Throws:
        `PGPException` - on failure.

    - #### extractPrivateKey

          public PGPPrivateKey extractPrivateKey​(PBESecretKeyDecryptor decryptorFactory)
                                          throws PGPException

      Extract a PGPPrivate key from the SecretKey's encrypted contents.
      Parameters:
        `decryptorFactory` - factory to use to generate a decryptor for the passed in secretKey.
      Returns:
        PGPPrivateKey the unencrypted private key.
      Throws:
        `PGPException` - on failure.

    - #### getEncoded

          public byte[] getEncoded()
                            throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### encode

          public void encode​(java.io.OutputStream outStream)
                      throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### copyWithNewPassword

          public static PGPSecretKey copyWithNewPassword​(PGPSecretKey key,
                                                         PBESecretKeyDecryptor oldKeyDecryptor,
                                                         PBESecretKeyEncryptor newKeyEncryptor)
                                                  throws PGPException

      Return a copy of the passed in secret key, encrypted using a new password and the passed in algorithm.
      Parameters:
        `key` - the PGPSecretKey to be copied.
        `oldKeyDecryptor` - the current decryptor based on the current password for key.
        `newKeyEncryptor` - a new encryptor based on a new password for encrypting the secret key material.
      Throws:
        `PGPException`

    - #### replacePublicKey

          public static PGPSecretKey replacePublicKey​(PGPSecretKey secretKey,
                                                      PGPPublicKey publicKey)

      Replace the passed the public key on the passed in secret key.
      Parameters:
        `secretKey` - secret key to change
        `publicKey` - new public key.
      Returns:
        a new secret key.
      Throws:
        `java.lang.IllegalArgumentException` - if keyIDs do not match.

    - #### parseSecretKeyFromSExpr

          public static PGPSecretKey parseSecretKeyFromSExpr​(java.io.InputStream inputStream,
                                                             PBEProtectionRemoverFactory keyProtectionRemoverFactory,
                                                             PGPPublicKey pubKey)
                                                      throws java.io.IOException,
                                                             PGPException

      Deprecated.
      use org.bouncycastle.gpg.SExprParser - it will also allow you to verify the protection checksum if it is available.
      Parse a secret key from one of the GPG S expression keys associating it with the passed in public key.
      Returns:
        a secret key object.
      Throws:
        `java.io.IOException`
        `PGPException`

    - #### parseSecretKeyFromSExpr

          public static PGPSecretKey parseSecretKeyFromSExpr​(java.io.InputStream inputStream,
                                                             PBEProtectionRemoverFactory keyProtectionRemoverFactory,
                                                             KeyFingerPrintCalculator fingerPrintCalculator)
                                                      throws java.io.IOException,
                                                             PGPException

      Deprecated.
      use org.bouncycastle.gpg.SExprParser - it will also allow you to verify the protection checksum if it is available.
      Parse a secret key from one of the GPG S expression keys.
      Returns:
        a secret key object.
      Throws:
        `java.io.IOException`
        `PGPException`