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 327701ad..502dbff8 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 @@ -12,6 +12,7 @@ import java.util.Iterator; import java.util.List; import java.util.NoSuchElementException; import javax.annotation.Nonnull; +import javax.annotation.Nullable; import org.bouncycastle.openpgp.PGPException; import org.bouncycastle.openpgp.PGPKeyRing; @@ -43,7 +44,8 @@ public final class KeyRingUtils { * @param secretKeys secret keys * @return primary secret key */ - public static PGPSecretKey requirePrimarySecretKeyFrom(PGPSecretKeyRing secretKeys) { + @Nonnull + public static PGPSecretKey requirePrimarySecretKeyFrom(@Nonnull PGPSecretKeyRing secretKeys) { PGPSecretKey primarySecretKey = getPrimarySecretKeyFrom(secretKeys); if (primarySecretKey == null) { throw new NoSuchElementException("Provided PGPSecretKeyRing has no primary secret key."); @@ -57,7 +59,8 @@ public final class KeyRingUtils { * @param secretKeys secret key ring * @return primary secret key */ - public static PGPSecretKey getPrimarySecretKeyFrom(PGPSecretKeyRing secretKeys) { + @Nullable + public static PGPSecretKey getPrimarySecretKeyFrom(@Nonnull PGPSecretKeyRing secretKeys) { PGPSecretKey secretKey = secretKeys.getSecretKey(); if (secretKey.isMasterKey()) { return secretKey; @@ -72,7 +75,8 @@ public final class KeyRingUtils { * @param keyRing key ring * @return primary public key */ - public static PGPPublicKey requirePrimaryPublicKeyFrom(PGPKeyRing keyRing) { + @Nonnull + public static PGPPublicKey requirePrimaryPublicKeyFrom(@Nonnull PGPKeyRing keyRing) { PGPPublicKey primaryPublicKey = getPrimaryPublicKeyFrom(keyRing); if (primaryPublicKey == null) { throw new NoSuchElementException("Provided PGPKeyRing has no primary public key."); @@ -86,7 +90,8 @@ public final class KeyRingUtils { * @param keyRing key ring * @return primary public key */ - public static PGPPublicKey getPrimaryPublicKeyFrom(PGPKeyRing keyRing) { + @Nullable + public static PGPPublicKey getPrimaryPublicKeyFrom(@Nonnull PGPKeyRing keyRing) { PGPPublicKey primaryPublicKey = keyRing.getPublicKey(); if (primaryPublicKey.isMasterKey()) { return primaryPublicKey; @@ -94,11 +99,28 @@ public final class KeyRingUtils { return null; } - public static PGPPublicKey getPublicKeyFrom(PGPKeyRing keyRing, long subKeyId) { + /** + * Return the public key with the given subKeyId from the keyRing. + * If no such subkey exists, return null. + * @param keyRing key ring + * @param subKeyId subkey id + * @return subkey or null + */ + @Nullable + public static PGPPublicKey getPublicKeyFrom(@Nonnull PGPKeyRing keyRing, long subKeyId) { return keyRing.getPublicKey(subKeyId); } - public static PGPPublicKey requirePublicKeyFrom(PGPKeyRing keyRing, long subKeyId) { + /** + * Require the public key with the given subKeyId from the keyRing. + * If no such subkey exists, throw an {@link NoSuchElementException}. + * + * @param keyRing key ring + * @param subKeyId subkey id + * @return subkey + */ + @Nonnull + public static PGPPublicKey requirePublicKeyFrom(@Nonnull PGPKeyRing keyRing, long subKeyId) { PGPPublicKey publicKey = getPublicKeyFrom(keyRing, subKeyId); if (publicKey == null) { throw new NoSuchElementException("KeyRing does not contain public key with keyID " + Long.toHexString(subKeyId)); @@ -106,7 +128,16 @@ public final class KeyRingUtils { return publicKey; } - public static PGPSecretKey requireSecretKeyFrom(PGPSecretKeyRing keyRing, long subKeyId) { + /** + * Require the secret key with the given secret subKeyId from the secret keyRing. + * If no such subkey exists, throw an {@link NoSuchElementException}. + * + * @param keyRing secret key ring + * @param subKeyId subkey id + * @return secret subkey + */ + @Nonnull + public static PGPSecretKey requireSecretKeyFrom(@Nonnull PGPSecretKeyRing keyRing, long subKeyId) { PGPSecretKey secretKey = keyRing.getSecretKey(subKeyId); if (secretKey == null) { throw new NoSuchElementException("KeyRing does not contain secret key with keyID " + Long.toHexString(subKeyId)); @@ -120,7 +151,8 @@ public final class KeyRingUtils { * @param secretKeys secret key ring * @return public key ring */ - public static PGPPublicKeyRing publicKeyRingFrom(PGPSecretKeyRing secretKeys) { + @Nonnull + public static PGPPublicKeyRing publicKeyRingFrom(@Nonnull PGPSecretKeyRing secretKeys) { List publicKeyList = new ArrayList<>(); Iterator publicKeyIterator = secretKeys.getPublicKeys(); while (publicKeyIterator.hasNext()) { @@ -139,7 +171,9 @@ public final class KeyRingUtils { * * @throws PGPException if something goes wrong (e.g. wrong passphrase) */ - public static PGPPrivateKey unlockSecretKey(PGPSecretKey secretKey, SecretKeyRingProtector protector) throws PGPException { + @Nonnull + public static PGPPrivateKey unlockSecretKey(@Nonnull PGPSecretKey secretKey, @Nonnull SecretKeyRingProtector protector) + throws PGPException { return UnlockSecretKey.unlockSecretKey(secretKey, protector); } @@ -152,6 +186,7 @@ public final class KeyRingUtils { * @throws IOException in case of an io error * @throws PGPException in case of a broken key */ + @Nonnull public static PGPPublicKeyRingCollection keyRingsToKeyRingCollection(@Nonnull PGPPublicKeyRing... rings) throws IOException, PGPException { return new PGPPublicKeyRingCollection(Arrays.asList(rings)); @@ -166,6 +201,7 @@ public final class KeyRingUtils { * @throws IOException in case of an io error * @throws PGPException in case of a broken key */ + @Nonnull public static PGPSecretKeyRingCollection keyRingsToKeyRingCollection(@Nonnull PGPSecretKeyRing... rings) throws IOException, PGPException { return new PGPSecretKeyRingCollection(Arrays.asList(rings)); @@ -194,7 +230,10 @@ public final class KeyRingUtils { * * @throws NoSuchElementException in case that the signed key is not part of the key ring */ - public static T injectCertification(T keyRing, PGPPublicKey certifiedKey, PGPSignature certification) { + @Nonnull + public static T injectCertification(@Nonnull T keyRing, + @Nonnull PGPPublicKey certifiedKey, + @Nonnull PGPSignature certification) { PGPSecretKeyRing secretKeys = null; PGPPublicKeyRing publicKeys; if (keyRing instanceof PGPSecretKeyRing) { @@ -239,7 +278,10 @@ public final class KeyRingUtils { * @param either {@link PGPPublicKeyRing} or {@link PGPSecretKeyRing} * @return key ring with injected certification */ - public static T injectCertification(T keyRing, String userId, PGPSignature certification) { + @Nonnull + public static T injectCertification(@Nonnull T keyRing, + @Nonnull String userId, + @Nonnull PGPSignature certification) { PGPSecretKeyRing secretKeys = null; PGPPublicKeyRing publicKeys; if (keyRing instanceof PGPSecretKeyRing) { @@ -277,7 +319,10 @@ public final class KeyRingUtils { * @param either {@link PGPPublicKeyRing} or {@link PGPSecretKeyRing} * @return key ring with injected user-attribute certification */ - public static T injectCertification(T keyRing, PGPUserAttributeSubpacketVector userAttributes, PGPSignature certification) { + @Nonnull + public static T injectCertification(@Nonnull T keyRing, + @Nonnull PGPUserAttributeSubpacketVector userAttributes, + @Nonnull PGPSignature certification) { PGPSecretKeyRing secretKeys = null; PGPPublicKeyRing publicKeys; if (keyRing instanceof PGPSecretKeyRing) { @@ -317,7 +362,9 @@ public final class KeyRingUtils { * @param either {@link PGPPublicKeyRing} or {@link PGPSecretKeyRing} * @return key ring with injected public key */ - public static T keysPlusPublicKey(T keyRing, PGPPublicKey publicKey) { + @Nonnull + public static T keysPlusPublicKey(@Nonnull T keyRing, + @Nonnull PGPPublicKey publicKey) { if (true) // Is currently broken beyond repair throw new NotYetImplementedException(); @@ -350,7 +397,9 @@ public final class KeyRingUtils { * @param secretKey secret key * @return secret key ring with injected secret key */ - public static PGPSecretKeyRing keysPlusSecretKey(PGPSecretKeyRing secretKeys, PGPSecretKey secretKey) { + @Nonnull + public static PGPSecretKeyRing keysPlusSecretKey(@Nonnull PGPSecretKeyRing secretKeys, + @Nonnull PGPSecretKey secretKey) { return PGPSecretKeyRing.insertSecretKey(secretKeys, secretKey); } @@ -360,7 +409,9 @@ public final class KeyRingUtils { * @param signature signature * @return secret key with the signature injected in its public key */ - public static PGPSecretKey secretKeyPlusSignature(PGPSecretKey secretKey, PGPSignature signature) { + @Nonnull + public static PGPSecretKey secretKeyPlusSignature(@Nonnull PGPSecretKey secretKey, + @Nonnull PGPSignature signature) { PGPPublicKey publicKey = secretKey.getPublicKey(); publicKey = PGPPublicKey.addCertification(publicKey, signature); PGPSecretKey newSecretKey = PGPSecretKey.replacePublicKey(secretKey, publicKey); @@ -380,7 +431,9 @@ public final class KeyRingUtils { * @throws IOException * @throws PGPException */ - public static PGPSecretKeyRing removeSecretKey(PGPSecretKeyRing secretKeys, long secretKeyId) + @Nonnull + public static PGPSecretKeyRing removeSecretKey(@Nonnull PGPSecretKeyRing secretKeys, + long secretKeyId) throws IOException, PGPException { if (secretKeys.getSecretKey(secretKeyId) == null) { throw new NoSuchElementException("PGPSecretKeyRing does not contain secret key " + Long.toHexString(secretKeyId));