diff --git a/vks-java/src/main/java/pgp/vks/client/RequestVerify.java b/vks-java/src/main/java/pgp/vks/client/RequestVerify.java index 3d7fb5d..e28f69f 100644 --- a/vks-java/src/main/java/pgp/vks/client/RequestVerify.java +++ b/vks-java/src/main/java/pgp/vks/client/RequestVerify.java @@ -9,20 +9,54 @@ import java.util.Arrays; import java.util.List; import java.util.Map; +/** + * Request email verification for email addresses of user-ids on a certificate. + */ public interface RequestVerify { + /** + * Request email verification for the given email address. + * + * @param emailAddress email address + * @return builder + */ default ForEmailAddresses forEmailAddress(String emailAddress) { return forEmailAddresses(emailAddress); } + /** + * Request email verification for one or more email addresses. + * + * @param emailAddresses email addresses + * @return builder + */ ForEmailAddresses forEmailAddresses(String... emailAddresses); interface ForEmailAddresses { + /** + * Execute the verification request using the given 
token
, retrieved earlier by uploading the + * certificate to the server. + * + * @param token access token to authorize the request + * @return servers successful response + * + * @throws IOException in case of an error + */ default Response execute(String token) throws IOException { return execute(token, Arrays.asList("en_US", "en_GB")); } + /** + * Execute the verification request using the given 
token
, retrieved earlier by uploading the + * certificate to the server. + * + * @param token access token to authorize the request + * @param locale list of preferred locales for the verification emails + * @return servers successful response + * + * @throws IOException in case of an error + */ Response execute(String token, List locale) throws IOException; } @@ -41,14 +75,29 @@ public interface RequestVerify { this.token = token; } + /** + * Return the uppercase OpenPGP fingerprint of the certificate. + * + * @return fingerprint + */ public String getKeyFingerprint() { return keyFingerprint; } + /** + * Return a map of {@link Status States} of email addresses of user-ids on the certificate after requesting + * verification. + * @return status map + */ public Map getStatus() { return status; } + /** + * Return an access token to be used to make further requests to the API. + * + * @return token + */ public String getToken() { return token; } diff --git a/vks-java/src/main/java/pgp/vks/client/Status.java b/vks-java/src/main/java/pgp/vks/client/Status.java index a8ead89..5fa35d3 100644 --- a/vks-java/src/main/java/pgp/vks/client/Status.java +++ b/vks-java/src/main/java/pgp/vks/client/Status.java @@ -4,6 +4,9 @@ package pgp.vks.client; +/** + * Enum representing different states an email address of a user-id on a certificate can be in. + */ public enum Status { /** diff --git a/vks-java/src/main/java/pgp/vks/client/VKSImpl.java b/vks-java/src/main/java/pgp/vks/client/VKSImpl.java index b760c88..e273ab9 100644 --- a/vks-java/src/main/java/pgp/vks/client/VKSImpl.java +++ b/vks-java/src/main/java/pgp/vks/client/VKSImpl.java @@ -27,6 +27,11 @@ public class VKSImpl implements VKS { this.api = new URLMapper(vksService); } + /** + * Return a {@link VKSImpl} instance targeting the 
https://keys.openpgp.org
VKS. + * + * @return VKS instance + */ @SneakyThrows public static VKS keysDotOpenPgpDotOrg() { return new VKSImpl("https://keys.openpgp.org"); diff --git a/vks-java/src/main/java/pgp/vks/client/exception/CertCannotBePublishedException.java b/vks-java/src/main/java/pgp/vks/client/exception/CertCannotBePublishedException.java index 07b5fc3..2e9eca1 100644 --- a/vks-java/src/main/java/pgp/vks/client/exception/CertCannotBePublishedException.java +++ b/vks-java/src/main/java/pgp/vks/client/exception/CertCannotBePublishedException.java @@ -6,6 +6,9 @@ package pgp.vks.client.exception; import java.net.ConnectException; +/** + * Exception gets thrown when a public key certificate cannot be published for some reason. + */ public class CertCannotBePublishedException extends ConnectException { public CertCannotBePublishedException(String errorMessage) { diff --git a/vks-java/src/main/java/pgp/vks/client/exception/CertNotFoundException.java b/vks-java/src/main/java/pgp/vks/client/exception/CertNotFoundException.java index 039eea7..e18056d 100644 --- a/vks-java/src/main/java/pgp/vks/client/exception/CertNotFoundException.java +++ b/vks-java/src/main/java/pgp/vks/client/exception/CertNotFoundException.java @@ -6,12 +6,11 @@ package pgp.vks.client.exception; import java.net.ConnectException; +/** + * Exception gets thrown when the queried OpenPGP certificate cannot be found on the server. + */ public class CertNotFoundException extends ConnectException { - public CertNotFoundException() { - super(); - } - public CertNotFoundException(String message) { super(message); } diff --git a/vks-java/src/main/java/pgp/vks/client/exception/UnsupportedApiException.java b/vks-java/src/main/java/pgp/vks/client/exception/UnsupportedApiException.java index 7f017b6..a1e399f 100644 --- a/vks-java/src/main/java/pgp/vks/client/exception/UnsupportedApiException.java +++ b/vks-java/src/main/java/pgp/vks/client/exception/UnsupportedApiException.java @@ -4,6 +4,10 @@ package pgp.vks.client.exception; +/** + * Exception gets thrown when an unsupported API {@link pgp.vks.client.VKS.Version} is used. + * E.g. user wants to use some command using v2 API, but implementation only supports v1. + */ public class UnsupportedApiException extends RuntimeException { public UnsupportedApiException(String message) { diff --git a/vks-java/src/main/java/pgp/vks/client/v1/dto/ErrorResponseDto.java b/vks-java/src/main/java/pgp/vks/client/v1/dto/ErrorResponseDto.java index 3208791..71567c0 100644 --- a/vks-java/src/main/java/pgp/vks/client/v1/dto/ErrorResponseDto.java +++ b/vks-java/src/main/java/pgp/vks/client/v1/dto/ErrorResponseDto.java @@ -6,6 +6,11 @@ package pgp.vks.client.v1.dto; import com.fasterxml.jackson.annotation.JsonProperty; +/** + * Error response that gets returned by the server if a POST request fails. + * + * @see VKS API Documentation + */ public class ErrorResponseDto { private final String error; @@ -14,6 +19,11 @@ public class ErrorResponseDto { this.error = error; } + /** + * Return the error message. + * + * @return error message + */ @JsonProperty("error") public String getError() { return error; diff --git a/vks-java/src/main/java/pgp/vks/client/v1/dto/UploadRequestDto.java b/vks-java/src/main/java/pgp/vks/client/v1/dto/UploadRequestDto.java index e351a39..865deb1 100644 --- a/vks-java/src/main/java/pgp/vks/client/v1/dto/UploadRequestDto.java +++ b/vks-java/src/main/java/pgp/vks/client/v1/dto/UploadRequestDto.java @@ -14,6 +14,11 @@ import java.io.IOException; import java.io.InputStream; import java.nio.charset.Charset; +/** + * Request for uploading a certificate to the VKS. + * + * @see VKS API Documentation + */ public class UploadRequestDto { private static final byte[] ARMOR_HEADER = "-----BEGIN PGP PUBLIC KEY BLOCK-----".getBytes(Charset.forName("UTF8")); @@ -24,6 +29,15 @@ public class UploadRequestDto { this.keytext = keytext; } + /** + * Create an {@link UploadRequestDto} from an ASCII armored or binary OpenPGP certificate which is read from the + * given 
certInStream
. + * + * @param certInStream {@link InputStream} containing the ASCII armored or binary OpenPGP certificate + * @return request DTO + * + * @throws IOException in case of an IO error + */ public static UploadRequestDto fromInputStream(InputStream certInStream) throws IOException { ByteArrayOutputStream certBuf = new ByteArrayOutputStream(); Streams.pipeAll(certInStream, certBuf); @@ -31,11 +45,26 @@ public class UploadRequestDto { return fromBytes(certBuf.toByteArray()); } + /** + * Create an {@link UploadRequestDto} from an ASCII armored or binary OpenPGP certificate which is read from the + * given 
keytext
byte array. + * + * @param keytext byte array containing the ASCII armored or binary OpenPGP certificate + * @return request DTO + */ public static UploadRequestDto fromBytes(byte[] keytext) { String armoredOrBase64 = new String(base64IfNecessary(keytext)); return new UploadRequestDto(armoredOrBase64); } + /** + * Prepare a serialized OpenPGP certificate for upload. + * If the given 
certBytes
contain an ASCII armored OpenPGP certificate, do nothing. + * Otherwise, consider the bytes to be the binary representation of an OpenPGP certificate and wrap it in Base64 encoding. + * + * @param certBytes certificate bytes + * @return Unmodified ASCII armored, or base64 encoded binary OpenPGP certificate + */ private static byte[] base64IfNecessary(byte[] certBytes) { if (!Arrays.areEqual(certBytes, 0, ARMOR_HEADER.length, ARMOR_HEADER, 0, ARMOR_HEADER.length)) { certBytes = Base64.encode(certBytes); diff --git a/vks-java/src/main/java/pgp/vks/client/v1/dto/UploadResponseDto.java b/vks-java/src/main/java/pgp/vks/client/v1/dto/UploadResponseDto.java index b2298c9..03d132b 100644 --- a/vks-java/src/main/java/pgp/vks/client/v1/dto/UploadResponseDto.java +++ b/vks-java/src/main/java/pgp/vks/client/v1/dto/UploadResponseDto.java @@ -11,6 +11,11 @@ import pgp.vks.client.Upload; import java.util.HashMap; import java.util.Map; +/** + * The VKS servers response to a successful upload. + * + * @see VKS API Documentation + */ public class UploadResponseDto { private final String key_fpr; @@ -25,21 +30,41 @@ public class UploadResponseDto { this.token = token; } + /** + * Uppercase fingerprint of the uploaded OpenPGP certificate. + * + * @return fingerprint + */ @JsonProperty("key_fpr") public String getKeyFingerprint() { return key_fpr; } + /** + * Access token which can be used for a limited time to request verification emails for user-ids on the certificate. + * + * @return access token + */ @JsonProperty("token") public String getToken() { return token; } + /** + * Map of {@link Status States} of email addresses of user-ids on the certificate. + * + * @return email status map + */ @JsonProperty("status") public Map getStatus() { return new HashMap<>(status); } + /** + * Convert the DTO into an entity. + * + * @return entity + */ public Upload.Response toEntity() { return new Upload.Response(getKeyFingerprint(), getStatus(), getToken()); } diff --git a/vks-java/src/main/java/pgp/vks/client/v1/dto/VerificationRequestDto.java b/vks-java/src/main/java/pgp/vks/client/v1/dto/VerificationRequestDto.java index 999be64..47c2608 100644 --- a/vks-java/src/main/java/pgp/vks/client/v1/dto/VerificationRequestDto.java +++ b/vks-java/src/main/java/pgp/vks/client/v1/dto/VerificationRequestDto.java @@ -8,6 +8,11 @@ import com.fasterxml.jackson.annotation.JsonProperty; import java.util.List; +/** + * Request for email verification of one or more unpublished/pending user-ids. + * + * @see VKS API Documentation + */ public class VerificationRequestDto { private final String token; @@ -22,16 +27,31 @@ public class VerificationRequestDto { this.locale = locale; } + /** + * Return the token which was previously required by uploading a certificate using an {@link UploadRequestDto}. + * + * @return access token used to authenticate the request + */ @JsonProperty("token") public String getToken() { return token; } + /** + * {@link List} of email addresses for which to request email verification. + * + * @return email addresses + */ @JsonProperty("addresses") public List getAddresses() { return addresses; } + /** + * {@link List} of preferred locales for the verification mails. + * + * @return locale list + */ @JsonProperty("locale") public List getLocale() { return locale; diff --git a/vks-java/src/main/java/pgp/vks/client/v1/dto/VerificationResponseDto.java b/vks-java/src/main/java/pgp/vks/client/v1/dto/VerificationResponseDto.java index 78a9597..bbd6e14 100644 --- a/vks-java/src/main/java/pgp/vks/client/v1/dto/VerificationResponseDto.java +++ b/vks-java/src/main/java/pgp/vks/client/v1/dto/VerificationResponseDto.java @@ -10,6 +10,11 @@ import pgp.vks.client.Status; import java.util.Map; +/** + * VKS servers response to a successful verification request. + * + * @see VKS API Documentation + */ public class VerificationResponseDto { private final String key_fpr; @@ -24,21 +29,41 @@ public class VerificationResponseDto { this.token = token; } + /** + * Uppercase OpenPGP fingerprint of the certificate. + * + * @return fingerprint + */ @JsonProperty("key_fpr") public String getKeyFingerprint() { return key_fpr; } + /** + * Access token which can be used to authenticate further verification requests. + * + * @return token + */ @JsonProperty("token") public String getToken() { return token; } + /** + * Map of {@link Status States} of email addresses of user-ids on the certificate. + * + * @return email address status map + */ @JsonProperty("status") public Map getStatus() { return status; } + /** + * Convert this DTO to an entity. + * + * @return entity + */ public RequestVerify.Response toEntity() { return new RequestVerify.Response(getKeyFingerprint(), getStatus(), getToken()); }