PGPainless/pgpainless
PGPainless
/
pgpainless
mirror of https://github.com/pgpainless/pgpainless.git
1
0
Fork 0
Code Issues Releases Wiki Activity

Add documentation and deprecate old methods

This commit is contained in:
Paul Schaub 2021-06-15 17:56:36 +02:00
parent 8f425cd31d
commit 715d055b41
Signed by: vanitasvitae
GPG Key ID: 62BEE9264BF17311
3 changed files with 135 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
pgpainless-core/src/main/java/org/pgpainless/decryption_verification/ConsumerOptions.java
View File

@ -1,23 +1,32 @@
/*
* Copyright 2021 Paul Schaub.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.pgpainless.decryption_verification;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
import java.util.Date;
import java.util.HashMap;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import org.bouncycastle.openpgp.PGPException;
import org.bouncycastle.openpgp.PGPPublicKeyRing;
import org.bouncycastle.openpgp.PGPPublicKeyRingCollection;
import org.bouncycastle.openpgp.PGPSecretKeyRing;
import org.bouncycastle.openpgp.PGPSecretKeyRingCollection;
import org.bouncycastle.openpgp.PGPSignature;
import org.pgpainless.key.protection.SecretKeyRingProtector;
import org.pgpainless.util.Passphrase;
@ -31,8 +40,8 @@ public class ConsumerOptions {
private Date verifyNotAfter;
// Set of verification keys
private Set<PGPPublicKeyRing> certificates = new HashSet<>();
private Set<PGPSignature> detachedSignatures = new HashSet<>();
private final Set<PGPPublicKeyRing> certificates = new HashSet<>();
private final Set<PGPSignature> detachedSignatures = new HashSet<>();
private MissingPublicKeyCallback missingCertificateCallback = null;
// Session key for decryption without passphrase/key
@ -53,6 +62,10 @@ public class ConsumerOptions {
return this;
}
public Date getVerifyNotBefore() {
return verifyNotBefore;
}
/**
* Consider signatures made after the given timestamp invalid.
*
@ -64,6 +77,10 @@ public class ConsumerOptions {
return this;
}
public Date getVerifyNotAfter() {
return verifyNotAfter;
}
/**
* Add a certificate (public key ring) for signature verification.
*
@ -127,6 +144,21 @@ public class ConsumerOptions {
return this;
}
/**
* Return the session key.
*
* @return session key or null
*/
public @Nullable byte[] getSessionKey() {
if (sessionKey == null) {
return null;
}
byte[] sk = new byte[sessionKey.length];
System.arraycopy(sessionKey, 0, sk, 0, sessionKey.length);
return sk;
}
/**
* Add a key for message decryption.
* The key is expected to be unencrypted.
@ -162,27 +194,27 @@ public class ConsumerOptions {
return this;
}
public Set<PGPSecretKeyRing> getDecryptionKeys() {
public @Nonnull Set<PGPSecretKeyRing> getDecryptionKeys() {
return Collections.unmodifiableSet(decryptionKeys.keySet());
}
public Set<Passphrase> getDecryptionPassphrases() {
public @Nonnull Set<Passphrase> getDecryptionPassphrases() {
return Collections.unmodifiableSet(decryptionPassphrases);
}
public Set<PGPPublicKeyRing> getCertificates() {
public @Nonnull Set<PGPPublicKeyRing> getCertificates() {
return Collections.unmodifiableSet(certificates);
}
public MissingPublicKeyCallback getMissingCertificateCallback() {
public @Nullable MissingPublicKeyCallback getMissingCertificateCallback() {
return missingCertificateCallback;
}
public SecretKeyRingProtector getSecretKeyProtector(PGPSecretKeyRing decryptionKeyRing) {
public @Nullable SecretKeyRingProtector getSecretKeyProtector(PGPSecretKeyRing decryptionKeyRing) {
return decryptionKeys.get(decryptionKeyRing);
}
public Set<PGPSignature> getDetachedSignatures() {
public @Nonnull Set<PGPSignature> getDetachedSignatures() {
return Collections.unmodifiableSet(detachedSignatures);
}
}

88
pgpainless-core/src/main/java/org/pgpainless/decryption_verification/DecryptionBuilderInterface.java
View File

@ -46,6 +46,14 @@ public interface DecryptionBuilderInterface {
interface DecryptWith {
/**
* Add options for decryption / signature verification, such as keys, passphrases etc.
*
* @param consumerOptions consumer options
* @return decryption stream
* @throws PGPException in case of an OpenPGP related error
* @throws IOException in case of an IO error
*/
DecryptionStream withOptions(ConsumerOptions consumerOptions) throws PGPException, IOException;
/**
@ -56,7 +64,11 @@ public interface DecryptionBuilderInterface {
*
* @param secretKeyRings secret keys
* @return api handle
*
* @deprecated use {@link ConsumerOptions#addDecryptionKey(PGPSecretKeyRing, SecretKeyRingProtector)}
* ({@link #withOptions(ConsumerOptions)}) instead.
*/
@Deprecated
default Verify decryptWith(@Nonnull PGPSecretKeyRingCollection secretKeyRings) {
return decryptWith(new UnprotectedKeysProtector(), secretKeyRings);
}
@ -68,7 +80,11 @@ public interface DecryptionBuilderInterface {
* @param decryptor for unlocking locked secret keys
* @param secretKeyRings secret keys
* @return api handle
*
* @deprecated use {@link ConsumerOptions#addDecryptionKey(PGPSecretKeyRing, SecretKeyRingProtector)}
* ({@link #withOptions(ConsumerOptions)}) instead.
*/
@Deprecated
Verify decryptWith(@Nonnull SecretKeyRingProtector decryptor, @Nonnull PGPSecretKeyRingCollection secretKeyRings);
/**
@ -78,8 +94,13 @@ public interface DecryptionBuilderInterface {
* @param decryptor for unlocking locked secret key
* @param secretKeyRing secret key
* @return api handle
*
* @deprecated use {@link ConsumerOptions#addDecryptionKey(PGPSecretKeyRing, SecretKeyRingProtector)}
* ({@link #withOptions(ConsumerOptions)}) instead.
*/
Verify decryptWith(@Nonnull SecretKeyRingProtector decryptor, @Nonnull PGPSecretKeyRing secretKeyRing) throws PGPException, IOException;
@Deprecated
Verify decryptWith(@Nonnull SecretKeyRingProtector decryptor, @Nonnull PGPSecretKeyRing secretKeyRing)
throws PGPException, IOException;
/**
* Decrypt the encrypted data using a passphrase.
@ -87,7 +108,11 @@ public interface DecryptionBuilderInterface {
*
* @param passphrase passphrase
* @return api handle
*
* @deprecated use {@link ConsumerOptions#addDecryptionPassphrase(Passphrase)}
* ({@link #withOptions(ConsumerOptions)}) instead.
*/
@Deprecated
Verify decryptWith(@Nonnull Passphrase passphrase);
/**
@ -95,32 +120,41 @@ public interface DecryptionBuilderInterface {
* Useful for signature verification of signed-only data.
*
* @return api handle
*
* @deprecated use {@link #withOptions(ConsumerOptions)} instead and set no decryption keys.
*/
@Deprecated
Verify doNotDecrypt();
}
@Deprecated
interface Verify extends VerifyWith {
@Override
@Deprecated
HandleMissingPublicKeys verifyWith(@Nonnull PGPPublicKeyRingCollection publicKeyRings);
@Override
@Deprecated
default HandleMissingPublicKeys verifyWith(@Nonnull OpenPgpV4Fingerprint trustedFingerprint,
@Nonnull PGPPublicKeyRingCollection publicKeyRings) {
return verifyWith(Collections.singleton(trustedFingerprint), publicKeyRings);
}
@Override
@Deprecated
HandleMissingPublicKeys verifyWith(@Nonnull Set<OpenPgpV4Fingerprint> trustedFingerprints,
@Nonnull PGPPublicKeyRingCollection publicKeyRings);
@Override
@Deprecated
default HandleMissingPublicKeys verifyWith(@Nonnull PGPPublicKeyRing publicKeyRing) {
return verifyWith(Collections.singleton(publicKeyRing));
}
@Override
@Deprecated
HandleMissingPublicKeys verifyWith(@Nonnull Set<PGPPublicKeyRing> publicKeyRings);
/**
@ -130,7 +164,11 @@ public interface DecryptionBuilderInterface {
* @return api handle
* @throws IOException if some IO error occurs
* @throws PGPException if the detached signatures are malformed
*
* @deprecated use {@link ConsumerOptions#addVerificationOfDetachedSignature(PGPSignature)}
* ({@link DecryptWith#withOptions(ConsumerOptions)}) instead.
*/
@Deprecated
default VerifyWith verifyDetachedSignature(@Nonnull byte[] bytes) throws IOException, PGPException {
return verifyDetachedSignature(new ByteArrayInputStream(bytes));
}
@ -142,7 +180,11 @@ public interface DecryptionBuilderInterface {
* @return api handle
* @throws IOException in case something is wrong with the input stream
* @throws PGPException if the detached signatures are malformed
*
* @deprecated use {@link ConsumerOptions#addVerificationOfDetachedSignature(PGPSignature)}
* ({@link DecryptWith#withOptions(ConsumerOptions)}) instead.
*/
@Deprecated
VerifyWith verifyDetachedSignature(@Nonnull InputStream inputStream) throws IOException, PGPException;
/**
@ -150,7 +192,11 @@ public interface DecryptionBuilderInterface {
*
* @param signature detached signature
* @return api handle
*
* @deprecated use {@link ConsumerOptions#addVerificationOfDetachedSignature(PGPSignature)}
* ({@link DecryptWith#withOptions(ConsumerOptions)}) instead.
*/
@Deprecated
default VerifyWith verifyDetachedSignature(@Nonnull PGPSignature signature) {
return verifyDetachedSignatures(Collections.singletonList(signature));
}
@ -160,17 +206,25 @@ public interface DecryptionBuilderInterface {
*
* @param signatures detached signatures
* @return api handle
*
* @deprecated use {@link ConsumerOptions#addVerificationOfDetachedSignature(PGPSignature)}
* ({@link DecryptWith#withOptions(ConsumerOptions)}) instead.
*/
@Deprecated
VerifyWith verifyDetachedSignatures(@Nonnull List<PGPSignature> signatures);
/**
* Instruct the {@link DecryptionStream} to not verify any signatures.
*
* @return api handle
*
* @deprecated use {@link DecryptWith#withOptions(ConsumerOptions)} instead and don't set verification keys.
*/
@Deprecated
Build doNotVerify();
}
@Deprecated
interface VerifyWith {
/**
@ -178,7 +232,11 @@ public interface DecryptionBuilderInterface {
*
* @param publicKeyRings public keys
* @return api handle
*
* @deprecated use {@link ConsumerOptions#addVerificationCerts(PGPPublicKeyRingCollection)}
* ({@link DecryptWith#withOptions(ConsumerOptions)}) instead.
*/
@Deprecated
HandleMissingPublicKeys verifyWith(@Nonnull PGPPublicKeyRingCollection publicKeyRings);
/**
@ -188,7 +246,10 @@ public interface DecryptionBuilderInterface {
* @param trustedFingerprint {@link OpenPgpV4Fingerprint} of the public key that shall be used to verify the signatures.
* @param publicKeyRings public keys
* @return api handle
* @deprecated use {@link ConsumerOptions#addVerificationCert(PGPPublicKeyRing)}
* ({@link DecryptWith#withOptions(ConsumerOptions)}) instead.
*/
@Deprecated
default HandleMissingPublicKeys verifyWith(@Nonnull OpenPgpV4Fingerprint trustedFingerprint,
@Nonnull PGPPublicKeyRingCollection publicKeyRings) {
return verifyWith(Collections.singleton(trustedFingerprint), publicKeyRings);
@ -201,7 +262,11 @@ public interface DecryptionBuilderInterface {
* @param trustedFingerprints set of trusted {@link OpenPgpV4Fingerprint OpenPgpV4Fingerprints}.
* @param publicKeyRings public keys
* @return api handle
*
* @deprecated use {@link ConsumerOptions#addVerificationCert(PGPPublicKeyRing)}
* ({@link DecryptWith#withOptions(ConsumerOptions)}) instead.
*/
@Deprecated
HandleMissingPublicKeys verifyWith(@Nonnull Set<OpenPgpV4Fingerprint> trustedFingerprints,
@Nonnull PGPPublicKeyRingCollection publicKeyRings);
@ -210,7 +275,11 @@ public interface DecryptionBuilderInterface {
*
* @param publicKeyRing public key
* @return api handle
*
* @deprecated use {@link ConsumerOptions#addVerificationCert(PGPPublicKeyRing)}
* ({@link DecryptWith#withOptions(ConsumerOptions)}) instead.
*/
@Deprecated
default HandleMissingPublicKeys verifyWith(@Nonnull PGPPublicKeyRing publicKeyRing) {
return verifyWith(Collections.singleton(publicKeyRing));
}
@ -220,11 +289,16 @@ public interface DecryptionBuilderInterface {
*
* @param publicKeyRings public keys
* @return api handle
*
* @deprecated use {@link ConsumerOptions#addVerificationCert(PGPPublicKeyRing)}
* ({@link DecryptWith#withOptions(ConsumerOptions)}) instead.
*/
@Deprecated
HandleMissingPublicKeys verifyWith(@Nonnull Set<PGPPublicKeyRing> publicKeyRings);
}
@Deprecated
interface HandleMissingPublicKeys {
/**
@ -232,17 +306,26 @@ public interface DecryptionBuilderInterface {
*
* @param callback callback
* @return api handle
*
* @deprecated use {@link ConsumerOptions#setMissingCertificateCallback(MissingPublicKeyCallback)}
* ({@link DecryptWith#withOptions(ConsumerOptions)}) instead.
*/
@Deprecated
Build handleMissingPublicKeysWith(@Nonnull MissingPublicKeyCallback callback);
/**
* Instruct the {@link DecryptionStream} to ignore any missing public keys.
*
* @return api handle
*
* @deprecated simply do not set a {@link MissingPublicKeyCallback} and use
* {@link DecryptWith#withOptions(ConsumerOptions)} instead.
*/
@Deprecated
Build ignoreMissingPublicKeys();
}
@Deprecated
interface Build {
/**
@ -252,7 +335,10 @@ public interface DecryptionBuilderInterface {
* @throws IOException in case of an I/O error
* @throws PGPException if something is malformed
* @throws org.pgpainless.exception.UnacceptableAlgorithmException if the message uses weak/unacceptable algorithms
*
* @deprecated use {@link DecryptWith#withOptions(ConsumerOptions)} instead.
*/
@Deprecated
DecryptionStream build() throws IOException, PGPException;
}

9
pgpainless-core/src/main/java/org/pgpainless/decryption_verification/DecryptionStreamFactory.java
View File

@ -19,17 +19,13 @@ import java.io.BufferedInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.logging.Level;
import java.util.logging.Logger;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import org.bouncycastle.openpgp.PGPCompressedData;
import org.bouncycastle.openpgp.PGPEncryptedData;
@ -46,7 +42,6 @@ import org.bouncycastle.openpgp.PGPPublicKeyEncryptedData;
import org.bouncycastle.openpgp.PGPPublicKeyRing;
import org.bouncycastle.openpgp.PGPSecretKey;
import org.bouncycastle.openpgp.PGPSecretKeyRing;
import org.bouncycastle.openpgp.PGPSecretKeyRingCollection;
import org.bouncycastle.openpgp.PGPSignature;
import org.bouncycastle.openpgp.PGPUtil;
import org.bouncycastle.openpgp.operator.KeyFingerPrintCalculator;
@ -66,7 +61,6 @@ import org.pgpainless.implementation.ImplementationFactory;
import org.pgpainless.key.OpenPgpV4Fingerprint;
import org.pgpainless.key.SubkeyIdentifier;
import org.pgpainless.key.info.KeyRingInfo;
import org.pgpainless.key.protection.SecretKeyRingProtector;
import org.pgpainless.key.protection.UnlockSecretKey;
import org.pgpainless.signature.DetachedSignature;
import org.pgpainless.signature.OnePassSignature;
@ -92,7 +86,8 @@ public final class DecryptionStreamFactory {
}
public static DecryptionStream create(@Nonnull InputStream inputStream,
@Nonnull ConsumerOptions options) throws PGPException, IOException {
@Nonnull ConsumerOptions options)
throws PGPException, IOException {
BufferedInputStream bufferedIn = new BufferedInputStream(inputStream);
bufferedIn.mark(200);
DecryptionStreamFactory factory = new DecryptionStreamFactory(options);