Package org.pgpainless.encryption_signing

# Class EncryptionOptions

java.lang.Object
org.pgpainless.encryption_signing.EncryptionOptions

public class EncryptionOptions extends 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 <alice@wonderland.lit>");
     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.

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static interface`
`EncryptionOptions.EncryptionKeySelector`

## Constructor Summary

Constructors
Constructor
Description
`EncryptionOptions()`
Encrypt to keys both carrying the key flag `KeyFlag.ENCRYPT_COMMS` or `KeyFlag.ENCRYPT_STORAGE`.
`EncryptionOptions(EncryptionPurpose purpose)`

## Method Summary

Modifier and Type
Method
Description
`EncryptionOptions`
`addAuthenticatableRecipients(String userId, boolean email, CertificateAuthority authority)`
Identify authenticatable certificates for the given user-ID by querying the `CertificateAuthority` for identifiable bindings.
`EncryptionOptions`
`addAuthenticatableRecipients(String userId, boolean email, CertificateAuthority authority, int targetAmount)`
Identify authenticatable certificates for the given user-ID by querying the `CertificateAuthority` for identifiable bindings.
`EncryptionOptions`
`addEncryptionMethod(org.bouncycastle.openpgp.operator.PGPKeyEncryptionMethodGenerator encryptionMethod)`
Add an `PGPKeyEncryptionMethodGenerator` which will be used to encrypt the message.
`EncryptionOptions`
`addHiddenRecipient(org.bouncycastle.openpgp.PGPPublicKeyRing key)`
Add a certificate as hidden recipient.
`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.
`EncryptionOptions`
`addPassphrase(Passphrase passphrase)`
Add a symmetric passphrase which the message will be encrypted to.
`EncryptionOptions`
`addRecipient(org.bouncycastle.openpgp.PGPPublicKeyRing key)`
Add a recipient by providing a key.
`EncryptionOptions`
`addRecipient(org.bouncycastle.openpgp.PGPPublicKeyRing key, CharSequence userId)`
Add a recipient by providing a key and recipient user-id.
`EncryptionOptions`
`addRecipient(org.bouncycastle.openpgp.PGPPublicKeyRing key, CharSequence userId, 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.
`EncryptionOptions`
`addRecipient(org.bouncycastle.openpgp.PGPPublicKeyRing key, EncryptionOptions.EncryptionKeySelector encryptionKeySelectionStrategy)`
Add a recipient by providing a key and an encryption key selection strategy.
`EncryptionOptions`
`addRecipients(Iterable<org.bouncycastle.openpgp.PGPPublicKeyRing> keys)`
Add all key rings in the provided `Iterable` (e.g.
`EncryptionOptions`
`addRecipients(Iterable<org.bouncycastle.openpgp.PGPPublicKeyRing> keys, EncryptionOptions.EncryptionKeySelector selector)`
Add all key rings in the provided `Iterable` (e.g.
`static EncryptionOptions`
`encryptCommunications()`
Factory method to create an `EncryptionOptions` object which will encrypt for keys which carry the flag `KeyFlag.ENCRYPT_COMMS`.
`static EncryptionOptions`
`encryptDataAtRest()`
Factory method to create an `EncryptionOptions` object which will encrypt for keys which carry the flag `KeyFlag.ENCRYPT_STORAGE`.
`static EncryptionOptions.EncryptionKeySelector`
`encryptToAllCapableSubkeys()`
Encrypt to any valid, encryption capable subkey on the key ring.
`static EncryptionOptions.EncryptionKeySelector`
`encryptToFirstSubkey()`
Only encrypt to the first valid encryption capable subkey we stumble upon.
`static EncryptionOptions`
`get()`
Factory method to create an `EncryptionOptions` object which will encrypt for keys which carry either the `KeyFlag.ENCRYPT_COMMS` or `KeyFlag.ENCRYPT_STORAGE` flag.
`boolean`
`hasEncryptionMethod()`
Return
`EncryptionOptions`
`overrideEncryptionAlgorithm(SymmetricKeyAlgorithm encryptionAlgorithm)`
Override the used symmetric encryption algorithm.
`EncryptionOptions`
`setAllowEncryptionWithMissingKeyFlags()`
If this method is called, subsequent calls to `addRecipient(PGPPublicKeyRing)` will allow encryption for subkeys that do not carry any `KeyFlag` subpacket.
`EncryptionOptions`
`setEvaluationDate(Date evaluationDate)`
Override the evaluation date for recipient keys with the given date.

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

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

## Constructor Details

### EncryptionOptions

public EncryptionOptions()
Encrypt to keys both carrying the key flag `KeyFlag.ENCRYPT_COMMS` or `KeyFlag.ENCRYPT_STORAGE`.

### EncryptionOptions

public EncryptionOptions(@Nonnull EncryptionPurpose purpose)

## Method Details

### get

public static EncryptionOptions get()
Factory method to create an `EncryptionOptions` object which will encrypt for keys which carry either the `KeyFlag.ENCRYPT_COMMS` or `KeyFlag.ENCRYPT_STORAGE` flag.

Use this if you are not sure.

Returns:
  encryption options

### setEvaluationDate

public EncryptionOptions setEvaluationDate(@Nonnull Date evaluationDate)
Override the evaluation date for recipient keys with the given date.

Parameters:
  `evaluationDate` - new evaluation date
Returns:
  this

### encryptCommunications

public static EncryptionOptions encryptCommunications()
Factory method to create an `EncryptionOptions` object which will encrypt for keys which carry the flag `KeyFlag.ENCRYPT_COMMS`.

Returns:
  encryption options

### encryptDataAtRest

public static EncryptionOptions encryptDataAtRest()
Factory method to create an `EncryptionOptions` object which will encrypt for keys which carry the flag `KeyFlag.ENCRYPT_STORAGE`.

Returns:
  encryption options

### addAuthenticatableRecipients

public EncryptionOptions addAuthenticatableRecipients(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(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 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 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 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 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