mirror of
https://github.com/pgpainless/pgpainless.git
synced 2024-12-23 11:27:57 +01:00
Add documentation and deprecate old methods
This commit is contained in:
parent
8f425cd31d
commit
715d055b41
3 changed files with 135 additions and 22 deletions
|
@ -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);
|
||||
}
|
||||
}
|
||||
|
|
|
@ -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;
|
||||
|
||||
}
|
||||
|
|
|
@ -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);
|
||||
|
|
Loading…
Reference in a new issue