#1035

pending completion

Build # #1035

Build Type

push

github-actions

Committed by

vanitasvitae

Commit Message

Add method to allow for encryption for keys with missing keyflags.

There are legacy keys around, which do not carry any key flags.
This commit adds a method to EncryptionOptions that allow PGPainless to encrypt
for such keys.

Fixes #400

Run Details

13 of 13 new or added lines in 2 files covered. (100.0%)

7082 of 7948 relevant lines covered (89.1%)

0.89 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

86.24

/pgpainless-core/src/main/java/org/pgpainless/encryption_signing/EncryptionOptions.java

// SPDX-FileCopyrightText: 2021 Paul Schaub <vanitasvitae@fsfe.org>
//
// SPDX-License-Identifier: Apache-2.0

package org.pgpainless.encryption_signing;

import java.util.Collections;
import java.util.Date;
import java.util.HashMap;
import java.util.HashSet;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Map;
import java.util.NoSuchElementException;
import java.util.Set;
import javax.annotation.Nonnull;

import org.bouncycastle.openpgp.PGPPublicKey;
import org.bouncycastle.openpgp.PGPPublicKeyRing;
import org.bouncycastle.openpgp.PGPPublicKeyRingCollection;
import org.bouncycastle.openpgp.operator.PBEKeyEncryptionMethodGenerator;
import org.bouncycastle.openpgp.operator.PGPKeyEncryptionMethodGenerator;
import org.bouncycastle.openpgp.operator.PublicKeyKeyEncryptionMethodGenerator;
import org.pgpainless.algorithm.EncryptionPurpose;
import org.pgpainless.algorithm.SymmetricKeyAlgorithm;
import org.pgpainless.authentication.CertificateAuthenticity;
import org.pgpainless.authentication.CertificateAuthority;
import org.pgpainless.exception.KeyException;
import org.pgpainless.implementation.ImplementationFactory;
import org.pgpainless.key.OpenPgpFingerprint;
import org.pgpainless.key.SubkeyIdentifier;
import org.pgpainless.key.info.KeyAccessor;
import org.pgpainless.key.info.KeyRingInfo;
import org.pgpainless.util.Passphrase;

/**
 * Options for the encryption process.
 * This class can be used to set encryption parameters, like encryption keys and passphrases, algorithms etc.
 * <p>
 * A typical use might look like follows:
 * <pre>
 * {@code
 * EncryptionOptions opt = new EncryptionOptions();
 * opt.addRecipient(aliceKey, "Alice <alice@wonderland.lit>");
 * opt.addPassphrase(Passphrase.fromPassword("AdditionalDecryptionPassphrase123"));
 * }
 * </pre>
 *<p>
 * To use a custom symmetric encryption algorithm, use {@link #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.
 * <p>
 * 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
 * <pre>
 * {@code
 * opt.addRecipient(aliceKey, EncryptionOptions.encryptToFirstSubkey());
 * }
 * </pre>
 * when adding the recipient key.
 */
public class EncryptionOptions {

    private final EncryptionPurpose purpose;
    private final Set<PGPKeyEncryptionMethodGenerator> encryptionMethods = new LinkedHashSet<>();
    private final Set<SubkeyIdentifier> encryptionKeys = new LinkedHashSet<>();
    private final Map<SubkeyIdentifier, KeyRingInfo> keyRingInfo = new HashMap<>();
    private final Map<SubkeyIdentifier, KeyAccessor> keyViews = new HashMap<>();
    private final EncryptionKeySelector encryptionKeySelector = encryptToAllCapableSubkeys();
    private boolean allowEncryptionWithMissingKeyFlags = false;

    private SymmetricKeyAlgorithm encryptionAlgorithmOverride = null;

    /**
     * Encrypt to keys both carrying the key flag {@link org.pgpainless.algorithm.KeyFlag#ENCRYPT_COMMS}
     * or {@link org.pgpainless.algorithm.KeyFlag#ENCRYPT_STORAGE}.
     */
    public EncryptionOptions() {
        this(EncryptionPurpose.ANY);
    }

    public EncryptionOptions(@Nonnull EncryptionPurpose purpose) {
        this.purpose = purpose;
    }

    /**
     * Factory method to create an {@link EncryptionOptions} object which will encrypt for keys
     * which carry either the {@link org.pgpainless.algorithm.KeyFlag#ENCRYPT_COMMS} or
     * {@link org.pgpainless.algorithm.KeyFlag#ENCRYPT_STORAGE} flag.
     * <p>
     * Use this if you are not sure.
     *
     * @return encryption options
     */
    public static EncryptionOptions get() {
        return new EncryptionOptions();
    }

    /**
     * Factory method to create an {@link EncryptionOptions} object which will encrypt for keys
     * which carry the flag {@link org.pgpainless.algorithm.KeyFlag#ENCRYPT_COMMS}.
     *
     * @return encryption options
     */
    public static EncryptionOptions encryptCommunications() {
        return new EncryptionOptions(EncryptionPurpose.COMMUNICATIONS);
    }

