PGPSecretKey
Date: 2016-06-23

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 and 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(PGPPrivateKey privKey, PGPPublicKey pubKey, PGPDigestCalculator checksumCalculator, boolean isMasterKey, PBESecretKeyEncryptor keyEncryptor)` Construct a PGPSecretKey using the passed in private key and public key.

  - ### Method Summary

    Methods
    Modifier and Type | Method and 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)`
    `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` | `getUserAttributes()` Return any user attribute vectors associated with the key.
    `java.util.Iterator` | `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)` Parse a secret key from one of the GPG S expression keys.
    `static PGPSecretKey` | `parseSecretKeyFromSExpr(java.io.InputStream inputStream, PBEProtectionRemoverFactory keyProtectionRemoverFactory, PGPPublicKey pubKey)` Parse a secret key from one of the GPG S expression keys associating it with the passed in public key.
    `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(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(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 getUserIDs()

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

    - #### getUserAttributes

          public java.util.Iterator getUserAttributes()

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

    - #### 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

      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

      Parse a secret key from one of the GPG S expression keys.
      Returns:
        a secret key object.
      Throws:
        `java.io.IOException`
        `PGPException`