Package org.pgpainless.encryption_signing

Class EncryptionOptions

  • public class EncryptionOptions
extends java.lang.Object
    Options for the encryption process. This class can be used to set encryption parameters, like encryption keys and passphrases, algorithms etc.

    A typical use might look like follows: 

     
 EncryptionOptions opt = new EncryptionOptions();
 opt.addRecipient(aliceKey, "Alice <[email protected]>");
 opt.addPassphrase(Passphrase.fromPassword("AdditionalDecryptionPassphrase123"));

    To use a custom symmetric encryption algorithm, use overrideEncryptionAlgorithm(SymmetricKeyAlgorithm). This will cause PGPainless to use the provided algorithm for message encryption, instead of negotiating an algorithm by inspecting the provided recipient keys.

    By default, PGPainless will encrypt to all suitable, encryption capable subkeys on each recipient's certificate. This behavior can be changed per recipient, e.g. by calling 

     
 opt.addRecipient(aliceKey, EncryptionOptions.encryptToFirstSubkey());
    when adding the recipient key.

    • Method Detail

      • setEvaluationDate

        public EncryptionOptions setEvaluationDate​(@Nonnull
                                           java.util.Date evaluationDate)
        Override the evaluation date for recipient keys with the given date.
        Parameters:
        evaluationDate - new evaluation date
        Returns:
        this

      • addAuthenticatableRecipients

        public EncryptionOptions addAuthenticatableRecipients​(java.lang.String userId,
                                                      boolean email,
                                                      CertificateAuthority authority)
        Identify authenticatable certificates for the given user-ID by querying the CertificateAuthority for identifiable bindings. Add all acceptable bindings, whose trust amount is larger or equal to the target amount to the list of recipients.
        Parameters:
        userId - userId
        email - if true, treat the user-ID as an email address and match all user-IDs containing the mail address
        authority - certificate authority
        Returns:
        encryption options

      • addAuthenticatableRecipients

        public EncryptionOptions addAuthenticatableRecipients​(java.lang.String userId,
                                                      boolean email,
                                                      CertificateAuthority authority,
                                                      int targetAmount)
        Identify authenticatable certificates for the given user-ID by querying the CertificateAuthority for identifiable bindings. Add all acceptable bindings, whose trust amount is larger or equal to the target amount to the list of recipients.
        Parameters:
        userId - userId
        email - if true, treat the user-ID as an email address and match all user-IDs containing the mail address
        authority - certificate authority
        targetAmount - target amount (120 = fully authenticated, 240 = doubly authenticated, 60 = partially authenticated...)
        Returns:
        encryption options

      • addRecipients

        public EncryptionOptions addRecipients​(@Nonnull
                                       java.lang.Iterable<org.bouncycastle.openpgp.PGPPublicKeyRing> keys)
        Add all key rings in the provided Iterable (e.g. PGPPublicKeyRingCollection) as recipients.
        Parameters:
        keys - keys
        Returns:
        this

      • addRecipients

        public EncryptionOptions addRecipients​(@Nonnull
                                       java.lang.Iterable<org.bouncycastle.openpgp.PGPPublicKeyRing> keys,
                                       @Nonnull
                                       EncryptionOptions.EncryptionKeySelector selector)
        Add all key rings in the provided Iterable (e.g. PGPPublicKeyRingCollection) as recipients. Per key ring, the selector is applied to select one or more encryption subkeys.
        Parameters:
        keys - keys
        selector - encryption key selector
        Returns:
        this

      • addRecipient

        public EncryptionOptions addRecipient​(@Nonnull
                                      org.bouncycastle.openpgp.PGPPublicKeyRing key,
                                      @Nonnull
                                      java.lang.CharSequence userId)
        Add a recipient by providing a key and recipient user-id. The user-id is used to determine the recipients preferences (algorithms etc.).
        Parameters:
        key - key ring
        userId - user id
        Returns:
        this

      • addRecipient

        public EncryptionOptions addRecipient​(@Nonnull
                                      org.bouncycastle.openpgp.PGPPublicKeyRing key,
                                      @Nonnull
                                      java.lang.CharSequence userId,
                                      @Nonnull
                                      EncryptionOptions.EncryptionKeySelector encryptionKeySelectionStrategy)
        Add a recipient by providing a key and recipient user-id, as well as a strategy for selecting one or multiple encryption capable subkeys from the key.
        Parameters:
        key - key
        userId - user-id
        encryptionKeySelectionStrategy - strategy to select one or more encryption subkeys to encrypt to
        Returns:
        this

      • addRecipient

        public EncryptionOptions addRecipient​(@Nonnull
                                      org.bouncycastle.openpgp.PGPPublicKeyRing key)
        Add a recipient by providing a key.
        Parameters:
        key - key ring
        Returns:
        this

      • addRecipient

        public EncryptionOptions addRecipient​(@Nonnull
                                      org.bouncycastle.openpgp.PGPPublicKeyRing key,
                                      @Nonnull
                                      EncryptionOptions.EncryptionKeySelector encryptionKeySelectionStrategy)
        Add a recipient by providing a key and an encryption key selection strategy.
        Parameters:
        key - key ring
        encryptionKeySelectionStrategy - strategy used to select one or multiple encryption subkeys.
        Returns:
        this

      • addHiddenRecipient

        public EncryptionOptions addHiddenRecipient​(@Nonnull
                                            org.bouncycastle.openpgp.PGPPublicKeyRing key)
        Add a certificate as hidden recipient. The recipients key-id will be obfuscated by setting a wildcard key ID.
        Parameters:
        key - recipient key
        Returns:
        this

      • addHiddenRecipient

        public EncryptionOptions addHiddenRecipient​(org.bouncycastle.openpgp.PGPPublicKeyRing key,
                                            EncryptionOptions.EncryptionKeySelector encryptionKeySelectionStrategy)
        Add a certificate as hidden recipient, using the provided EncryptionOptions.EncryptionKeySelector to select recipient subkeys. The recipients key-ids will be obfuscated by setting a wildcard key ID instead.
        Parameters:
        key - recipient key
        encryptionKeySelectionStrategy - strategy to select recipient (sub) keys.
        Returns:
        this

      • addPassphrase

        public EncryptionOptions addPassphrase​(@Nonnull
                                       Passphrase passphrase)
        Add a symmetric passphrase which the message will be encrypted to.
        Parameters:
        passphrase - passphrase
        Returns:
        this

      • addEncryptionMethod

        public EncryptionOptions addEncryptionMethod​(@Nonnull
                                             org.bouncycastle.openpgp.operator.PGPKeyEncryptionMethodGenerator encryptionMethod)
        Add an PGPKeyEncryptionMethodGenerator which will be used to encrypt the message. Method generators are either PBEKeyEncryptionMethodGenerator (passphrase) or PGPKeyEncryptionMethodGenerator (public key). This method is intended for advanced users to allow encryption for specific subkeys. This can come in handy for example if data needs to be encrypted to a subkey that's ignored by PGPainless.
        Parameters:
        encryptionMethod - encryption method
        Returns:
        this

      • overrideEncryptionAlgorithm

        public EncryptionOptions overrideEncryptionAlgorithm​(@Nonnull
                                                     SymmetricKeyAlgorithm encryptionAlgorithm)
        Override the used symmetric encryption algorithm. The symmetric encryption algorithm is used to encrypt the message itself, while the used symmetric key will be encrypted to all recipients using public key cryptography. If the algorithm is not overridden, a suitable algorithm will be negotiated.
        Parameters:
        encryptionAlgorithm - encryption algorithm override
        Returns:
        this

      • setAllowEncryptionWithMissingKeyFlags

        public EncryptionOptions setAllowEncryptionWithMissingKeyFlags()
        If this method is called, subsequent calls to addRecipient(PGPPublicKeyRing) will allow encryption for subkeys that do not carry any KeyFlag subpacket. This is a workaround for dealing with legacy keys that have no key flags subpacket but rely on the key algorithm type to convey the subkeys use.
        Returns:
        this

      • hasEncryptionMethod

        public boolean hasEncryptionMethod()
        Return 
        true
        iff the user specified at least one encryption method, 
        false
        otherwise.
        Returns:
        encryption methods is not empty

      • encryptToFirstSubkey

        public static EncryptionOptions.EncryptionKeySelector encryptToFirstSubkey()
        Only encrypt to the first valid encryption capable subkey we stumble upon.
        Returns:
        encryption key selector

      • encryptToAllCapableSubkeys

        public static EncryptionOptions.EncryptionKeySelector encryptToAllCapableSubkeys()
        Encrypt to any valid, encryption capable subkey on the key ring.
        Returns:
        encryption key selector