Class Ring

  • All Implemented Interfaces:
    java.lang.Cloneable

    public class Ring
    extends java.lang.Object
    implements java.lang.Cloneable
    A collection of Keys.

    Keys can be added to the ring by adding them to the list returned by the getKeys() method, or by loading them from ascii armor text via the load(String) method, or by loading them from a file via the load(File) method, or by loading them from an input stream via the load(InputStream) method. A ring can also be constructed from an existing array of keys (Ring(Key...)), or from an existing list of keys (Ring(List)), or from an ASCII-armor text string containing the keys (Ring(String)), or from a file containing the keys (Ring(File)), or from an input stream containing the keys (Ring(InputStream)).

    Once keys have been loaded, their subkeys can be manipulated to customize usage flags (to indicate whether a subkey should be used for encryption, decryption, signing, or verification), and to supply the passphrase needed to unlock the subkey (which is needed to use the subkey for decryption and signing).

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected java.util.List<Key> keys  
    • Constructor Summary

      Constructors 
      Constructor Description
      Ring()
      Constructs a new empty ring.
      Ring​(java.io.File file)
      Loads all keys from the specified file.
      Ring​(java.io.InputStream stream)
      Loads all keys from the specified input stream.
      Ring​(java.lang.String armor)
      Loads all keys from the specified armored text.
      Ring​(java.util.List<Key> keys)
      Constructs a new ring with the specified list of keys.
      Ring​(Key... keys)
      Constructs a new ring with the specified array of keys.
    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      boolean asBoolean()
      True if this contains at least one key.
      void clearSecrets()
      Zeroes-out the cached passphrase for all keys, and releases the extracted private key material for garbage collection.
      Ring clone()  
      java.util.List<Key> findAll​(java.lang.Long id)
      All keys for which the specified ID is any subkey's full ID.
      java.util.List<Key> findAll​(java.lang.String id)
      All keys for which the specified string is a case-insensitive substring of either: any subkey's full ID (eg "0x1234567890ABCDEF") any subkey's fingerprint (eg "1234567890ABCDEF1234567890ABCDEF12345678") any one of any subkey's user IDs (eg "Alice (work) <alice@example.com>")
      java.util.List<Key> findAll​(java.util.regex.Pattern id)
      All keys for which the specified pattern matches any part of either: any subkey's full ID (eg "0x1234567890ABCDEF") any subkey's fingerprint (eg "1234567890ABCDEF1234567890ABCDEF12345678") any one of any subkey's user IDs (eg "Alice (work) <alice@example.com>")
      Key findById​(java.lang.Long id)
      Deprecated.
      Use findAll(java.lang.Long) (to find all subkeys on a ring, in case the same key had been included multiple times with different settings on the same ring).
      java.util.List<Key> getDecryptionKeys()
      All keys that can decrypt, or an empty list.
      java.util.List<Key> getEncryptionKeys()
      All keys that can encrypt, or an empty list.
      java.util.List<Key> getKeys()
      All keys, an or an empty list.
      java.util.List<Key> getSigningKeys()
      All keys that can sign, or an empty list.
      java.util.List<Key> getVerificationKeys()
      All keys that can verify, or an empty list.
      java.util.List<Key> load​(java.io.File file)
      Loads all keys from the specified file, and adds them to this ring's existing list of keys.
      java.util.List<Key> load​(java.io.InputStream stream)
      Loads all keys from the specified input stream, and adds them to this ring's existing list of keys.
      java.util.List<Key> load​(java.lang.String armor)
      Loads all keys from the specified armored text, and adds them to this ring's existing list of keys.
      protected Key newKey​(java.util.ArrayList<Subkey> subkeys)  
      protected Key newKey​(org.bouncycastle.openpgp.PGPPublicKeyRing ring)  
      protected Key newKey​(org.bouncycastle.openpgp.PGPSecretKeyRing ring)  
      protected Subkey newSubkey()  
      protected Subkey newSubkey​(org.bouncycastle.openpgp.PGPPublicKey k)  
      protected Subkey newSubkey​(org.bouncycastle.openpgp.PGPSecretKey k)  
      protected java.util.Iterator<?> parse​(java.io.InputStream stream)
      Separates stream into PGP packets.
      protected void setKeys​(java.util.List<Key> x)
      All keys, an or an empty list.
      java.lang.String toString()
      Display string for this ring, including listing each key on the ring, with each subkey's usage flags, short ID, and user IDs.
      • Methods inherited from class java.lang.Object

        equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Field Detail

      • keys

        protected java.util.List<Key> keys
    • Constructor Detail

      • Ring

        public Ring()
        Constructs a new empty ring.
      • Ring

        public Ring​(Key... keys)
        Constructs a new ring with the specified array of keys.
      • Ring

        public Ring​(java.util.List<Key> keys)
        Constructs a new ring with the specified list of keys.
      • Ring

        public Ring​(java.lang.String armor)
             throws java.io.IOException,
                    org.bouncycastle.openpgp.PGPException
        Loads all keys from the specified armored text.
        Throws:
        java.io.IOException
        org.bouncycastle.openpgp.PGPException
      • Ring

        public Ring​(java.io.File file)
             throws java.io.IOException,
                    org.bouncycastle.openpgp.PGPException
        Loads all keys from the specified file.
        Throws:
        java.io.IOException
        org.bouncycastle.openpgp.PGPException
      • Ring

        public Ring​(java.io.InputStream stream)
             throws java.io.IOException,
                    org.bouncycastle.openpgp.PGPException
        Loads all keys from the specified input stream.
        Throws:
        java.io.IOException
        org.bouncycastle.openpgp.PGPException
    • Method Detail

      • clone

        public Ring clone()
        Overrides:
        clone in class java.lang.Object
      • toString

        public java.lang.String toString()
        Display string for this ring, including listing each key on the ring, with each subkey's usage flags, short ID, and user IDs.
        Overrides:
        toString in class java.lang.Object
      • asBoolean

        public boolean asBoolean()
        True if this contains at least one key.
      • getSigningKeys

        public java.util.List<Key> getSigningKeys()
        All keys that can sign, or an empty list.
      • getVerificationKeys

        public java.util.List<Key> getVerificationKeys()
        All keys that can verify, or an empty list.
      • getEncryptionKeys

        public java.util.List<Key> getEncryptionKeys()
        All keys that can encrypt, or an empty list.
      • getDecryptionKeys

        public java.util.List<Key> getDecryptionKeys()
        All keys that can decrypt, or an empty list.
      • getKeys

        public java.util.List<Key> getKeys()
        All keys, an or an empty list.
      • setKeys

        protected void setKeys​(java.util.List<Key> x)
        All keys, an or an empty list.
      • findById

        @Deprecated
        public Key findById​(java.lang.Long id)
        Deprecated.
        Use findAll(java.lang.Long) (to find all subkeys on a ring, in case the same key had been included multiple times with different settings on the same ring).
        First key containing the subkey with the specified full ID, or null.
      • findAll

        public java.util.List<Key> findAll​(java.lang.Long id)
        All keys for which the specified ID is any subkey's full ID. Normally this will return 0 or 1 keys, but if a key has been added to a ring multiple times (with different settings, such as one time as a public key and one time as a private key), this method may return more than one key instance.
      • findAll

        public java.util.List<Key> findAll​(java.lang.String id)
        All keys for which the specified string is a case-insensitive substring of either:
        • any subkey's full ID (eg "0x1234567890ABCDEF")
        • any subkey's fingerprint (eg "1234567890ABCDEF1234567890ABCDEF12345678")
        • any one of any subkey's user IDs (eg "Alice (work) <alice@example.com>")

        So for example, a string "0x1234" would match the above full ID; a string "90ab" would match the above fingerprint; and a string "alice (work)" would match the above user ID.

      • findAll

        public java.util.List<Key> findAll​(java.util.regex.Pattern id)
        All keys for which the specified pattern matches any part of either:
        • any subkey's full ID (eg "0x1234567890ABCDEF")
        • any subkey's fingerprint (eg "1234567890ABCDEF1234567890ABCDEF12345678")
        • any one of any subkey's user IDs (eg "Alice (work) <alice@example.com>")

        So for example, a pattern /0x1234/ would match the above full ID; a pattern /(?i)90ab/ would match the above fingerprint; and a pattern /Alice .work./ would match the above user ID.

      • clearSecrets

        public void clearSecrets()
        Zeroes-out the cached passphrase for all keys, and releases the extracted private key material for garbage collection.
      • load

        public java.util.List<Key> load​(java.lang.String armor)
                                 throws java.io.IOException,
                                        org.bouncycastle.openpgp.PGPException
        Loads all keys from the specified armored text, and adds them to this ring's existing list of keys.
        Throws:
        java.io.IOException
        org.bouncycastle.openpgp.PGPException
      • load

        public java.util.List<Key> load​(java.io.File file)
                                 throws java.io.IOException,
                                        org.bouncycastle.openpgp.PGPException
        Loads all keys from the specified file, and adds them to this ring's existing list of keys.
        Throws:
        java.io.IOException
        org.bouncycastle.openpgp.PGPException
      • load

        public java.util.List<Key> load​(java.io.InputStream stream)
                                 throws java.io.IOException,
                                        org.bouncycastle.openpgp.PGPException
        Loads all keys from the specified input stream, and adds them to this ring's existing list of keys.
        Throws:
        java.io.IOException
        org.bouncycastle.openpgp.PGPException
      • parse

        protected java.util.Iterator<?> parse​(java.io.InputStream stream)
                                       throws java.io.IOException,
                                              org.bouncycastle.openpgp.PGPException
        Separates stream into PGP packets.
        Throws:
        java.io.IOException
        org.bouncycastle.openpgp.PGPException
        See Also:
        PGPObjectFactory
      • newKey

        protected Key newKey​(java.util.ArrayList<Subkey> subkeys)
      • newKey

        protected Key newKey​(org.bouncycastle.openpgp.PGPPublicKeyRing ring)
                      throws org.bouncycastle.openpgp.PGPException
        Throws:
        org.bouncycastle.openpgp.PGPException
      • newKey

        protected Key newKey​(org.bouncycastle.openpgp.PGPSecretKeyRing ring)
                      throws org.bouncycastle.openpgp.PGPException
        Throws:
        org.bouncycastle.openpgp.PGPException
      • newSubkey

        protected Subkey newSubkey()
      • newSubkey

        protected Subkey newSubkey​(org.bouncycastle.openpgp.PGPPublicKey k)
                            throws org.bouncycastle.openpgp.PGPException
        Throws:
        org.bouncycastle.openpgp.PGPException
      • newSubkey

        protected Subkey newSubkey​(org.bouncycastle.openpgp.PGPSecretKey k)
                            throws org.bouncycastle.openpgp.PGPException
        Throws:
        org.bouncycastle.openpgp.PGPException