    /**
     * Factory method to create an {@link EncryptionOptions} object which will encrypt for keys
     * which carry the flag {@link org.pgpainless.algorithm.KeyFlag#ENCRYPT_STORAGE}.
     *
     * @return encryption options
     */
    public static EncryptionOptions encryptDataAtRest() {
        return new EncryptionOptions(EncryptionPurpose.STORAGE);
    }

    /**
     * Identify authenticatable certificates for the given user-ID by querying the {@link CertificateAuthority} for
     * identifiable bindings.
     * Add all acceptable bindings, whose trust amount is larger or equal to the target amount to the list of recipients.
     * @param userId userId
     * @param email if true, treat the user-ID as an email address and match all user-IDs containing the mail address
     * @param authority certificate authority
     * @return encryption options
     */
    public EncryptionOptions addAuthenticatableRecipients(String userId, boolean email, CertificateAuthority authority) {
        return addAuthenticatableRecipients(userId, email, authority, 120);
    }

    /**
     * Identify authenticatable certificates for the given user-ID by querying the {@link CertificateAuthority} for
     * identifiable bindings.
     * Add all acceptable bindings, whose trust amount is larger or equal to the target amount to the list of recipients.
     * @param userId userId
     * @param email if true, treat the user-ID as an email address and match all user-IDs containing the mail address
     * @param authority certificate authority
     * @param targetAmount target amount (120 = fully authenticated, 240 = doubly authenticated,
     *                    60 = partially authenticated...)
     * @return encryption options
     */
    public EncryptionOptions addAuthenticatableRecipients(String userId, boolean email, CertificateAuthority authority, int targetAmount) {
        List<CertificateAuthenticity> identifiedCertificates = authority.lookupByUserId(userId, email, new Date(), targetAmount);
        boolean foundAcceptable = false;
        for (CertificateAuthenticity candidate : identifiedCertificates) {
            if (candidate.isAuthenticated()) {
                addRecipient(candidate.getCertificate());
                foundAcceptable = true;
            }
        }
        if (!foundAcceptable) {
            throw new IllegalArgumentException("Could not identify any trust-worthy certificates for '" + userId + "' and target trust amount " + targetAmount);
        }
        return this;
    }

    /**
     * Add all key rings in the provided {@link Iterable} (e.g. {@link PGPPublicKeyRingCollection}) as recipients.
     *
     * @param keys keys
     * @return this
     */
    public EncryptionOptions addRecipients(@Nonnull Iterable<PGPPublicKeyRing> keys) {
        if (!keys.iterator().hasNext()) {
            throw new IllegalArgumentException("Set of recipient keys cannot be empty.");
        }
        for (PGPPublicKeyRing key : keys) {
            addRecipient(key);
        }
        return this;
    }

    /**
     * Add all key rings in the provided {@link Iterable} (e.g. {@link PGPPublicKeyRingCollection}) as recipients.
     * Per key ring, the selector is applied to select one or more encryption subkeys.
     *
     * @param keys keys
     * @param selector encryption key selector
     * @return this
     */
    public EncryptionOptions addRecipients(@Nonnull Iterable<PGPPublicKeyRing> keys, @Nonnull EncryptionKeySelector selector) {
        if (!keys.iterator().hasNext()) {
            throw new IllegalArgumentException("Set of recipient keys cannot be empty.");
        }
        for (PGPPublicKeyRing key : keys) {
            addRecipient(key, selector);
        }
        return this;
    }

    /**
     * Add a recipient by providing a key and recipient user-id.
     * The user-id is used to determine the recipients preferences (algorithms etc.).
     *
     * @param key key ring
     * @param userId user id
     * @return this
     */
    public EncryptionOptions addRecipient(@Nonnull PGPPublicKeyRing key, @Nonnull CharSequence userId) {
        return addRecipient(key, userId, encryptionKeySelector);
    }

    /**
     * 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.
     *
     * @param key key
     * @param userId user-id
     * @param encryptionKeySelectionStrategy strategy to select one or more encryption subkeys to encrypt to
     * @return this
     */
    public EncryptionOptions addRecipient(@Nonnull PGPPublicKeyRing key,
                                          @Nonnull CharSequence userId,
                                          @Nonnull EncryptionKeySelector encryptionKeySelectionStrategy) {
        KeyRingInfo info = new KeyRingInfo(key, new Date());

        List<PGPPublicKey> encryptionSubkeys = encryptionKeySelectionStrategy
                .selectEncryptionSubkeys(info.getEncryptionSubkeys(userId.toString(), purpose));
        if (encryptionSubkeys.isEmpty()) {
            throw new KeyException.UnacceptableEncryptionKeyException(OpenPgpFingerprint.of(key));
        }

        for (PGPPublicKey encryptionSubkey : encryptionSubkeys) {
            SubkeyIdentifier keyId = new SubkeyIdentifier(key, encryptionSubkey.getKeyID());
            keyRingInfo.put(keyId, info);
            keyViews.put(keyId, new KeyAccessor.ViaUserId(info, keyId, userId.toString()));
            addRecipientKey(key, encryptionSubkey, false);
        }

        return this;
    }

