From 58dee0d970b055e4304f3d1ffd885dff1cc00b83 Mon Sep 17 00:00:00 2001 From: Paul Schaub Date: Sat, 2 Apr 2022 18:56:05 +0200 Subject: [PATCH] Fix javadoc warnings --- .../main/java/org/pgpainless/PGPainless.java | 2 + .../MessageInspector.java | 6 ++ .../ClearsignedMessageUtil.java | 2 + .../EncryptionBuilderInterface.java | 5 +- .../encryption_signing/EncryptionOptions.java | 1 + .../encryption_signing/SigningOptions.java | 2 + .../key/generation/KeyRingTemplates.java | 36 ++++++++++ .../SecretKeyRingEditorInterface.java | 66 ++++++++++++++++++- .../pgpainless/key/parsing/KeyRingReader.java | 10 +++ .../protection/SecretKeyRingProtector.java | 3 + .../org/pgpainless/key/util/KeyRingUtils.java | 8 +-- .../pgpainless/signature/SignatureUtils.java | 2 + .../builder/AbstractSignatureBuilder.java | 2 + ...irdPartyCertificationSignatureBuilder.java | 4 ++ .../signature/consumer/SignaturePicker.java | 12 ++++ .../consumer/SignatureValidityComparator.java | 2 + .../subpackets/SignatureSubpacketsUtil.java | 2 + .../java/org/pgpainless/util/ArmorUtils.java | 2 + 18 files changed, 160 insertions(+), 7 deletions(-) diff --git a/pgpainless-core/src/main/java/org/pgpainless/PGPainless.java b/pgpainless-core/src/main/java/org/pgpainless/PGPainless.java index bd353f24..46dd35c2 100644 --- a/pgpainless-core/src/main/java/org/pgpainless/PGPainless.java +++ b/pgpainless-core/src/main/java/org/pgpainless/PGPainless.java @@ -71,6 +71,8 @@ public final class PGPainless { * * @param key key or certificate * @return ascii armored string + * + * @throws IOException in case of an error in the {@link org.bouncycastle.bcpg.ArmoredOutputStream} */ public static String asciiArmor(@Nonnull PGPKeyRing key) throws IOException { if (key instanceof PGPSecretKeyRing) { diff --git a/pgpainless-core/src/main/java/org/pgpainless/decryption_verification/MessageInspector.java b/pgpainless-core/src/main/java/org/pgpainless/decryption_verification/MessageInspector.java index a9948f1d..3dda0f5d 100644 --- a/pgpainless-core/src/main/java/org/pgpainless/decryption_verification/MessageInspector.java +++ b/pgpainless-core/src/main/java/org/pgpainless/decryption_verification/MessageInspector.java @@ -75,6 +75,9 @@ public final class MessageInspector { * * @param message OpenPGP message * @return encryption info + * + * @throws PGPException in case the message is broken + * @throws IOException in case of an IO error */ public static EncryptionInfo determineEncryptionInfoForMessage(String message) throws PGPException, IOException { @SuppressWarnings("CharsetObjectCanBeUsed") @@ -88,6 +91,9 @@ public final class MessageInspector { * * @param dataIn openpgp message * @return encryption information + * + * @throws IOException in case of an IO error + * @throws PGPException if the message is broken */ public static EncryptionInfo determineEncryptionInfoForMessage(InputStream dataIn) throws IOException, PGPException { InputStream decoded = ArmorUtils.getDecoderStream(dataIn); diff --git a/pgpainless-core/src/main/java/org/pgpainless/decryption_verification/cleartext_signatures/ClearsignedMessageUtil.java b/pgpainless-core/src/main/java/org/pgpainless/decryption_verification/cleartext_signatures/ClearsignedMessageUtil.java index d2b514bb..ee166c99 100644 --- a/pgpainless-core/src/main/java/org/pgpainless/decryption_verification/cleartext_signatures/ClearsignedMessageUtil.java +++ b/pgpainless-core/src/main/java/org/pgpainless/decryption_verification/cleartext_signatures/ClearsignedMessageUtil.java @@ -35,7 +35,9 @@ public final class ClearsignedMessageUtil { * @param clearsignedInputStream input stream containing a clearsigned message * @param messageOutputStream output stream to which the dearmored message shall be written * @return signatures + * * @throws IOException if the message is not clearsigned or some other IO error happens + * @throws WrongConsumingMethodException in case the armored message is not cleartext signed */ public static PGPSignatureList detachSignaturesFromInbandClearsignedMessage(InputStream clearsignedInputStream, OutputStream messageOutputStream) diff --git a/pgpainless-core/src/main/java/org/pgpainless/encryption_signing/EncryptionBuilderInterface.java b/pgpainless-core/src/main/java/org/pgpainless/encryption_signing/EncryptionBuilderInterface.java index 9ba0bb78..c705c0b1 100644 --- a/pgpainless-core/src/main/java/org/pgpainless/encryption_signing/EncryptionBuilderInterface.java +++ b/pgpainless-core/src/main/java/org/pgpainless/encryption_signing/EncryptionBuilderInterface.java @@ -27,7 +27,10 @@ public interface EncryptionBuilderInterface { * Create an {@link EncryptionStream} with the given options (recipients, signers, algorithms...). * * @param options options - * @return encryption strea + * @return encryption stream + * + * @throws PGPException if something goes wrong during encryption stream preparation + * @throws IOException if something goes wrong during encryption stream preparation (writing headers) */ EncryptionStream withOptions(ProducerOptions options) throws PGPException, IOException; diff --git a/pgpainless-core/src/main/java/org/pgpainless/encryption_signing/EncryptionOptions.java b/pgpainless-core/src/main/java/org/pgpainless/encryption_signing/EncryptionOptions.java index 48107b23..af557703 100644 --- a/pgpainless-core/src/main/java/org/pgpainless/encryption_signing/EncryptionOptions.java +++ b/pgpainless-core/src/main/java/org/pgpainless/encryption_signing/EncryptionOptions.java @@ -282,6 +282,7 @@ public class EncryptionOptions { * If the algorithm is not overridden, a suitable algorithm will be negotiated. * * @param encryptionAlgorithm encryption algorithm override + * @return this */ public EncryptionOptions overrideEncryptionAlgorithm(SymmetricKeyAlgorithm encryptionAlgorithm) { if (encryptionAlgorithm == SymmetricKeyAlgorithm.NULL) { diff --git a/pgpainless-core/src/main/java/org/pgpainless/encryption_signing/SigningOptions.java b/pgpainless-core/src/main/java/org/pgpainless/encryption_signing/SigningOptions.java index 0db93407..0608b22e 100644 --- a/pgpainless-core/src/main/java/org/pgpainless/encryption_signing/SigningOptions.java +++ b/pgpainless-core/src/main/java/org/pgpainless/encryption_signing/SigningOptions.java @@ -58,6 +58,7 @@ public final class SigningOptions { * The resulting signature will be written into the message itself, together with a one-pass-signature packet. * * @param signatureGenerator signature generator + * @param hashAlgorithm hash algorithm used to generate the signature * @return inline signing method */ public static SigningMethod inlineSignature(PGPSignatureGenerator signatureGenerator, HashAlgorithm hashAlgorithm) { @@ -70,6 +71,7 @@ public final class SigningOptions { * to the signed message. * * @param signatureGenerator signature generator + * @param hashAlgorithm hash algorithm used to generate the signature * @return detached signing method */ public static SigningMethod detachedSignature(PGPSignatureGenerator signatureGenerator, HashAlgorithm hashAlgorithm) { diff --git a/pgpainless-core/src/main/java/org/pgpainless/key/generation/KeyRingTemplates.java b/pgpainless-core/src/main/java/org/pgpainless/key/generation/KeyRingTemplates.java index 0917b110..0d663ff9 100644 --- a/pgpainless-core/src/main/java/org/pgpainless/key/generation/KeyRingTemplates.java +++ b/pgpainless-core/src/main/java/org/pgpainless/key/generation/KeyRingTemplates.java @@ -33,6 +33,10 @@ public final class KeyRingTemplates { * @param length length in bits. * * @return {@link PGPSecretKeyRing} containing the KeyPair. + * + * @throws InvalidAlgorithmParameterException in case of invalid key generation parameters + * @throws NoSuchAlgorithmException in case of missing algorithm implementation in the crypto provider + * @throws PGPException in case of an OpenPGP related error */ public PGPSecretKeyRing simpleRsaKeyRing(@Nonnull UserId userId, @Nonnull RsaLength length) throws InvalidAlgorithmParameterException, NoSuchAlgorithmException, PGPException { @@ -47,6 +51,10 @@ public final class KeyRingTemplates { * @param length length in bits. * * @return {@link PGPSecretKeyRing} containing the KeyPair. + * + * @throws InvalidAlgorithmParameterException in case of invalid key generation parameters + * @throws NoSuchAlgorithmException in case of missing algorithm implementation in the crypto provider + * @throws PGPException in case of an OpenPGP related error */ public PGPSecretKeyRing simpleRsaKeyRing(@Nonnull String userId, @Nonnull RsaLength length) throws InvalidAlgorithmParameterException, NoSuchAlgorithmException, PGPException { @@ -62,6 +70,10 @@ public final class KeyRingTemplates { * @param password Password of the key. Can be null for unencrypted keys. * * @return {@link PGPSecretKeyRing} containing the KeyPair. + * + * @throws InvalidAlgorithmParameterException in case of invalid key generation parameters + * @throws NoSuchAlgorithmException in case of missing algorithm implementation in the crypto provider + * @throws PGPException in case of an OpenPGP related error */ public PGPSecretKeyRing simpleRsaKeyRing(@Nonnull UserId userId, @Nonnull RsaLength length, String password) throws InvalidAlgorithmParameterException, NoSuchAlgorithmException, PGPException { @@ -77,6 +89,10 @@ public final class KeyRingTemplates { * @param password Password of the key. Can be null for unencrypted keys. * * @return {@link PGPSecretKeyRing} containing the KeyPair. + * + * @throws InvalidAlgorithmParameterException in case of invalid key generation parameters + * @throws NoSuchAlgorithmException in case of missing algorithm implementation in the crypto provider + * @throws PGPException in case of an OpenPGP related error */ public PGPSecretKeyRing simpleRsaKeyRing(@Nonnull String userId, @Nonnull RsaLength length, String password) throws PGPException, NoSuchAlgorithmException, InvalidAlgorithmParameterException { @@ -98,6 +114,10 @@ public final class KeyRingTemplates { * @param userId user-id * * @return {@link PGPSecretKeyRing} containing the key pairs. + * + * @throws InvalidAlgorithmParameterException in case of invalid key generation parameters + * @throws NoSuchAlgorithmException in case of missing algorithm implementation in the crypto provider + * @throws PGPException in case of an OpenPGP related error */ public PGPSecretKeyRing simpleEcKeyRing(@Nonnull UserId userId) throws InvalidAlgorithmParameterException, NoSuchAlgorithmException, PGPException { @@ -112,6 +132,10 @@ public final class KeyRingTemplates { * @param userId user-id * * @return {@link PGPSecretKeyRing} containing the key pairs. + * + * @throws InvalidAlgorithmParameterException in case of invalid key generation parameters + * @throws NoSuchAlgorithmException in case of missing algorithm implementation in the crypto provider + * @throws PGPException in case of an OpenPGP related error */ public PGPSecretKeyRing simpleEcKeyRing(@Nonnull String userId) throws InvalidAlgorithmParameterException, NoSuchAlgorithmException, PGPException { @@ -127,6 +151,10 @@ public final class KeyRingTemplates { * @param password Password of the private key. Can be null for an unencrypted key. * * @return {@link PGPSecretKeyRing} containing the key pairs. + * + * @throws InvalidAlgorithmParameterException in case of invalid key generation parameters + * @throws NoSuchAlgorithmException in case of missing algorithm implementation in the crypto provider + * @throws PGPException in case of an OpenPGP related error */ public PGPSecretKeyRing simpleEcKeyRing(@Nonnull UserId userId, String password) throws InvalidAlgorithmParameterException, NoSuchAlgorithmException, PGPException { @@ -142,6 +170,10 @@ public final class KeyRingTemplates { * @param password Password of the private key. Can be null for an unencrypted key. * * @return {@link PGPSecretKeyRing} containing the key pairs. + * + * @throws InvalidAlgorithmParameterException in case of invalid key generation parameters + * @throws NoSuchAlgorithmException in case of missing algorithm implementation in the crypto provider + * @throws PGPException in case of an OpenPGP related error */ public PGPSecretKeyRing simpleEcKeyRing(@Nonnull String userId, String password) throws PGPException, NoSuchAlgorithmException, InvalidAlgorithmParameterException { @@ -163,6 +195,10 @@ public final class KeyRingTemplates { * @param userId primary user id * @param password passphrase or null if the key should be unprotected. * @return key ring + * + * @throws InvalidAlgorithmParameterException in case of invalid key generation parameters + * @throws NoSuchAlgorithmException in case of missing algorithm implementation in the crypto provider + * @throws PGPException in case of an OpenPGP related error */ public PGPSecretKeyRing modernKeyRing(String userId, String password) throws InvalidAlgorithmParameterException, NoSuchAlgorithmException, PGPException { diff --git a/pgpainless-core/src/main/java/org/pgpainless/key/modification/secretkeyring/SecretKeyRingEditorInterface.java b/pgpainless-core/src/main/java/org/pgpainless/key/modification/secretkeyring/SecretKeyRingEditorInterface.java index ec579c9e..6f4d34b8 100644 --- a/pgpainless-core/src/main/java/org/pgpainless/key/modification/secretkeyring/SecretKeyRingEditorInterface.java +++ b/pgpainless-core/src/main/java/org/pgpainless/key/modification/secretkeyring/SecretKeyRingEditorInterface.java @@ -34,6 +34,8 @@ public interface SecretKeyRingEditorInterface { * @param userId user-id * @param secretKeyRingProtector protector to unlock the secret key * @return the builder + * + * @throws PGPException in case we cannot generate a signature for the user-id */ SecretKeyRingEditorInterface addUserId( @Nonnull CharSequence userId, @@ -48,6 +50,8 @@ public interface SecretKeyRingEditorInterface { * certification signature. * @param protector protector to unlock the primary secret key * @return the builder + * + * @throws PGPException in case we cannot generate a signature for the user-id */ SecretKeyRingEditorInterface addUserId( @Nonnull CharSequence userId, @@ -62,6 +66,8 @@ public interface SecretKeyRingEditorInterface { * @param userId user id * @param protector protector to unlock the secret key * @return the builder + * + * @throws PGPException in case we cannot generate a signature for the user-id */ SecretKeyRingEditorInterface addPrimaryUserId( @Nonnull CharSequence userId, @@ -76,6 +82,8 @@ public interface SecretKeyRingEditorInterface { * @param userIdSelector selector to select user-ids * @param protector protector to unlock the primary key * @return the builder + * + * @throws PGPException in case we cannot generate a revocation signature for the user-id */ SecretKeyRingEditorInterface removeUserId(SelectUserId userIdSelector, SecretKeyRingProtector protector) @@ -89,6 +97,8 @@ public interface SecretKeyRingEditorInterface { * @param userId user-id to revoke * @param protector protector to unlock the primary key * @return the builder + * + * @throws PGPException in case we cannot generate a revocation signature for the user-id */ SecretKeyRingEditorInterface removeUserId(CharSequence userId, SecretKeyRingProtector protector) @@ -102,6 +112,11 @@ public interface SecretKeyRingEditorInterface { * @param subKeyPassphrase passphrase to encrypt the sub key * @param secretKeyRingProtector protector to unlock the secret key of the key ring * @return the builder + * + * @throws InvalidAlgorithmParameterException in case the user wants to use invalid parameters for the key + * @throws NoSuchAlgorithmException in case of missing algorithm support in the crypto backend + * @throws PGPException in case we cannot generate a binding signature for the subkey + * @throws IOException in case of an IO error */ SecretKeyRingEditorInterface addSubKey( @Nonnull KeySpec keySpec, @@ -118,6 +133,11 @@ public interface SecretKeyRingEditorInterface { * @param subpacketsCallback callback to modify the subpackets of the subkey binding signature * @param secretKeyRingProtector protector to unlock the primary key * @return builder + * + * @throws InvalidAlgorithmParameterException in case the user wants to use invalid parameters for the key + * @throws NoSuchAlgorithmException in case of missing algorithm support in the crypto backend + * @throws PGPException in case we cannot generate a binding signature for the subkey + * @throws IOException in case of an IO error */ SecretKeyRingEditorInterface addSubKey( @Nonnull KeySpec keySpec, @@ -136,6 +156,10 @@ public interface SecretKeyRingEditorInterface { * @param keyFlag first key flag for the subkey * @param additionalKeyFlags optional additional key flags * @return builder + * + * @throws PGPException in case we cannot generate a binding signature for the subkey + * @throws IOException in case of an IO error + * @throws NoSuchAlgorithmException in case of missing algorithm support in the crypto backend */ SecretKeyRingEditorInterface addSubKey( @Nonnull PGPKeyPair subkey, @@ -152,6 +176,8 @@ public interface SecretKeyRingEditorInterface { * * @param secretKeyRingProtector protector of the primary key * @return the builder + * + * @throws PGPException in case we cannot generate a revocation signature */ default SecretKeyRingEditorInterface revoke( @Nonnull SecretKeyRingProtector secretKeyRingProtector) @@ -166,6 +192,8 @@ public interface SecretKeyRingEditorInterface { * @param secretKeyRingProtector protector of the primary key * @param revocationAttributes reason for the revocation * @return the builder + * + * @throws PGPException in case we cannot generate a revocation signature */ SecretKeyRingEditorInterface revoke( @Nonnull SecretKeyRingProtector secretKeyRingProtector, @@ -180,6 +208,8 @@ public interface SecretKeyRingEditorInterface { * @param secretKeyRingProtector protector to unlock the primary secret key * @param subpacketsCallback callback to modify the revocations subpackets * @return builder + * + * @throws PGPException in case we cannot generate a revocation signature */ SecretKeyRingEditorInterface revoke( @Nonnull SecretKeyRingProtector secretKeyRingProtector, @@ -198,6 +228,8 @@ public interface SecretKeyRingEditorInterface { * @param fingerprint fingerprint of the subkey to be revoked * @param secretKeyRingProtector protector to unlock the secret key ring * @return the builder + * + * @throws PGPException in case we cannot generate a revocation signature for the subkey */ default SecretKeyRingEditorInterface revokeSubKey( @Nonnull OpenPgpFingerprint fingerprint, @@ -215,6 +247,8 @@ public interface SecretKeyRingEditorInterface { * @param secretKeyRingProtector protector to unlock the primary key * @param revocationAttributes reason for the revocation * @return the builder + * + * @throws PGPException in case we cannot generate a revocation signature for the subkey */ default SecretKeyRingEditorInterface revokeSubKey( OpenPgpFingerprint fingerprint, @@ -235,6 +269,8 @@ public interface SecretKeyRingEditorInterface { * @param secretKeyRingProtector protector to unlock the primary key * @param revocationAttributes reason for the revocation * @return the builder + * + * @throws PGPException in case we cannot generate a revocation signature for the subkey */ SecretKeyRingEditorInterface revokeSubKey( long subKeyId, @@ -255,6 +291,8 @@ public interface SecretKeyRingEditorInterface { * @param subKeyId id of the subkey * @param secretKeyRingProtector protector to unlock the secret key ring * @return the builder + * + * @throws PGPException in case we cannot generate a revocation signature for the subkey */ default SecretKeyRingEditorInterface revokeSubKey( long subKeyId, @@ -279,6 +317,8 @@ public interface SecretKeyRingEditorInterface { * @param subpacketsCallback callback which can be used to modify the subpackets of the revocation * signature * @return the builder + * + * @throws PGPException in case we cannot generate a revocation signature for the subkey */ SecretKeyRingEditorInterface revokeSubKey( long keyID, @@ -296,6 +336,8 @@ public interface SecretKeyRingEditorInterface { * @param userId userId to revoke * @param secretKeyRingProtector protector to unlock the primary key * @return the builder + * + * @throws PGPException in case we cannot generate a revocation signature for the user-id */ default SecretKeyRingEditorInterface revokeUserId( @Nonnull CharSequence userId, @@ -311,6 +353,8 @@ public interface SecretKeyRingEditorInterface { * @param secretKeyRingProtector protector to unlock the primary key * @param revocationAttributes reason for the revocation * @return the builder + * + * @throws PGPException in case we cannot generate a revocation signature for the user-id */ SecretKeyRingEditorInterface revokeUserId( @Nonnull CharSequence userId, @@ -329,6 +373,8 @@ public interface SecretKeyRingEditorInterface { * @param secretKeyRingProtector protector to unlock the primary secret key * @param subpacketCallback callback to modify the revocations subpackets * @return builder + * + * @throws PGPException in case we cannot generate a revocation signature for the user-id */ SecretKeyRingEditorInterface revokeUserId( @Nonnull CharSequence userId, @@ -348,7 +394,8 @@ public interface SecretKeyRingEditorInterface { * @param secretKeyRingProtector protector to unlock the primary secret key * @param revocationAttributes revocation attributes * @return builder - * @throws PGPException if the revocation signatures cannot be generated + * + * @throws PGPException in case we cannot generate a revocation signature for the user-id */ SecretKeyRingEditorInterface revokeUserIds( @Nonnull SelectUserId userIdSelector, @@ -370,7 +417,8 @@ public interface SecretKeyRingEditorInterface { * @param secretKeyRingProtector protector to unlock the primary secret key * @param subpacketsCallback callback to modify the revocations subpackets * @return builder - * @throws PGPException if the revocation signatures cannot be generated + * + * @throws PGPException in case we cannot generate a revocation signature for the user-id */ SecretKeyRingEditorInterface revokeUserIds( @Nonnull SelectUserId userIdSelector, @@ -385,6 +433,8 @@ public interface SecretKeyRingEditorInterface { * @param expiration new expiration date or null * @param secretKeyRingProtector to unlock the secret key * @return the builder + * + * @throws PGPException in case we cannot generate a new self-signature with the changed expiration date */ SecretKeyRingEditorInterface setExpirationDate( @Nullable Date expiration, @@ -397,6 +447,8 @@ public interface SecretKeyRingEditorInterface { * @param secretKeyRingProtector protector to unlock the primary key. * @param revocationAttributes reason for the revocation * @return revocation certificate + * + * @throws PGPException in case we cannot generate a revocation certificate */ PGPSignature createRevocationCertificate( @Nonnull SecretKeyRingProtector secretKeyRingProtector, @@ -410,6 +462,8 @@ public interface SecretKeyRingEditorInterface { * @param secretKeyRingProtector protector to unlock the primary key. * @param revocationAttributes reason for the revocation * @return revocation certificate + * + * @throws PGPException in case we cannot generate a revocation certificate */ PGPSignature createRevocationCertificate( long subkeyId, @@ -424,6 +478,8 @@ public interface SecretKeyRingEditorInterface { * @param secretKeyRingProtector protector to unlock the primary key. * @param certificateSubpacketsCallback callback to modify the subpackets of the revocation certificate. * @return revocation certificate + * + * @throws PGPException in case we cannot generate a revocation certificate */ PGPSignature createRevocationCertificate( long subkeyId, @@ -438,6 +494,8 @@ public interface SecretKeyRingEditorInterface { * @param secretKeyRingProtector protector to unlock the primary key. * @param revocationAttributes reason for the revocation * @return revocation certificate + * + * @throws PGPException in case we cannot generate a revocation certificate */ default PGPSignature createRevocationCertificate( OpenPgpFingerprint subkeyFingerprint, @@ -521,6 +579,8 @@ public interface SecretKeyRingEditorInterface { * * @param passphrase passphrase * @return editor builder + * + * @throws PGPException in case the passphrase cannot be changed */ SecretKeyRingEditorInterface toNewPassphrase(Passphrase passphrase) throws PGPException; @@ -529,6 +589,8 @@ public interface SecretKeyRingEditorInterface { * Leave the key unprotected. * * @return editor builder + * + * @throws PGPException in case the passphrase cannot be changed */ SecretKeyRingEditorInterface toNoPassphrase() throws PGPException; } diff --git a/pgpainless-core/src/main/java/org/pgpainless/key/parsing/KeyRingReader.java b/pgpainless-core/src/main/java/org/pgpainless/key/parsing/KeyRingReader.java index 5c347f75..0021f74e 100644 --- a/pgpainless-core/src/main/java/org/pgpainless/key/parsing/KeyRingReader.java +++ b/pgpainless-core/src/main/java/org/pgpainless/key/parsing/KeyRingReader.java @@ -107,6 +107,8 @@ public class KeyRingReader { * @param inputStream input stream * @param maxIterations max iterations before abort * @return public key ring + * + * @throws IOException in case of an IO error or exceeding of max iterations */ public static PGPPublicKeyRing readPublicKeyRing(@Nonnull InputStream inputStream, int maxIterations) throws IOException { PGPObjectFactory objectFactory = ImplementationFactory.getInstance().getPGPObjectFactory( @@ -142,6 +144,9 @@ public class KeyRingReader { * @param inputStream input stream * @param maxIterations max iterations before abort * @return public key ring collection + * + * @throws IOException in case of an IO error or exceeding of max iterations + * @throws PGPException in case of a broken key */ public static PGPPublicKeyRingCollection readPublicKeyRingCollection(@Nonnull InputStream inputStream, int maxIterations) throws IOException, PGPException { @@ -186,6 +191,8 @@ public class KeyRingReader { * @param inputStream input stream * @param maxIterations max iterations before abort * @return public key ring + * + * @throws IOException in case of an IO error or exceeding of max iterations */ public static PGPSecretKeyRing readSecretKeyRing(@Nonnull InputStream inputStream, int maxIterations) throws IOException { InputStream decoderStream = ArmorUtils.getDecoderStream(inputStream); @@ -222,6 +229,9 @@ public class KeyRingReader { * @param inputStream input stream * @param maxIterations max iterations before abort * @return secret key ring collection + * + * @throws IOException in case of an IO error or exceeding of max iterations + * @throws PGPException in case of a broken secret key */ public static PGPSecretKeyRingCollection readSecretKeyRingCollection(@Nonnull InputStream inputStream, int maxIterations) diff --git a/pgpainless-core/src/main/java/org/pgpainless/key/protection/SecretKeyRingProtector.java b/pgpainless-core/src/main/java/org/pgpainless/key/protection/SecretKeyRingProtector.java index 84f47155..ee461a4e 100644 --- a/pgpainless-core/src/main/java/org/pgpainless/key/protection/SecretKeyRingProtector.java +++ b/pgpainless-core/src/main/java/org/pgpainless/key/protection/SecretKeyRingProtector.java @@ -37,6 +37,8 @@ public interface SecretKeyRingProtector { * * @param keyId id of the key * @return decryptor for the key + * + * @throws PGPException if the decryptor cannot be created for some reason */ @Nullable PBESecretKeyDecryptor getDecryptor(Long keyId) throws PGPException; @@ -46,6 +48,7 @@ public interface SecretKeyRingProtector { * * @param keyId id of the key * @return encryptor for the key + * * @throws PGPException if the encryptor cannot be created for some reason */ @Nullable PBESecretKeyEncryptor getEncryptor(Long keyId) throws PGPException; diff --git a/pgpainless-core/src/main/java/org/pgpainless/key/util/KeyRingUtils.java b/pgpainless-core/src/main/java/org/pgpainless/key/util/KeyRingUtils.java index f64133b0..375e3527 100644 --- a/pgpainless-core/src/main/java/org/pgpainless/key/util/KeyRingUtils.java +++ b/pgpainless-core/src/main/java/org/pgpainless/key/util/KeyRingUtils.java @@ -429,8 +429,8 @@ public final class KeyRingUtils { * @param secretKeyId id of the secret key to remove * @return secret key ring with removed secret key * - * @throws IOException - * @throws PGPException + * @throws IOException in case of an error during serialization / deserialization of the key + * @throws PGPException in case of a broken key * * @deprecated use {@link #stripSecretKey(PGPSecretKeyRing, long)} instead. * TODO: Remove in 1.2.X @@ -453,8 +453,8 @@ public final class KeyRingUtils { * @param secretKeyId id of the secret key to remove * @return secret key ring with removed secret key * - * @throws IOException - * @throws PGPException + * @throws IOException in case of an error during serialization / deserialization of the key + * @throws PGPException in case of a broken key */ @Nonnull public static PGPSecretKeyRing stripSecretKey(@Nonnull PGPSecretKeyRing secretKeys, diff --git a/pgpainless-core/src/main/java/org/pgpainless/signature/SignatureUtils.java b/pgpainless-core/src/main/java/org/pgpainless/signature/SignatureUtils.java index 420efc26..1ebbdda4 100644 --- a/pgpainless-core/src/main/java/org/pgpainless/signature/SignatureUtils.java +++ b/pgpainless-core/src/main/java/org/pgpainless/signature/SignatureUtils.java @@ -193,7 +193,9 @@ public final class SignatureUtils { * * @param encodedSignatures ASCII armored signature list * @return signature list + * * @throws IOException if the signatures cannot be read + * @throws PGPException in case of a broken signature */ public static List readSignatures(String encodedSignatures) throws IOException, PGPException { @SuppressWarnings("CharsetObjectCanBeUsed") diff --git a/pgpainless-core/src/main/java/org/pgpainless/signature/builder/AbstractSignatureBuilder.java b/pgpainless-core/src/main/java/org/pgpainless/signature/builder/AbstractSignatureBuilder.java index 08e496ac..1079f92f 100644 --- a/pgpainless-core/src/main/java/org/pgpainless/signature/builder/AbstractSignatureBuilder.java +++ b/pgpainless-core/src/main/java/org/pgpainless/signature/builder/AbstractSignatureBuilder.java @@ -114,6 +114,8 @@ public abstract class AbstractSignatureBuilder { /** * Create a new {@link SignatureValidityComparator} which orders signatures following the passed ordering. * Still, hard revocations will come first. + * + * @param order order of creation dates */ public SignatureValidityComparator(SignatureCreationDateComparator.Order order) { this.creationDateComparator = new SignatureCreationDateComparator(order); diff --git a/pgpainless-core/src/main/java/org/pgpainless/signature/subpackets/SignatureSubpacketsUtil.java b/pgpainless-core/src/main/java/org/pgpainless/signature/subpackets/SignatureSubpacketsUtil.java index 12c6f1de..7d3b4622 100644 --- a/pgpainless-core/src/main/java/org/pgpainless/signature/subpackets/SignatureSubpacketsUtil.java +++ b/pgpainless-core/src/main/java/org/pgpainless/signature/subpackets/SignatureSubpacketsUtil.java @@ -506,6 +506,8 @@ public final class SignatureSubpacketsUtil { * * @param signature signature * @return embedded signature + * + * @throws PGPException in case the embedded signatures cannot be parsed */ public static PGPSignatureList getEmbeddedSignature(PGPSignature signature) throws PGPException { PGPSignatureList hashed = signature.getHashedSubPackets().getEmbeddedSignatures(); diff --git a/pgpainless-core/src/main/java/org/pgpainless/util/ArmorUtils.java b/pgpainless-core/src/main/java/org/pgpainless/util/ArmorUtils.java index 1d3c17cc..d95673a4 100644 --- a/pgpainless-core/src/main/java/org/pgpainless/util/ArmorUtils.java +++ b/pgpainless-core/src/main/java/org/pgpainless/util/ArmorUtils.java @@ -544,6 +544,8 @@ public final class ArmorUtils { * * @param inputStream input stream * @return BufferedInputStreamExt + * + * @throws IOException in case of an IO error */ @Nonnull public static InputStream getDecoderStream(@Nonnull InputStream inputStream)