diff --git a/CHANGELOG.md b/CHANGELOG.md index 73243f2..a78481a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,10 +5,9 @@ SPDX-License-Identifier: CC0-1.0 # Cert-D-Java Changelog -## 0.1.1-SNAPSHOT +## 0.1.1 - Bump `slf4j` to `1.7.36` -- Bump `logback` to `1.2.11` -- +- Bump `logback` to `1.2.11` ## 0.1.0 -- Initial Release \ No newline at end of file +- Initial Release diff --git a/pgp-cert-d-java/src/main/java/pgp/cert_d/FilenameResolver.java b/pgp-cert-d-java/src/main/java/pgp/cert_d/FilenameResolver.java index a753fd3..81ffc86 100644 --- a/pgp-cert-d-java/src/main/java/pgp/cert_d/FilenameResolver.java +++ b/pgp-cert-d-java/src/main/java/pgp/cert_d/FilenameResolver.java @@ -28,7 +28,8 @@ public class FilenameResolver { * * @param fingerprint fingerprint * @return absolute certificate file location - * @throws BadNameException + * + * @throws BadNameException if the given fingerprint string is not a fingerprint */ public File getCertFileByFingerprint(String fingerprint) throws BadNameException { if (!isFingerprint(fingerprint)) { @@ -41,6 +42,15 @@ public class FilenameResolver { return file; } + /** + * Calculate the file location for the certification addressed using the given special name. + * For known special names, see {@link SpecialNames}. + * + * @param specialName special name (e.g. "trust-root") + * @return absolute certificate file location + * + * @throws BadNameException in case the given special name is not known + */ public File getCertFileBySpecialName(String specialName) throws BadNameException { if (!isSpecialName(specialName)) { throw new BadNameException(); diff --git a/pgp-cert-d-java/src/main/java/pgp/cert_d/LockingMechanism.java b/pgp-cert-d-java/src/main/java/pgp/cert_d/LockingMechanism.java index 520a857..92e196d 100644 --- a/pgp-cert-d-java/src/main/java/pgp/cert_d/LockingMechanism.java +++ b/pgp-cert-d-java/src/main/java/pgp/cert_d/LockingMechanism.java @@ -11,6 +11,9 @@ public interface LockingMechanism { /** * Lock the store for writes. * Readers can continue to use the store and will always see consistent certs. + * + * @throws IOException in case of an IO error + * @throws InterruptedException if the thread gets interrupted */ void lockDirectory() throws IOException, InterruptedException; @@ -19,11 +22,15 @@ public interface LockingMechanism { * Return false without locking the store in case the store was already locked. * * @return true if locking succeeded, false otherwise + * + * @throws IOException in case of an IO error */ boolean tryLockDirectory() throws IOException; /** * Release the directory write-lock acquired via {@link #lockDirectory()}. + * + * @throws IOException in case of an IO error */ void releaseDirectory() throws IOException; diff --git a/pgp-certificate-store/src/main/java/pgp/certificate_store/Certificate.java b/pgp-certificate-store/src/main/java/pgp/certificate_store/Certificate.java index b7aca12..ea3f363 100644 --- a/pgp-certificate-store/src/main/java/pgp/certificate_store/Certificate.java +++ b/pgp-certificate-store/src/main/java/pgp/certificate_store/Certificate.java @@ -21,6 +21,7 @@ public abstract class Certificate { * Return an {@link InputStream} of the binary representation of the certificate. * * @return input stream + * @throws IOException in case of an IO error */ public abstract InputStream getInputStream() throws IOException; @@ -29,8 +30,15 @@ public abstract class Certificate { * The tag is a checksum calculated over the binary representation of the certificate. * * @return tag + * @throws IOException in case of an IO error */ public abstract String getTag() throws IOException; + /** + * Return a {@link Set} containing key-ids of subkeys. + * + * @return subkeys + * @throws IOException in case of an IO error + */ public abstract Set getSubkeyIds() throws IOException; } diff --git a/pgp-certificate-store/src/main/java/pgp/certificate_store/CertificateDirectory.java b/pgp-certificate-store/src/main/java/pgp/certificate_store/CertificateDirectory.java index 29f5998..006970c 100644 --- a/pgp-certificate-store/src/main/java/pgp/certificate_store/CertificateDirectory.java +++ b/pgp-certificate-store/src/main/java/pgp/certificate_store/CertificateDirectory.java @@ -30,6 +30,8 @@ public interface CertificateDirectory { * @return certificate or null * * @throws IOException in case of an IO-error + * @throws BadNameException if the identifier is invalid + * @throws BadDataException if the certificate file contains invalid data */ Certificate getCertificate(String identifier) throws IOException, BadNameException, BadDataException; @@ -44,6 +46,8 @@ public interface CertificateDirectory { * @return changed certificate or null * * @throws IOException in case of an IO-error + * @throws BadNameException if the identifier is invalid + * @throws BadDataException if the certificate file contains invalid data */ Certificate getCertificateIfChanged(String identifier, String tag) throws IOException, BadNameException, BadDataException; @@ -63,6 +67,7 @@ public interface CertificateDirectory { * * @throws IOException in case of an IO-error * @throws InterruptedException in case the inserting thread gets interrupted + * @throws BadDataException if the data stream does not contain valid OpenPGP data */ Certificate insertCertificate(InputStream data, MergeCallback merge) throws IOException, InterruptedException, BadDataException; @@ -83,6 +88,7 @@ public interface CertificateDirectory { * @return merged certificate or null if the store cannot be locked * * @throws IOException in case of an IO-error + * @throws BadDataException if the data stream does not contain valid OpenPGP data */ Certificate tryInsertCertificate(InputStream data, MergeCallback merge) throws IOException, BadDataException; @@ -98,11 +104,15 @@ public interface CertificateDirectory { * This method will block until a write-lock on the store can be acquired. If you cannot afford blocking, * consider to use {@link #tryInsertCertificateBySpecialName(String, InputStream, MergeCallback)} instead. * + * @param specialName special name of the certificate * @param data input stream containing the new certificate instance * @param merge callback for merging with an existing certificate instance * @return merged certificate or null if the store cannot be locked * * @throws IOException in case of an IO-error + * @throws InterruptedException if the thread is interrupted + * @throws BadDataException if the certificate file does not contain valid OpenPGP data + * @throws BadNameException if the special name is unknown */ Certificate insertCertificateBySpecialName(String specialName, InputStream data, MergeCallback merge) throws IOException, InterruptedException, BadDataException, BadNameException; @@ -120,11 +130,14 @@ public interface CertificateDirectory { * However, if the write-lock is available, this method will acquire the lock, write to the store, release the lock * and return the written certificate. * + * @param specialName special name for the certificate * @param data input stream containing the new certificate instance * @param merge callback for merging with an existing certificate instance * @return merged certificate or null if the store cannot be locked * * @throws IOException in case of an IO-error + * @throws BadDataException if the data stream does not contain valid OpenPGP data + * @throws BadNameException if the special name is not known */ Certificate tryInsertCertificateBySpecialName(String specialName, InputStream data, MergeCallback merge) throws IOException, BadDataException, BadNameException; diff --git a/pgp-certificate-store/src/main/java/pgp/certificate_store/MergeCallback.java b/pgp-certificate-store/src/main/java/pgp/certificate_store/MergeCallback.java index a7cee53..9c9f162 100644 --- a/pgp-certificate-store/src/main/java/pgp/certificate_store/MergeCallback.java +++ b/pgp-certificate-store/src/main/java/pgp/certificate_store/MergeCallback.java @@ -19,6 +19,8 @@ public interface MergeCallback { * @param data certificate * @param existing optional already existing copy of the certificate * @return merged certificate + * + * @throws IOException in case of an IO error */ Certificate merge(Certificate data, Certificate existing) throws IOException; diff --git a/pgp-certificate-store/src/main/java/pgp/certificate_store/SubkeyLookup.java b/pgp-certificate-store/src/main/java/pgp/certificate_store/SubkeyLookup.java index 73e396b..55d03e6 100644 --- a/pgp-certificate-store/src/main/java/pgp/certificate_store/SubkeyLookup.java +++ b/pgp-certificate-store/src/main/java/pgp/certificate_store/SubkeyLookup.java @@ -16,6 +16,8 @@ public interface SubkeyLookup { * * @param subkeyId subkey id * @return fingerprint of the certificate + * + * @throws IOException in case of an IO error */ Set getCertificateFingerprintsForSubkeyId(long subkeyId) throws IOException; @@ -25,6 +27,7 @@ public interface SubkeyLookup { * * @param certificate certificate fingerprint * @param subkeyIds subkey ids + * * @throws IOException in case of an IO error */ void storeCertificateSubkeyIds(String certificate, List subkeyIds) throws IOException;