    /**
     * Add a recipient by providing a key.
     *
     * @param key key ring
     * @return this
     */
    public EncryptionOptions addRecipient(@Nonnull PGPPublicKeyRing key) {
        return addRecipient(key, encryptionKeySelector);
    }

    /**
     * Add a recipient by providing a key and an encryption key selection strategy.
     *
     * @param key key ring
     * @param encryptionKeySelectionStrategy strategy used to select one or multiple encryption subkeys.
     * @return this
     */
    public EncryptionOptions addRecipient(@Nonnull PGPPublicKeyRing key,
                                          @Nonnull EncryptionKeySelector encryptionKeySelectionStrategy) {
        return addAsRecipient(key, encryptionKeySelectionStrategy, false);
    }

    /**
     * Add a certificate as hidden recipient.
     * The recipients key-id will be obfuscated by setting a wildcard key ID.
     *
     * @param key recipient key
     * @return this
     */
    public EncryptionOptions addHiddenRecipient(@Nonnull PGPPublicKeyRing key) {
        return addHiddenRecipient(key, encryptionKeySelector);
    }

    /**
     * Add a certificate as hidden recipient, using the provided {@link EncryptionKeySelector} to select recipient subkeys.
     * The recipients key-ids will be obfuscated by setting a wildcard key ID instead.
     *
     * @param key recipient key
     * @param encryptionKeySelectionStrategy strategy to select recipient (sub) keys.
     * @return this
     */
    public EncryptionOptions addHiddenRecipient(PGPPublicKeyRing key, EncryptionKeySelector encryptionKeySelectionStrategy) {
        return addAsRecipient(key, encryptionKeySelectionStrategy, true);
    }

    private EncryptionOptions addAsRecipient(PGPPublicKeyRing key, EncryptionKeySelector encryptionKeySelectionStrategy, boolean wildcardKeyId) {
        Date evaluationDate = new Date();
        KeyRingInfo info = new KeyRingInfo(key, evaluationDate);

        Date primaryKeyExpiration;
        try {
            primaryKeyExpiration = info.getPrimaryKeyExpirationDate();
        } catch (NoSuchElementException e) {
            throw new KeyException.UnacceptableSelfSignatureException(OpenPgpFingerprint.of(key));
        }
        if (primaryKeyExpiration != null && primaryKeyExpiration.before(evaluationDate)) {
            throw new KeyException.ExpiredKeyException(OpenPgpFingerprint.of(key), primaryKeyExpiration);
        }

        List<PGPPublicKey> encryptionSubkeys = encryptionKeySelectionStrategy
                .selectEncryptionSubkeys(info.getEncryptionSubkeys(purpose));

        // There are some legacy keys around without key flags.
        // If we allow encryption for those keys, we add valid keys without any key flags, if they are
        // capable of encryption by means of their algorithm
        if (encryptionSubkeys.isEmpty() && allowEncryptionWithMissingKeyFlags) {
            List<PGPPublicKey> validSubkeys = info.getValidSubkeys();
            for (PGPPublicKey validSubkey : validSubkeys) {
                if (!validSubkey.isEncryptionKey()) {
                    continue;
                }
                // only add encryption keys with no key flags.
                if (info.getKeyFlagsOf(validSubkey.getKeyID()).isEmpty()) {
                    encryptionSubkeys.add(validSubkey);
                }
            }
        }

        if (encryptionSubkeys.isEmpty()) {
            throw new KeyException.UnacceptableEncryptionKeyException(OpenPgpFingerprint.of(key));
        }

        for (PGPPublicKey encryptionSubkey : encryptionSubkeys) {
            SubkeyIdentifier keyId = new SubkeyIdentifier(key, encryptionSubkey.getKeyID());
            keyRingInfo.put(keyId, info);
            keyViews.put(keyId, new KeyAccessor.ViaKeyId(info, keyId));
            addRecipientKey(key, encryptionSubkey, wildcardKeyId);
        }

        return this;
    }

    private void addRecipientKey(@Nonnull PGPPublicKeyRing keyRing,
                                 @Nonnull PGPPublicKey key,
                                 boolean wildcardKeyId) {
        encryptionKeys.add(new SubkeyIdentifier(keyRing, key.getKeyID()));
        PublicKeyKeyEncryptionMethodGenerator encryptionMethod = ImplementationFactory
                .getInstance().getPublicKeyKeyEncryptionMethodGenerator(key);
        encryptionMethod.setUseWildcardKeyID(wildcardKeyId);
        addEncryptionMethod(encryptionMethod);
    }

    /**
     * Add a symmetric passphrase which the message will be encrypted to.
     *
     * @param passphrase passphrase
     * @return this
     */
    public EncryptionOptions addPassphrase(@Nonnull Passphrase passphrase) {
        if (passphrase.isEmpty()) {
            throw new IllegalArgumentException("Passphrase must not be empty.");
        }
        PBEKeyEncryptionMethodGenerator encryptionMethod = ImplementationFactory
                .getInstance().getPBEKeyEncryptionMethodGenerator(passphrase);
        return addEncryptionMethod(encryptionMethod);
    }

