PGPSecretKeyRing
Date: 2016-06-23

org.bouncycastle.openpgp

## Class PGPSecretKeyRing

- java.lang.Object
- - org.bouncycastle.openpgp.PGPKeyRing
  - - org.bouncycastle.openpgp.PGPSecretKeyRing

- All Implemented Interfaces:
    java.lang.Iterable<PGPSecretKey>
  Direct Known Subclasses:
    BcPGPSecretKeyRing, JcaPGPSecretKeyRing

      public class PGPSecretKeyRing
      extends PGPKeyRing
      implements org.bouncycastle.util.Iterable<PGPSecretKey>

  Class to hold a single master secret key and its subkeys.

  Often PGP keyring files consist of multiple master keys, if you are trying to process or construct one of these you should use the `PGPSecretKeyRingCollection` class.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `PGPSecretKeyRing(byte[] encoding, KeyFingerPrintCalculator fingerPrintCalculator)`
    `PGPSecretKeyRing(java.io.InputStream in, KeyFingerPrintCalculator fingerPrintCalculator)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static PGPSecretKeyRing` | `copyWithNewPassword(PGPSecretKeyRing ring, PBESecretKeyDecryptor oldKeyDecryptor, PBESecretKeyEncryptor newKeyEncryptor)` Return a copy of the passed in secret key ring, with the private keys (where present) associated with the master key and sub keys are encrypted using a new password and the passed in algorithm.
    `void` | `encode(java.io.OutputStream outStream)`
    `byte[]` | `getEncoded()`
    `java.util.Iterator<PGPPublicKey>` | `getExtraPublicKeys()` Return an iterator of the public keys in the secret key ring that have no matching private key.
    `PGPPublicKey` | `getPublicKey()` Return the public key for the master key.
    `PGPPublicKey` | `getPublicKey(long keyID)` Return the public key referred to by the passed in keyID if it is present.
    `java.util.Iterator<PGPPublicKey>` | `getPublicKeys()` Return an iterator containing all the public keys.
    `PGPSecretKey` | `getSecretKey()` Return the master private key.
    `PGPSecretKey` | `getSecretKey(long keyId)`
    `java.util.Iterator<PGPSecretKey>` | `getSecretKeys()` Return an iterator containing all the secret keys.
    `static PGPSecretKeyRing` | `insertSecretKey(PGPSecretKeyRing secRing, PGPSecretKey secKey)` Returns a new key ring with the secret key passed in either added or replacing an existing one with the same key ID.
    `java.util.Iterator<PGPSecretKey>` | `iterator()` Support method for Iterable where available.
    `static PGPSecretKeyRing` | `removeSecretKey(PGPSecretKeyRing secRing, PGPSecretKey secKey)` Returns a new key ring with the secret key passed in removed from the key ring.
    `static PGPSecretKeyRing` | `replacePublicKeys(PGPSecretKeyRing secretRing, PGPPublicKeyRing publicRing)` Replace the public key set on the secret ring with the corresponding key off the public ring.

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

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

- - ### Constructor Detail

    - #### PGPSecretKeyRing

          public PGPSecretKeyRing(byte[] encoding,
                          KeyFingerPrintCalculator fingerPrintCalculator)
                           throws java.io.IOException,
                                  PGPException

      Throws:
        `java.io.IOException`
        `PGPException`

    - #### PGPSecretKeyRing

          public PGPSecretKeyRing(java.io.InputStream in,
                          KeyFingerPrintCalculator fingerPrintCalculator)
                           throws java.io.IOException,
                                  PGPException

      Throws:
        `java.io.IOException`
        `PGPException`

  - ### Method Detail

    - #### getPublicKey

          public PGPPublicKey getPublicKey()

      Return the public key for the master key.
      Specified by:
        `getPublicKey` in class `PGPKeyRing`
      Returns:
        PGPPublicKey

    - #### getPublicKey

          public PGPPublicKey getPublicKey(long keyID)

      Return the public key referred to by the passed in keyID if it is present.
      Specified by:
        `getPublicKey` in class `PGPKeyRing`
      Parameters:
        `keyID` -
      Returns:
        PGPPublicKey

    - #### getPublicKeys

          public java.util.Iterator<PGPPublicKey> getPublicKeys()

      Return an iterator containing all the public keys.
      Specified by:
        `getPublicKeys` in class `PGPKeyRing`
      Returns:
        Iterator

    - #### getSecretKey

          public PGPSecretKey getSecretKey()

      Return the master private key.
      Returns:
        PGPSecretKey

    - #### getSecretKeys

          public java.util.Iterator<PGPSecretKey> getSecretKeys()

      Return an iterator containing all the secret keys.
      Returns:
        Iterator

    - #### getSecretKey

          public PGPSecretKey getSecretKey(long keyId)

    - #### getExtraPublicKeys

          public java.util.Iterator<PGPPublicKey> getExtraPublicKeys()

      Return an iterator of the public keys in the secret key ring that have no matching private key. At the moment only personal certificate data appears in this fashion.
      Returns:
        iterator of unattached, or extra, public keys.

    - #### getEncoded

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

      Specified by:
        `getEncoded` in class `PGPKeyRing`
      Throws:
        `java.io.IOException`

    - #### encode

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

      Specified by:
        `encode` in class `PGPKeyRing`
      Throws:
        `java.io.IOException`

    - #### iterator

          public java.util.Iterator<PGPSecretKey> iterator()

      Support method for Iterable where available.
      Specified by:
        `iterator` in interface `java.lang.Iterable<PGPSecretKey>`

    - #### replacePublicKeys

          public static PGPSecretKeyRing replacePublicKeys(PGPSecretKeyRing secretRing,
                                           PGPPublicKeyRing publicRing)

      Replace the public key set on the secret ring with the corresponding key off the public ring.
      Parameters:
        `secretRing` - secret ring to be changed.
        `publicRing` - public ring containing the new public key set.

    - #### copyWithNewPassword

          public static PGPSecretKeyRing copyWithNewPassword(PGPSecretKeyRing ring,
                                             PBESecretKeyDecryptor oldKeyDecryptor,
                                             PBESecretKeyEncryptor newKeyEncryptor)
                                                      throws PGPException

      Return a copy of the passed in secret key ring, with the private keys (where present) associated with the master key and sub keys are encrypted using a new password and the passed in algorithm.
      Parameters:
        `ring` - the PGPSecretKeyRing 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.
      Returns:
        the updated key ring.
      Throws:
        `PGPException`

    - #### insertSecretKey

          public static PGPSecretKeyRing insertSecretKey(PGPSecretKeyRing secRing,
                                         PGPSecretKey secKey)

      Returns a new key ring with the secret key passed in either added or replacing an existing one with the same key ID.
      Parameters:
        `secRing` - the secret key ring to be modified.
        `secKey` - the secret key to be added.
      Returns:
        a new secret key ring.

    - #### removeSecretKey

          public static PGPSecretKeyRing removeSecretKey(PGPSecretKeyRing secRing,
                                         PGPSecretKey secKey)

      Returns a new key ring with the secret key passed in removed from the key ring.
      Parameters:
        `secRing` - the secret key ring to be modified.
        `secKey` - the secret key to be removed.
      Returns:
        a new secret key ring, or null if secKey is not found.