mirror of
https://codeberg.org/PGPainless/cert-d-java.git
synced 2024-12-22 13:47:59 +01:00
Add javadoc for interfaces
This commit is contained in:
parent
a956aec5fc
commit
662f96ff77
GPG key ID:
62BEE9264BF17311
4 changed files with 279 additions and 0 deletions
|
|
@ -17,12 +17,23 @@ import java.util.Iterator;
|
|||
import java.util.List;
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* Implementation of the Shared PGP Certificate Directory.
|
||||
*
|
||||
* @see <a href="https://sequoia-pgp.gitlab.io/pgp-cert-d/">Shared PGP Certificate Directory Specification</a>
|
||||
*/
|
||||
public class PGPCertificateDirectory
|
||||
implements ReadOnlyPGPCertificateDirectory, WritingPGPCertificateDirectory, SubkeyLookup {
|
||||
|
||||
final Backend backend;
|
||||
final SubkeyLookup subkeyLookup;
|
||||
|
||||
/**
|
||||
* Constructor for a PGP certificate directory.
|
||||
*
|
||||
* @param backend storage backend
|
||||
* @param subkeyLookup subkey lookup mechanism to map subkey-ids to certificates
|
||||
*/
|
||||
public PGPCertificateDirectory(Backend backend, SubkeyLookup subkeyLookup) {
|
||||
this.backend = backend;
|
||||
this.subkeyLookup = subkeyLookup;
|
||||
|
|
@ -189,30 +200,119 @@ public class PGPCertificateDirectory
|
|||
subkeyLookup.storeCertificateSubkeyIds(certificate, subkeyIds);
|
||||
}
|
||||
|
||||
/**
|
||||
* Storage backend.
|
||||
*/
|
||||
public interface Backend {
|
||||
|
||||
/**
|
||||
* Get the locking mechanism to write-lock the backend.
|
||||
*
|
||||
* @return lock
|
||||
*/
|
||||
LockingMechanism getLock();
|
||||
|
||||
/**
|
||||
* Read a {@link Certificate} by its OpenPGP fingerprint.
|
||||
*
|
||||
* @param fingerprint fingerprint
|
||||
* @return certificate
|
||||
*
|
||||
* @throws BadNameException if the fingerprint is malformed
|
||||
* @throws IOException in case of an IO error
|
||||
* @throws BadDataException if the certificate contains bad data
|
||||
*/
|
||||
Certificate readByFingerprint(String fingerprint) throws BadNameException, IOException, BadDataException;
|
||||
|
||||
/**
|
||||
* Read a {@link Certificate} or {@link pgp.certificate_store.certificate.Key} by the given special name.
|
||||
*
|
||||
* @param specialName special name
|
||||
* @return certificate or key
|
||||
*
|
||||
* @throws BadNameException if the special name is not known
|
||||
* @throws IOException in case of an IO error
|
||||
* @throws BadDataException if the certificate contains bad data
|
||||
*/
|
||||
KeyMaterial readBySpecialName(String specialName) throws BadNameException, IOException, BadDataException;
|
||||
|
||||
/**
|
||||
* Return an {@link Iterator} of all {@link Certificate Certificates} in the store, except for certificates
|
||||
* stored under a special name.
|
||||
*
|
||||
* @return iterator
|
||||
*/
|
||||
Iterator<Certificate> readItems();
|
||||
|
||||
/**
|
||||
* Insert a {@link pgp.certificate_store.certificate.Key} or {@link Certificate} as trust-root.
|
||||
*
|
||||
* @param data input stream containing the key material
|
||||
* @param merge callback to merge the key material with existing key material
|
||||
* @return merged or inserted key material
|
||||
*
|
||||
* @throws BadDataException if the data stream or existing key material contains bad data
|
||||
* @throws IOException in case of an IO error
|
||||
*/
|
||||
KeyMaterial doInsertTrustRoot(InputStream data, KeyMaterialMerger merge)
|
||||
throws BadDataException, IOException;
|
||||
|
||||
/**
|
||||
* Insert a {@link Certificate} identified by its fingerprint into the directory.
|
||||
*
|
||||
* @param data input stream containing the certificate data
|
||||
* @param merge callback to merge the certificate with existing key material
|
||||
* @return merged or inserted certificate
|
||||
*
|
||||
* @throws IOException in case of an IO error
|
||||
* @throws BadDataException if the data stream or existing certificate contains bad data
|
||||
*/
|
||||
Certificate doInsert(InputStream data, KeyMaterialMerger merge)
|
||||
throws IOException, BadDataException;
|
||||
|
||||
/**
|
||||
* Insert a {@link pgp.certificate_store.certificate.Key} or {@link Certificate} under the given special name.
|
||||
*
|
||||
* @param specialName special name to identify the key material with
|
||||
* @param data data stream containing the key or certificate
|
||||
* @param merge callback to merge the key/certificate with existing key material
|
||||
* @return certificate component of the merged or inserted key material
|
||||
*
|
||||
* @throws IOException in case of an IO error
|
||||
* @throws BadDataException if the data stream or existing key material contains bad data
|
||||
* @throws BadNameException if the special name is not known
|
||||
*/
|
||||
Certificate doInsertWithSpecialName(String specialName, InputStream data, KeyMaterialMerger merge)
|
||||
throws IOException, BadDataException, BadNameException;
|
||||
|
||||
/**
|
||||
* Calculate the tag of the certificate with the given fingerprint.
|
||||
*
|
||||
* @param fingerprint fingerprint
|
||||
* @return tag
|
||||
*
|
||||
* @throws BadNameException if the fingerprint is malformed
|
||||
* @throws IOException in case of an IO error
|
||||
* @throws IllegalArgumentException if the certificate does not exist
|
||||
*/
|
||||
Long getTagForFingerprint(String fingerprint) throws BadNameException, IOException;
|
||||
|
||||
/**
|
||||
* Calculate the tag of the certificate identified by the given special name.
|
||||
*
|
||||
* @param specialName special name
|
||||
* @return tag
|
||||
*
|
||||
* @throws BadNameException if the special name is not known
|
||||
* @throws IOException in case of an IO error
|
||||
* @throws IllegalArgumentException if the certificate or key does not exist
|
||||
*/
|
||||
Long getTagForSpecialName(String specialName) throws BadNameException, IOException;
|
||||
}
|
||||
|
||||
/**
|
||||
* Interface for a write-locking mechanism.
|
||||
*/
|
||||
public interface LockingMechanism {
|
||||
|
||||
/**
|
||||
|
|
@ -234,6 +334,11 @@ public class PGPCertificateDirectory
|
|||
*/
|
||||
boolean tryLockDirectory() throws IOException;
|
||||
|
||||
/**
|
||||
* Return true if the lock is in locked state.
|
||||
*
|
||||
* @return true if locked
|
||||
*/
|
||||
boolean isLocked();
|
||||
|
||||
/**
|
||||
|
|
|
|||
|
|
@ -11,27 +11,113 @@ import pgp.certificate_store.exception.BadNameException;
|
|||
import java.io.IOException;
|
||||
import java.util.Iterator;
|
||||
|
||||
/**
|
||||
* Interface for a read-only OpenPGP certificate directory.
|
||||
*/
|
||||
public interface ReadOnlyPGPCertificateDirectory {
|
||||
|
||||
/**
|
||||
* Get the trust-root certificate. This is a certificate which is stored under the special name
|
||||
* <pre>trust-root</pre>.
|
||||
* If no such certificate is found, <pre>null</pre> is returned.
|
||||
*
|
||||
* @return trust-root certificate
|
||||
*
|
||||
* @throws IOException in case of an IO error
|
||||
* @throws BadDataException if the certificate contains bad data
|
||||
*/
|
||||
Certificate getTrustRootCertificate()
|
||||
throws IOException, BadDataException;
|
||||
|
||||
/**
|
||||
* Get the trust-root certificate if it has changed.
|
||||
* This method uses the <pre>tag</pre> to calculate if the certificate might have changed.
|
||||
* If the computed tag equals the given tag, the certificate has not changed, so <pre>null</pre> is returned.
|
||||
* Otherwise. the changed certificate is returned.
|
||||
*
|
||||
* @param tag tag
|
||||
* @return changed certificate, or null if the certificate is unchanged or not found.
|
||||
*
|
||||
* @throws IOException in case of an IO error
|
||||
* @throws BadDataException if the certificate contains bad data
|
||||
*/
|
||||
Certificate getTrustRootCertificateIfChanged(long tag)
|
||||
throws IOException, BadDataException;
|
||||
|
||||
/**
|
||||
* Get the certificate identified by the given fingerprint.
|
||||
* If no such certificate is found, return <pre>null</pre>.
|
||||
*
|
||||
* @param fingerprint lower-case fingerprint of the certificate
|
||||
* @return certificate or null if no such certificate has been found
|
||||
*
|
||||
* @throws IOException in case of an IO error
|
||||
* @throws BadNameException if the fingerprint is malformed
|
||||
* @throws BadDataException if the certificate contains bad data
|
||||
*/
|
||||
Certificate getByFingerprint(String fingerprint)
|
||||
throws IOException, BadNameException, BadDataException;
|
||||
|
||||
/**
|
||||
* Get the certificate identified by the given fingerprint if it has changed.
|
||||
* This method uses the <pre>tag</pre> to calculate, if the certificate might have changed.
|
||||
* If the computed tag equals the given tag, the certificate has not changed, so <pre>null</pre> is returned.
|
||||
* Otherwise, the changed certificate is returned.
|
||||
*
|
||||
* @param fingerprint lower-case fingerprint of the certificate
|
||||
* @param tag tag
|
||||
* @return certificate or null if the certificate has not been changed or has not been found
|
||||
*
|
||||
* @throws IOException in case of an IO error
|
||||
* @throws BadNameException if the fingerprint is malformed
|
||||
* @throws BadDataException if the certificate contains bad data
|
||||
*/
|
||||
Certificate getByFingerprintIfChanged(String fingerprint, long tag)
|
||||
throws IOException, BadNameException, BadDataException;
|
||||
|
||||
/**
|
||||
* Get the certificate identified by the given special name.
|
||||
* If no such certificate is found, <pre>null</pre> is returned.
|
||||
*
|
||||
* @param specialName special name
|
||||
* @return certificate or null
|
||||
*
|
||||
* @throws IOException in case of an IO error
|
||||
* @throws BadNameException if the special name is not known
|
||||
* @throws BadDataException if the certificate contains bad data
|
||||
*/
|
||||
Certificate getBySpecialName(String specialName)
|
||||
throws IOException, BadNameException, BadDataException;
|
||||
|
||||
/**
|
||||
* Get the certificate identified by the given special name or null, if it has not been changed.
|
||||
* This method uses the <pre>tag</pre> to calculate, if the certificate might have changed.
|
||||
* If the computed tag equals the given tag, the certificate has not changed, so <pre>null</pre> is returned.
|
||||
* Otherwise, the changed certificate is returned.
|
||||
*
|
||||
* @param specialName special name
|
||||
* @param tag tag
|
||||
* @return certificate or null
|
||||
*
|
||||
* @throws IOException in case of an IO error
|
||||
* @throws BadNameException if the special name is not known
|
||||
* @throws BadDataException if the certificate contains bad data
|
||||
*/
|
||||
Certificate getBySpecialNameIfChanged(String specialName, long tag)
|
||||
throws IOException, BadNameException, BadDataException;
|
||||
|
||||
/**
|
||||
* Get all certificates in the directory, except for certificates which are stored by special name.
|
||||
*
|
||||
* @return iterator of certificates
|
||||
*/
|
||||
Iterator<Certificate> items();
|
||||
|
||||
/**
|
||||
* Get the fingerprints of all certificates in the directory, except for certificates which are stored by
|
||||
* special name.
|
||||
*
|
||||
* @return iterator of fingerprints
|
||||
*/
|
||||
Iterator<String> fingerprints();
|
||||
}
|
||||
|
|
|
|||
|
|
@ -13,26 +13,113 @@ import pgp.certificate_store.exception.BadNameException;
|
|||
import java.io.IOException;
|
||||
import java.io.InputStream;
|
||||
|
||||
/**
|
||||
* Interface for a writing OpenPGP certificate directory.
|
||||
*/
|
||||
public interface WritingPGPCertificateDirectory {
|
||||
|
||||
/**
|
||||
* Return the certificate or key identified by the special name <pre>trust-root</pre>.
|
||||
*
|
||||
* @return trust-root key or certificate
|
||||
*
|
||||
* @throws IOException in case of an IO error
|
||||
* @throws BadDataException if the certificate contains bad data
|
||||
*/
|
||||
KeyMaterial getTrustRoot()
|
||||
throws IOException, BadDataException;
|
||||
|
||||
/**
|
||||
* Insert a key or certificate under the special name <pre>trust-root</pre>.
|
||||
* This method blocks until the key material has been written.
|
||||
*
|
||||
* @param data input stream containing the key or certificate
|
||||
* @param merge key material merger to merge the key or certificate with existing key material
|
||||
* @return the merged or inserted key or certificate
|
||||
*
|
||||
* @throws IOException in case of an IO error
|
||||
* @throws BadDataException if the data stream or the existing trust-root key material contains bad data
|
||||
* @throws InterruptedException if the thread is interrupted
|
||||
*/
|
||||
KeyMaterial insertTrustRoot(InputStream data, KeyMaterialMerger merge)
|
||||
throws IOException, BadDataException, InterruptedException;
|
||||
|
||||
/**
|
||||
* Insert a key or certificate under the special name <pre>trust-root</pre>.
|
||||
* Contrary to {@link #insertTrustRoot(InputStream, KeyMaterialMerger)}, this method does not block.
|
||||
* Instead, it returns null if the write-lock cannot be obtained.
|
||||
*
|
||||
* @param data input stream containing the key or certificate
|
||||
* @param merge key material merger to merge the key or certificate with existing key material
|
||||
* @return the merged or inserted key or certificate, or null if the write-lock cannot be obtained
|
||||
*
|
||||
* @throws IOException in case of an IO error
|
||||
* @throws BadDataException if the thread is interrupted
|
||||
*/
|
||||
KeyMaterial tryInsertTrustRoot(InputStream data, KeyMaterialMerger merge)
|
||||
throws IOException, BadDataException;
|
||||
|
||||
/**
|
||||
* Insert a certificate identified by its fingerprint.
|
||||
* This method blocks until the certificate has been written.
|
||||
*
|
||||
* @param data input stream containing the certificate data
|
||||
* @param merge merge callback to merge the certificate with existing certificate material
|
||||
* @return the merged or inserted certificate
|
||||
*
|
||||
* @throws IOException in case of an IO error
|
||||
* @throws BadDataException if the data stream or existing certificate contains bad data
|
||||
* @throws InterruptedException if the thread is interrupted
|
||||
*/
|
||||
Certificate insert(InputStream data, KeyMaterialMerger merge)
|
||||
throws IOException, BadDataException, InterruptedException;
|
||||
|
||||
/**
|
||||
* Insert a certificate identified by its fingerprint.
|
||||
* Contrary to {@link #insert(InputStream, KeyMaterialMerger)}, this method does not block.
|
||||
* Instead, it returns null if the write-lock cannot be obtained.
|
||||
*
|
||||
* @param data input stream containing the certificate data
|
||||
* @param merge merge callback to merge the certificate with existing certificate material
|
||||
* @return the merged or inserted certificate
|
||||
*
|
||||
* @throws IOException in case of an IO error
|
||||
* @throws BadDataException if the data stream or existing certificate contains bad data
|
||||
*/
|
||||
Certificate tryInsert(InputStream data, KeyMaterialMerger merge)
|
||||
throws IOException, BadDataException;
|
||||
|
||||
/**
|
||||
* Insert a certificate or key under the given special name.
|
||||
* This method blocks until the certificate/key has been written.
|
||||
*
|
||||
* @param specialName special name under which the key material shall be inserted
|
||||
* @param data input stream containing the key/certificate data
|
||||
* @param merge callback to merge the key/certificate with existing key material
|
||||
* @return certificate component of the merged or inserted key material data
|
||||
*
|
||||
* @throws IOException in case of an IO error
|
||||
* @throws BadDataException if the data stream or the existing certificate contains bad data
|
||||
* @throws BadNameException if the special name is not known
|
||||
* @throws InterruptedException if the thread is interrupted
|
||||
*/
|
||||
Certificate insertWithSpecialName(String specialName, InputStream data, KeyMaterialMerger merge)
|
||||
throws IOException, BadDataException, BadNameException, InterruptedException;
|
||||
|
||||
/**
|
||||
* Insert a certificate or key under the given special name.
|
||||
* Contrary to {@link #insertWithSpecialName(String, InputStream, KeyMaterialMerger)}, this method does not block.
|
||||
* Instead, it returns null if the write-lock cannot be obtained.
|
||||
*
|
||||
* @param specialName special name under which the key material shall be inserted
|
||||
* @param data input stream containing the key material
|
||||
* @param merge callback to merge the key/certificate with existing key material
|
||||
* @return certificate component of the merged or inserted key material
|
||||
*
|
||||
* @throws IOException in case of an IO error
|
||||
* @throws BadDataException if the data stream or existing key material contains bad data
|
||||
* @throws BadNameException if the special name is not known
|
||||
*/
|
||||
Certificate tryInsertWithSpecialName(String specialName, InputStream data, KeyMaterialMerger merge)
|
||||
throws IOException, BadDataException, BadNameException;
|
||||
|
||||
|
|
|
|||
|
|
@ -15,6 +15,7 @@ public interface KeyMaterialReaderBackend {
|
|||
* Read a {@link KeyMaterial} (either {@link Key} or {@link Certificate}) from the given {@link InputStream}.
|
||||
*
|
||||
* @param data input stream containing the binary representation of the key.
|
||||
* @param tag tag for the key material. Might be null.
|
||||
* @return key or certificate object
|
||||
*
|
||||
* @throws IOException in case of an IO error
|
||||
|
|
|
|||
Loading…
Reference in a new issue