    /**
     * Add an {@link PGPKeyEncryptionMethodGenerator} which will be used to encrypt the message.
     * Method generators are either {@link PBEKeyEncryptionMethodGenerator} (passphrase)
     * or {@link 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.
     *
     * @param encryptionMethod encryption method
     * @return this
     */
    public EncryptionOptions addEncryptionMethod(@Nonnull PGPKeyEncryptionMethodGenerator encryptionMethod) {
        encryptionMethods.add(encryptionMethod);
        return this;
    }

    Set<PGPKeyEncryptionMethodGenerator> getEncryptionMethods() {
        return new HashSet<>(encryptionMethods);
    }

    Map<SubkeyIdentifier, KeyRingInfo> getKeyRingInfo() {
        return new HashMap<>(keyRingInfo);
    }

    Set<SubkeyIdentifier> getEncryptionKeyIdentifiers() {
        return new HashSet<>(encryptionKeys);
    }

    Map<SubkeyIdentifier, KeyAccessor> getKeyViews() {
        return new HashMap<>(keyViews);
    }

    SymmetricKeyAlgorithm getEncryptionAlgorithmOverride() {
        return encryptionAlgorithmOverride;
    }

    /**
     * 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.
     *
     * @param encryptionAlgorithm encryption algorithm override
     * @return this
     */
    public EncryptionOptions overrideEncryptionAlgorithm(@Nonnull SymmetricKeyAlgorithm encryptionAlgorithm) {
        if (encryptionAlgorithm == SymmetricKeyAlgorithm.NULL) {
            throw new IllegalArgumentException("Plaintext encryption can only be used to denote unencrypted secret keys.");
        }
        this.encryptionAlgorithmOverride = encryptionAlgorithm;
        return this;
    }

    /**
     * If this method is called, subsequent calls to {@link #addRecipient(PGPPublicKeyRing)} will allow encryption
     * for subkeys that do not carry any {@link org.pgpainless.algorithm.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.
     *
     * @return this
     */
    public EncryptionOptions setAllowEncryptionWithMissingKeyFlags() {
        this.allowEncryptionWithMissingKeyFlags = true;
        return this;
    }

    /**
     * Return <pre>true</pre> iff the user specified at least one encryption method,
     * <pre>false</pre> otherwise.
     *
     * @return encryption methods is not empty
     */
    public boolean hasEncryptionMethod() {
        return !encryptionMethods.isEmpty();
    }

    public interface EncryptionKeySelector {
        List<PGPPublicKey> selectEncryptionSubkeys(@Nonnull List<PGPPublicKey> encryptionCapableKeys);
    }

    /**
     * Only encrypt to the first valid encryption capable subkey we stumble upon.
     *
     * @return encryption key selector
     */
    public static EncryptionKeySelector encryptToFirstSubkey() {
        return new EncryptionKeySelector() {
            @Override
            public List<PGPPublicKey> selectEncryptionSubkeys(@Nonnull List<PGPPublicKey> encryptionCapableKeys) {
                return encryptionCapableKeys.isEmpty() ? Collections.emptyList() : Collections.singletonList(encryptionCapableKeys.get(0));
            }
        };
    }

    /**
     * Encrypt to any valid, encryption capable subkey on the key ring.
     *
     * @return encryption key selector
     */
    public static EncryptionKeySelector encryptToAllCapableSubkeys() {
        return new EncryptionKeySelector() {
            @Override
            public List<PGPPublicKey> selectEncryptionSubkeys(@Nonnull List<PGPPublicKey> encryptionCapableKeys) {
                return encryptionCapableKeys;
            }
        };
    }

    // TODO: Create encryptToBestSubkey() method
}

1	// SPDX-FileCopyrightText: 2021 Paul Schaub <vanitasvitae@fsfe.org>
2	//
3	// SPDX-License-Identifier: Apache-2.0
4
5	package org.pgpainless.encryption_signing;
6
7	import java.util.Collections;
8	import java.util.Date;
9	import java.util.HashMap;
10	import java.util.HashSet;
11	import java.util.LinkedHashSet;
12	import java.util.List;
13	import java.util.Map;
14	import java.util.NoSuchElementException;
15	import java.util.Set;
16	import javax.annotation.Nonnull;
17
18	import org.bouncycastle.openpgp.PGPPublicKey;
19	import org.bouncycastle.openpgp.PGPPublicKeyRing;
20	import org.bouncycastle.openpgp.PGPPublicKeyRingCollection;
21	import org.bouncycastle.openpgp.operator.PBEKeyEncryptionMethodGenerator;
22	import org.bouncycastle.openpgp.operator.PGPKeyEncryptionMethodGenerator;
23	import org.bouncycastle.openpgp.operator.PublicKeyKeyEncryptionMethodGenerator;
24	import org.pgpainless.algorithm.EncryptionPurpose;
25	import org.pgpainless.algorithm.SymmetricKeyAlgorithm;
26	import org.pgpainless.authentication.CertificateAuthenticity;
27	import org.pgpainless.authentication.CertificateAuthority;
28	import org.pgpainless.exception.KeyException;
29	import org.pgpainless.implementation.ImplementationFactory;
30	import org.pgpainless.key.OpenPgpFingerprint;
31	import org.pgpainless.key.SubkeyIdentifier;
32	import org.pgpainless.key.info.KeyAccessor;
33	import org.pgpainless.key.info.KeyRingInfo;
34	import org.pgpainless.util.Passphrase;
35
36	/**
37	* Options for the encryption process.
38	* This class can be used to set encryption parameters, like encryption keys and passphrases, algorithms etc.
39	* <p>
40	* A typical use might look like follows:
41	* <pre>
42	* {@code
43	* EncryptionOptions opt = new EncryptionOptions();
44	* opt.addRecipient(aliceKey, "Alice <alice@wonderland.lit>");
45	* opt.addPassphrase(Passphrase.fromPassword("AdditionalDecryptionPassphrase123"));
46	* }
47	* </pre>
48	*<p>
49	* To use a custom symmetric encryption algorithm, use {@link #overrideEncryptionAlgorithm(SymmetricKeyAlgorithm)}.
50	* This will cause PGPainless to use the provided algorithm for message encryption, instead of negotiating an algorithm
51	* by inspecting the provided recipient keys.
52	* <p>
53	* By default, PGPainless will encrypt to all suitable, encryption capable subkeys on each recipient's certificate.
54	* This behavior can be changed per recipient, e.g. by calling
55	* <pre>
56	* {@code
57	* opt.addRecipient(aliceKey, EncryptionOptions.encryptToFirstSubkey());
58	* }
59	* </pre>
60	* when adding the recipient key.
61	*/
62	public class EncryptionOptions {
63
64	private final EncryptionPurpose purpose;
65	private final Set<PGPKeyEncryptionMethodGenerator> encryptionMethods = new LinkedHashSet<>();	1✔
66	private final Set<SubkeyIdentifier> encryptionKeys = new LinkedHashSet<>();	1✔
67	private final Map<SubkeyIdentifier, KeyRingInfo> keyRingInfo = new HashMap<>();	1✔
68	private final Map<SubkeyIdentifier, KeyAccessor> keyViews = new HashMap<>();	1✔
69	private final EncryptionKeySelector encryptionKeySelector = encryptToAllCapableSubkeys();	1✔
70	private boolean allowEncryptionWithMissingKeyFlags = false;	1✔
71
72	private SymmetricKeyAlgorithm encryptionAlgorithmOverride = null;	1✔
73
74	/**
75	* Encrypt to keys both carrying the key flag {@link org.pgpainless.algorithm.KeyFlag#ENCRYPT_COMMS}
76	* or {@link org.pgpainless.algorithm.KeyFlag#ENCRYPT_STORAGE}.
77	*/
78	public EncryptionOptions() {
79	this(EncryptionPurpose.ANY);	1✔
80	}	1✔
81
82	public EncryptionOptions(@Nonnull EncryptionPurpose purpose) {	1✔
83	this.purpose = purpose;	1✔
84	}	1✔
85
86	/**
87	* Factory method to create an {@link EncryptionOptions} object which will encrypt for keys
88	* which carry either the {@link org.pgpainless.algorithm.KeyFlag#ENCRYPT_COMMS} or
89	* {@link org.pgpainless.algorithm.KeyFlag#ENCRYPT_STORAGE} flag.
90	* <p>
91	* Use this if you are not sure.
92	*
93	* @return encryption options
94	*/
95	public static EncryptionOptions get() {
96	return new EncryptionOptions();	1✔
97	}
98
99	/**
100	* Factory method to create an {@link EncryptionOptions} object which will encrypt for keys
101	* which carry the flag {@link org.pgpainless.algorithm.KeyFlag#ENCRYPT_COMMS}.
102	*
103	* @return encryption options
104	*/
105	public static EncryptionOptions encryptCommunications() {
106	return new EncryptionOptions(EncryptionPurpose.COMMUNICATIONS);	1✔
107	}
108
109	/**
110	* Factory method to create an {@link EncryptionOptions} object which will encrypt for keys
111	* which carry the flag {@link org.pgpainless.algorithm.KeyFlag#ENCRYPT_STORAGE}.
112	*
113	* @return encryption options
114	*/
115	public static EncryptionOptions encryptDataAtRest() {
116	return new EncryptionOptions(EncryptionPurpose.STORAGE);	1✔
117	}
118
119	/**
120	* Identify authenticatable certificates for the given user-ID by querying the {@link CertificateAuthority} for
121	* identifiable bindings.
122	* Add all acceptable bindings, whose trust amount is larger or equal to the target amount to the list of recipients.
123	* @param userId userId
124	* @param email if true, treat the user-ID as an email address and match all user-IDs containing the mail address
125	* @param authority certificate authority
126	* @return encryption options
127	*/
128	public EncryptionOptions addAuthenticatableRecipients(String userId, boolean email, CertificateAuthority authority) {
129	return addAuthenticatableRecipients(userId, email, authority, 120);	×
130	}
131
132	/**
133	* Identify authenticatable certificates for the given user-ID by querying the {@link CertificateAuthority} for
134	* identifiable bindings.
135	* Add all acceptable bindings, whose trust amount is larger or equal to the target amount to the list of recipients.
136	* @param userId userId
137	* @param email if true, treat the user-ID as an email address and match all user-IDs containing the mail address
138	* @param authority certificate authority
139	* @param targetAmount target amount (120 = fully authenticated, 240 = doubly authenticated,
140	* 60 = partially authenticated...)
141	* @return encryption options
142	*/
143	public EncryptionOptions addAuthenticatableRecipients(String userId, boolean email, CertificateAuthority authority, int targetAmount) {
144	List<CertificateAuthenticity> identifiedCertificates = authority.lookupByUserId(userId, email, new Date(), targetAmount);	×
145	boolean foundAcceptable = false;	×
146	for (CertificateAuthenticity candidate : identifiedCertificates) {	×
147	if (candidate.isAuthenticated()) {	×
148	addRecipient(candidate.getCertificate());	×
149	foundAcceptable = true;	×
150	}
151	}	×
152	if (!foundAcceptable) {	×
153	throw new IllegalArgumentException("Could not identify any trust-worthy certificates for '" + userId + "' and target trust amount " + targetAmount);	×
154	}
155	return this;	×
156	}
157
158	/**
159	* Add all key rings in the provided {@link Iterable} (e.g. {@link PGPPublicKeyRingCollection}) as recipients.
160	*
161	* @param keys keys
162	* @return this
163	*/
164	public EncryptionOptions addRecipients(@Nonnull Iterable<PGPPublicKeyRing> keys) {
165	if (!keys.iterator().hasNext()) {	1✔
166	throw new IllegalArgumentException("Set of recipient keys cannot be empty.");	1✔
167	}
168	for (PGPPublicKeyRing key : keys) {	1✔
169	addRecipient(key);	1✔
170	}	1✔
171	return this;	1✔
172	}
173
174	/**
175	* Add all key rings in the provided {@link Iterable} (e.g. {@link PGPPublicKeyRingCollection}) as recipients.
176	* Per key ring, the selector is applied to select one or more encryption subkeys.
177	*
178	* @param keys keys
179	* @param selector encryption key selector
180	* @return this
181	*/
182	public EncryptionOptions addRecipients(@Nonnull Iterable<PGPPublicKeyRing> keys, @Nonnull EncryptionKeySelector selector) {
183	if (!keys.iterator().hasNext()) {	1✔
184	throw new IllegalArgumentException("Set of recipient keys cannot be empty.");	1✔
185	}
186	for (PGPPublicKeyRing key : keys) {	1✔
187	addRecipient(key, selector);	1✔
188	}	1✔
189	return this;	1✔
190	}
191
192	/**
193	* Add a recipient by providing a key and recipient user-id.
194	* The user-id is used to determine the recipients preferences (algorithms etc.).
195	*
196	* @param key key ring
197	* @param userId user id
198	* @return this
199	*/
200	public EncryptionOptions addRecipient(@Nonnull PGPPublicKeyRing key, @Nonnull CharSequence userId) {
201	return addRecipient(key, userId, encryptionKeySelector);	1✔
202	}
203
204	/**
205	* Add a recipient by providing a key and recipient user-id, as well as a strategy for selecting one or multiple
206	* encryption capable subkeys from the key.
207	*
208	* @param key key
209	* @param userId user-id
210	* @param encryptionKeySelectionStrategy strategy to select one or more encryption subkeys to encrypt to
211	* @return this
212	*/
213	public EncryptionOptions addRecipient(@Nonnull PGPPublicKeyRing key,
214	@Nonnull CharSequence userId,
215	@Nonnull EncryptionKeySelector encryptionKeySelectionStrategy) {
216	KeyRingInfo info = new KeyRingInfo(key, new Date());	1✔
217
218	List<PGPPublicKey> encryptionSubkeys = encryptionKeySelectionStrategy	1✔
219	.selectEncryptionSubkeys(info.getEncryptionSubkeys(userId.toString(), purpose));	1✔
220	if (encryptionSubkeys.isEmpty()) {	1✔
221	throw new KeyException.UnacceptableEncryptionKeyException(OpenPgpFingerprint.of(key));	1✔
222	}
223
224	for (PGPPublicKey encryptionSubkey : encryptionSubkeys) {	1✔
225	SubkeyIdentifier keyId = new SubkeyIdentifier(key, encryptionSubkey.getKeyID());	1✔
226	keyRingInfo.put(keyId, info);	1✔
227	keyViews.put(keyId, new KeyAccessor.ViaUserId(info, keyId, userId.toString()));	1✔
228	addRecipientKey(key, encryptionSubkey, false);	1✔
229	}	1✔
230
231	return this;	1✔
232	}
233
234	/**
235	* Add a recipient by providing a key.
236	*
237	* @param key key ring
238	* @return this
239	*/
240	public EncryptionOptions addRecipient(@Nonnull PGPPublicKeyRing key) {
241	return addRecipient(key, encryptionKeySelector);	1✔
242	}
243
244	/**
245	* Add a recipient by providing a key and an encryption key selection strategy.
246	*
247	* @param key key ring
248	* @param encryptionKeySelectionStrategy strategy used to select one or multiple encryption subkeys.
249	* @return this
250	*/
251	public EncryptionOptions addRecipient(@Nonnull PGPPublicKeyRing key,
252	@Nonnull EncryptionKeySelector encryptionKeySelectionStrategy) {
253	return addAsRecipient(key, encryptionKeySelectionStrategy, false);	1✔
254	}
255
256	/**
257	* Add a certificate as hidden recipient.
258	* The recipients key-id will be obfuscated by setting a wildcard key ID.
259	*
260	* @param key recipient key
261	* @return this
262	*/
263	public EncryptionOptions addHiddenRecipient(@Nonnull PGPPublicKeyRing key) {
264	return addHiddenRecipient(key, encryptionKeySelector);	1✔
265	}
266
267	/**
268	* Add a certificate as hidden recipient, using the provided {@link EncryptionKeySelector} to select recipient subkeys.
269	* The recipients key-ids will be obfuscated by setting a wildcard key ID instead.
270	*
271	* @param key recipient key
272	* @param encryptionKeySelectionStrategy strategy to select recipient (sub) keys.
273	* @return this
274	*/
275	public EncryptionOptions addHiddenRecipient(PGPPublicKeyRing key, EncryptionKeySelector encryptionKeySelectionStrategy) {
276	return addAsRecipient(key, encryptionKeySelectionStrategy, true);	1✔
277	}
278
279	private EncryptionOptions addAsRecipient(PGPPublicKeyRing key, EncryptionKeySelector encryptionKeySelectionStrategy, boolean wildcardKeyId) {
280	Date evaluationDate = new Date();	1✔
281	KeyRingInfo info = new KeyRingInfo(key, evaluationDate);	1✔
282
283	Date primaryKeyExpiration;
284	try {
285	primaryKeyExpiration = info.getPrimaryKeyExpirationDate();	1✔
286	} catch (NoSuchElementException e) {	×
287	throw new KeyException.UnacceptableSelfSignatureException(OpenPgpFingerprint.of(key));	×
288	}	1✔
289	if (primaryKeyExpiration != null && primaryKeyExpiration.before(evaluationDate)) {	1✔
290	throw new KeyException.ExpiredKeyException(OpenPgpFingerprint.of(key), primaryKeyExpiration);	1✔
291	}
292
293	List<PGPPublicKey> encryptionSubkeys = encryptionKeySelectionStrategy	1✔
294	.selectEncryptionSubkeys(info.getEncryptionSubkeys(purpose));	1✔
295
296	// There are some legacy keys around without key flags.
297	// If we allow encryption for those keys, we add valid keys without any key flags, if they are
298	// capable of encryption by means of their algorithm
299	if (encryptionSubkeys.isEmpty() && allowEncryptionWithMissingKeyFlags) {	1✔
300	List<PGPPublicKey> validSubkeys = info.getValidSubkeys();	1✔
301	for (PGPPublicKey validSubkey : validSubkeys) {	1✔
302	if (!validSubkey.isEncryptionKey()) {	1✔
303	continue;	×
304	}
305	// only add encryption keys with no key flags.
306	if (info.getKeyFlagsOf(validSubkey.getKeyID()).isEmpty()) {	1✔
307	encryptionSubkeys.add(validSubkey);	1✔
308	}
309	}	1✔
310	}
311
312	if (encryptionSubkeys.isEmpty()) {	1✔
313	throw new KeyException.UnacceptableEncryptionKeyException(OpenPgpFingerprint.of(key));	1✔
314	}
315
316	for (PGPPublicKey encryptionSubkey : encryptionSubkeys) {	1✔
317	SubkeyIdentifier keyId = new SubkeyIdentifier(key, encryptionSubkey.getKeyID());	1✔
318	keyRingInfo.put(keyId, info);	1✔
319	keyViews.put(keyId, new KeyAccessor.ViaKeyId(info, keyId));	1✔
320	addRecipientKey(key, encryptionSubkey, wildcardKeyId);	1✔
321	}	1✔
322
323	return this;	1✔
324	}
325
326	private void addRecipientKey(@Nonnull PGPPublicKeyRing keyRing,
327	@Nonnull PGPPublicKey key,
328	boolean wildcardKeyId) {
329	encryptionKeys.add(new SubkeyIdentifier(keyRing, key.getKeyID()));	1✔
330	PublicKeyKeyEncryptionMethodGenerator encryptionMethod = ImplementationFactory
331	.getInstance().getPublicKeyKeyEncryptionMethodGenerator(key);	1✔
332	encryptionMethod.setUseWildcardKeyID(wildcardKeyId);	1✔
333	addEncryptionMethod(encryptionMethod);	1✔
334	}	1✔
335
336	/**
337	* Add a symmetric passphrase which the message will be encrypted to.
338	*
339	* @param passphrase passphrase
340	* @return this
341	*/
342	public EncryptionOptions addPassphrase(@Nonnull Passphrase passphrase) {
343	if (passphrase.isEmpty()) {	1✔
344	throw new IllegalArgumentException("Passphrase must not be empty.");	1✔
345	}
346	PBEKeyEncryptionMethodGenerator encryptionMethod = ImplementationFactory
347	.getInstance().getPBEKeyEncryptionMethodGenerator(passphrase);	1✔
348	return addEncryptionMethod(encryptionMethod);	1✔
349	}
350
351	/**
352	* Add an {@link PGPKeyEncryptionMethodGenerator} which will be used to encrypt the message.
353	* Method generators are either {@link PBEKeyEncryptionMethodGenerator} (passphrase)
354	* or {@link PGPKeyEncryptionMethodGenerator} (public key).
355	*
356	* This method is intended for advanced users to allow encryption for specific subkeys.
357	* This can come in handy for example if data needs to be encrypted to a subkey that's ignored by PGPainless.
358	*
359	* @param encryptionMethod encryption method
360	* @return this
361	*/
362	public EncryptionOptions addEncryptionMethod(@Nonnull PGPKeyEncryptionMethodGenerator encryptionMethod) {
363	encryptionMethods.add(encryptionMethod);	1✔
364	return this;	1✔
365	}
366
367	Set<PGPKeyEncryptionMethodGenerator> getEncryptionMethods() {
368	return new HashSet<>(encryptionMethods);	1✔
369	}
370
371	Map<SubkeyIdentifier, KeyRingInfo> getKeyRingInfo() {
372	return new HashMap<>(keyRingInfo);	×
373	}
374
375	Set<SubkeyIdentifier> getEncryptionKeyIdentifiers() {
376	return new HashSet<>(encryptionKeys);	1✔
377	}
378
379	Map<SubkeyIdentifier, KeyAccessor> getKeyViews() {
380	return new HashMap<>(keyViews);	1✔
381	}
382
383	SymmetricKeyAlgorithm getEncryptionAlgorithmOverride() {
384	return encryptionAlgorithmOverride;	1✔
385	}
386
387	/**
388	* Override the used symmetric encryption algorithm.
389	* The symmetric encryption algorithm is used to encrypt the message itself,
390	* while the used symmetric key will be encrypted to all recipients using public key
391	* cryptography.
392	*
393	* If the algorithm is not overridden, a suitable algorithm will be negotiated.
394	*
395	* @param encryptionAlgorithm encryption algorithm override
396	* @return this
397	*/
398	public EncryptionOptions overrideEncryptionAlgorithm(@Nonnull SymmetricKeyAlgorithm encryptionAlgorithm) {
399	if (encryptionAlgorithm == SymmetricKeyAlgorithm.NULL) {	1✔
400	throw new IllegalArgumentException("Plaintext encryption can only be used to denote unencrypted secret keys.");	1✔
401	}
402	this.encryptionAlgorithmOverride = encryptionAlgorithm;	1✔
403	return this;	1✔
404	}
405
406	/**
407	* If this method is called, subsequent calls to {@link #addRecipient(PGPPublicKeyRing)} will allow encryption
408	* for subkeys that do not carry any {@link org.pgpainless.algorithm.KeyFlag} subpacket.
409	* This is a workaround for dealing with legacy keys that have no key flags subpacket but rely on the key algorithm
410	* type to convey the subkeys use.
411	*
412	* @return this
413	*/
414	public EncryptionOptions setAllowEncryptionWithMissingKeyFlags() {
415	this.allowEncryptionWithMissingKeyFlags = true;	1✔
416	return this;	1✔
417	}
418
419	/**
420	* Return <pre>true</pre> iff the user specified at least one encryption method,
421	* <pre>false</pre> otherwise.
422	*
423	* @return encryption methods is not empty
424	*/
425	public boolean hasEncryptionMethod() {
426	return !encryptionMethods.isEmpty();	1✔
427	}
428
429	public interface EncryptionKeySelector {
430	List<PGPPublicKey> selectEncryptionSubkeys(@Nonnull List<PGPPublicKey> encryptionCapableKeys);
431	}
432
433	/**
434	* Only encrypt to the first valid encryption capable subkey we stumble upon.
435	*
436	* @return encryption key selector
437	*/
438	public static EncryptionKeySelector encryptToFirstSubkey() {
439	return new EncryptionKeySelector() {	1✔
440	@Override
441	public List<PGPPublicKey> selectEncryptionSubkeys(@Nonnull List<PGPPublicKey> encryptionCapableKeys) {
442	return encryptionCapableKeys.isEmpty() ? Collections.emptyList() : Collections.singletonList(encryptionCapableKeys.get(0));	1✔
443	}
444	};
445	}
446
447	/**
448	* Encrypt to any valid, encryption capable subkey on the key ring.
449	*
450	* @return encryption key selector
451	*/
452	public static EncryptionKeySelector encryptToAllCapableSubkeys() {
453	return new EncryptionKeySelector() {	1✔
454	@Override
455	public List<PGPPublicKey> selectEncryptionSubkeys(@Nonnull List<PGPPublicKey> encryptionCapableKeys) {
456	return encryptionCapableKeys;	1✔
457	}
458	};
459	}
460
461	// TODO: Create encryptToBestSubkey() method
462	}

pgpainless / pgpainless / #1035

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous