From d00c6072bf15896c3254d46a17113f03079d277e Mon Sep 17 00:00:00 2001 From: Max Lambrecht Date: Mon, 15 Jun 2020 11:18:16 -0300 Subject: [PATCH] Adding and improving javadocs. Removing unused code. Signed-off-by: Max Lambrecht --- .../src/main/java/spiffe/Algorithm.java | 6 ++ .../main/java/spiffe/bundle/BundleSource.java | 2 +- .../spiffe/bundle/jwtbundle/JwtBundle.java | 2 +- .../spiffe/bundle/jwtbundle/JwtBundleSet.java | 2 +- .../spiffe/bundle/x509bundle/X509Bundle.java | 2 +- .../bundle/x509bundle/X509BundleSet.java | 2 +- .../exception/AuthorityNotFoundException.java | 4 +- .../exception/BundleNotFoundException.java | 4 +- .../spiffe/exception/JwtBundleException.java | 6 +- .../spiffe/exception/JwtSourceException.java | 6 +- .../spiffe/exception/JwtSvidException.java | 4 - .../SocketEndpointAddressException.java | 4 - .../exception/X509ContextException.java | 6 +- .../spiffe/exception/X509SourceException.java | 6 +- .../spiffe/exception/X509SvidException.java | 5 -- .../main/java/spiffe/spiffeid/SpiffeId.java | 10 ++- .../java/spiffe/spiffeid/SpiffeIdUtils.java | 62 +++---------- .../java/spiffe/spiffeid/TrustDomain.java | 33 ++++--- .../java/spiffe/svid/jwtsvid/JwtSvid.java | 23 ++--- .../spiffe/svid/jwtsvid/JwtSvidSource.java | 6 +- .../java/spiffe/svid/x509svid/X509Svid.java | 6 +- .../spiffe/svid/x509svid/X509SvidSource.java | 2 +- .../svid/x509svid/X509SvidValidator.java | 3 +- .../main/java/spiffe/workloadapi/Address.java | 2 +- .../java/spiffe/workloadapi/JwtSource.java | 3 +- .../main/java/spiffe/workloadapi/Watcher.java | 2 +- .../spiffe/workloadapi/WorkloadApiClient.java | 18 ++-- .../java/spiffe/workloadapi/X509Context.java | 2 +- .../java/spiffe/workloadapi/X509Source.java | 5 +- .../workloadapi/retry/BackoffPolicy.java | 9 +- .../workloadapi/retry/RetryHandler.java | 2 +- .../spiffe/spiffeid/SpiffeIdUtilsTest.java | 87 +------------------ 32 files changed, 99 insertions(+), 237 deletions(-) diff --git a/java-spiffe-core/src/main/java/spiffe/Algorithm.java b/java-spiffe-core/src/main/java/spiffe/Algorithm.java index 48cb345..eab14e9 100644 --- a/java-spiffe-core/src/main/java/spiffe/Algorithm.java +++ b/java-spiffe-core/src/main/java/spiffe/Algorithm.java @@ -4,6 +4,9 @@ import java.util.Collections; import java.util.HashSet; import java.util.Set; +/** + * Represents JWT Algorithms. + */ public enum Algorithm { /** @@ -66,6 +69,9 @@ public enum Algorithm { return name; } + /** + * Represents families of algorithms. + */ public enum Family { RSA("RSA", RS256, RS384, RS512, PS256, PS384, PS512), EC("EC", ES256, ES384, ES512), diff --git a/java-spiffe-core/src/main/java/spiffe/bundle/BundleSource.java b/java-spiffe-core/src/main/java/spiffe/bundle/BundleSource.java index d22a2ea..08fc13a 100644 --- a/java-spiffe-core/src/main/java/spiffe/bundle/BundleSource.java +++ b/java-spiffe-core/src/main/java/spiffe/bundle/BundleSource.java @@ -6,7 +6,7 @@ import spiffe.exception.BundleNotFoundException; import spiffe.spiffeid.TrustDomain; /** - * A BundleSource represents a source of bundles of type T keyed by trust domain. + * Represents a source of bundles of type T keyed by trust domain. */ public interface BundleSource { diff --git a/java-spiffe-core/src/main/java/spiffe/bundle/jwtbundle/JwtBundle.java b/java-spiffe-core/src/main/java/spiffe/bundle/jwtbundle/JwtBundle.java index 36f9808..1909f6d 100644 --- a/java-spiffe-core/src/main/java/spiffe/bundle/jwtbundle/JwtBundle.java +++ b/java-spiffe-core/src/main/java/spiffe/bundle/jwtbundle/JwtBundle.java @@ -27,7 +27,7 @@ import java.util.Map; import java.util.concurrent.ConcurrentHashMap; /** - * A JwtBundle represents a collection of trusted JWT authorities (Public Keys) for a trust domain. + * Represents a collection of trusted JWT authorities (Public Keys) for a trust domain. */ @Value public class JwtBundle implements BundleSource { diff --git a/java-spiffe-core/src/main/java/spiffe/bundle/jwtbundle/JwtBundleSet.java b/java-spiffe-core/src/main/java/spiffe/bundle/jwtbundle/JwtBundleSet.java index d71c287..e52c5b1 100644 --- a/java-spiffe-core/src/main/java/spiffe/bundle/jwtbundle/JwtBundleSet.java +++ b/java-spiffe-core/src/main/java/spiffe/bundle/jwtbundle/JwtBundleSet.java @@ -14,7 +14,7 @@ import java.util.Map; import java.util.concurrent.ConcurrentHashMap; /** - * A JwtBundleSet represents a set of JWT bundles keyed by trust domain. + * Represents a set of JWT bundles keyed by trust domain. */ @Value public class JwtBundleSet implements BundleSource { diff --git a/java-spiffe-core/src/main/java/spiffe/bundle/x509bundle/X509Bundle.java b/java-spiffe-core/src/main/java/spiffe/bundle/x509bundle/X509Bundle.java index 32f74fc..cafe791 100644 --- a/java-spiffe-core/src/main/java/spiffe/bundle/x509bundle/X509Bundle.java +++ b/java-spiffe-core/src/main/java/spiffe/bundle/x509bundle/X509Bundle.java @@ -20,7 +20,7 @@ import java.util.Set; import java.util.concurrent.ConcurrentHashMap; /** - * A X509Bundle represents a collection of trusted X.509 authorities for a trust domain. + * Represents a collection of trusted X.509 authorities for a trust domain. */ @Value public class X509Bundle implements BundleSource { diff --git a/java-spiffe-core/src/main/java/spiffe/bundle/x509bundle/X509BundleSet.java b/java-spiffe-core/src/main/java/spiffe/bundle/x509bundle/X509BundleSet.java index 42cc815..9a3ed5e 100644 --- a/java-spiffe-core/src/main/java/spiffe/bundle/x509bundle/X509BundleSet.java +++ b/java-spiffe-core/src/main/java/spiffe/bundle/x509bundle/X509BundleSet.java @@ -14,7 +14,7 @@ import java.util.Map; import java.util.concurrent.ConcurrentHashMap; /** - * A X509BundleSet represents a set of X.509 bundles keyed by trust domain. + * Represents a set of X.509 bundles keyed by trust domain. */ @Value public class X509BundleSet implements BundleSource { diff --git a/java-spiffe-core/src/main/java/spiffe/exception/AuthorityNotFoundException.java b/java-spiffe-core/src/main/java/spiffe/exception/AuthorityNotFoundException.java index 2e699d1..5e4457f 100644 --- a/java-spiffe-core/src/main/java/spiffe/exception/AuthorityNotFoundException.java +++ b/java-spiffe-core/src/main/java/spiffe/exception/AuthorityNotFoundException.java @@ -1,8 +1,8 @@ package spiffe.exception; /** - * Checked exception thrown to indicate that an authority could not be - * found in the bundle source. + * Checked exception thrown to indicate that an Authority could not be + * found in the Bundle Source. */ public class AuthorityNotFoundException extends Exception { public AuthorityNotFoundException(String message) { diff --git a/java-spiffe-core/src/main/java/spiffe/exception/BundleNotFoundException.java b/java-spiffe-core/src/main/java/spiffe/exception/BundleNotFoundException.java index 4403b6a..298f773 100644 --- a/java-spiffe-core/src/main/java/spiffe/exception/BundleNotFoundException.java +++ b/java-spiffe-core/src/main/java/spiffe/exception/BundleNotFoundException.java @@ -1,8 +1,8 @@ package spiffe.exception; /** - * Checked exception thrown to indicate that a bundle could not be - * found in the bundle source. + * Checked exception thrown to indicate that a Bundle could not be + * found in the Bundle Source. */ public class BundleNotFoundException extends Exception { public BundleNotFoundException(String message) { diff --git a/java-spiffe-core/src/main/java/spiffe/exception/JwtBundleException.java b/java-spiffe-core/src/main/java/spiffe/exception/JwtBundleException.java index 296b3b9..f55d20f 100644 --- a/java-spiffe-core/src/main/java/spiffe/exception/JwtBundleException.java +++ b/java-spiffe-core/src/main/java/spiffe/exception/JwtBundleException.java @@ -1,7 +1,7 @@ package spiffe.exception; /** - * Checked exception thrown when there is an error creating a JwtBundle + * Checked exception thrown when there is an error creating a JWT Bundle. */ public class JwtBundleException extends Exception { public JwtBundleException(String message) { @@ -11,8 +11,4 @@ public class JwtBundleException extends Exception { public JwtBundleException(String message, Throwable cause) { super(message, cause); } - - public JwtBundleException(Throwable cause) { - super(cause); - } } diff --git a/java-spiffe-core/src/main/java/spiffe/exception/JwtSourceException.java b/java-spiffe-core/src/main/java/spiffe/exception/JwtSourceException.java index c6e14bd..2683be7 100644 --- a/java-spiffe-core/src/main/java/spiffe/exception/JwtSourceException.java +++ b/java-spiffe-core/src/main/java/spiffe/exception/JwtSourceException.java @@ -1,7 +1,7 @@ package spiffe.exception; /** - * Checked thrown when there is an error creating or initializing a JWT source + * Checked thrown when there is an error creating or initializing a JWT Source. */ public class JwtSourceException extends Exception { @@ -12,8 +12,4 @@ public class JwtSourceException extends Exception { public JwtSourceException(String message, Throwable cause) { super(message, cause); } - - public JwtSourceException(Throwable cause) { - super(cause); - } } diff --git a/java-spiffe-core/src/main/java/spiffe/exception/JwtSvidException.java b/java-spiffe-core/src/main/java/spiffe/exception/JwtSvidException.java index 3a908a9..f9bfcf8 100644 --- a/java-spiffe-core/src/main/java/spiffe/exception/JwtSvidException.java +++ b/java-spiffe-core/src/main/java/spiffe/exception/JwtSvidException.java @@ -13,8 +13,4 @@ public class JwtSvidException extends Exception { public JwtSvidException(String message, Throwable cause) { super(message, cause); } - - public JwtSvidException(Throwable cause) { - super(cause); - } } diff --git a/java-spiffe-core/src/main/java/spiffe/exception/SocketEndpointAddressException.java b/java-spiffe-core/src/main/java/spiffe/exception/SocketEndpointAddressException.java index b828062..f1c1961 100644 --- a/java-spiffe-core/src/main/java/spiffe/exception/SocketEndpointAddressException.java +++ b/java-spiffe-core/src/main/java/spiffe/exception/SocketEndpointAddressException.java @@ -12,8 +12,4 @@ public class SocketEndpointAddressException extends Exception { public SocketEndpointAddressException(String message, Throwable cause) { super(message, cause); } - - public SocketEndpointAddressException(Throwable cause) { - super(cause); - } } diff --git a/java-spiffe-core/src/main/java/spiffe/exception/X509ContextException.java b/java-spiffe-core/src/main/java/spiffe/exception/X509ContextException.java index 72046ba..fd12bc1 100644 --- a/java-spiffe-core/src/main/java/spiffe/exception/X509ContextException.java +++ b/java-spiffe-core/src/main/java/spiffe/exception/X509ContextException.java @@ -2,7 +2,7 @@ package spiffe.exception; /** * Checked exception thrown when a there was an error retrieving - * or processing a X509Context. + * or processing an X.509 Context. */ public class X509ContextException extends Exception { public X509ContextException(String message) { @@ -12,8 +12,4 @@ public class X509ContextException extends Exception { public X509ContextException(String message, Throwable cause) { super(message, cause); } - - public X509ContextException(Throwable cause) { - super(cause); - } } diff --git a/java-spiffe-core/src/main/java/spiffe/exception/X509SourceException.java b/java-spiffe-core/src/main/java/spiffe/exception/X509SourceException.java index 5f93eb1..6397aa9 100644 --- a/java-spiffe-core/src/main/java/spiffe/exception/X509SourceException.java +++ b/java-spiffe-core/src/main/java/spiffe/exception/X509SourceException.java @@ -1,7 +1,7 @@ package spiffe.exception; /** - * Checked thrown when there is an error creating or initializing a X.509 source + * Checked thrown when there is an error creating or initializing a X.509 Source. */ public class X509SourceException extends Exception { public X509SourceException(String message) { @@ -11,8 +11,4 @@ public class X509SourceException extends Exception { public X509SourceException(String message, Throwable cause) { super(message, cause); } - - public X509SourceException(Throwable cause) { - super(cause); - } } diff --git a/java-spiffe-core/src/main/java/spiffe/exception/X509SvidException.java b/java-spiffe-core/src/main/java/spiffe/exception/X509SvidException.java index ce1558e..c409a47 100644 --- a/java-spiffe-core/src/main/java/spiffe/exception/X509SvidException.java +++ b/java-spiffe-core/src/main/java/spiffe/exception/X509SvidException.java @@ -5,7 +5,6 @@ package spiffe.exception; * the components of an X.509 SVID. */ public class X509SvidException extends Exception { - public X509SvidException(String message) { super(message); } @@ -13,8 +12,4 @@ public class X509SvidException extends Exception { public X509SvidException(String message, Throwable cause) { super(message, cause); } - - public X509SvidException(Throwable cause) { - super(cause); - } } diff --git a/java-spiffe-core/src/main/java/spiffe/spiffeid/SpiffeId.java b/java-spiffe-core/src/main/java/spiffe/spiffeid/SpiffeId.java index 2a776d4..00fcbcf 100644 --- a/java-spiffe-core/src/main/java/spiffe/spiffeid/SpiffeId.java +++ b/java-spiffe-core/src/main/java/spiffe/spiffeid/SpiffeId.java @@ -10,7 +10,7 @@ import java.util.Arrays; import java.util.stream.Collectors; /** - * A SpiffeId represents a SPIFFE ID as defined in SPIFFE standard. + * Represents a SPIFFE ID as defined in SPIFFE standard. *

* @see https://github.com/spiffe/spiffe/blob/master/standards/SPIFFE-ID.md */ @@ -70,15 +70,19 @@ public class SpiffeId { } /** - * Returns true if the trust domain of this SPIFFE ID is the same as the given trust domain. + * Returns true if the trust domain of this SPIFFE ID is the same as trust domain given as parameter. * - * @param trustDomain instance of a {@link TrustDomain} + * @param trustDomain an instance of a {@link TrustDomain} * @return true if the given trust domain equals the trust domain of this object, false otherwise */ public boolean memberOf(final TrustDomain trustDomain) { return this.trustDomain.equals(trustDomain); } + /** + * Returns the string representation of the SPIFFE ID, concatenating schema, trust domain, + * and path segments (e.g. 'spiffe://example.org/path1/path2') + */ @Override public String toString() { return String.format("%s://%s%s", SPIFFE_SCHEME, this.trustDomain.toString(), this.path); diff --git a/java-spiffe-core/src/main/java/spiffe/spiffeid/SpiffeIdUtils.java b/java-spiffe-core/src/main/java/spiffe/spiffeid/SpiffeIdUtils.java index 34329c3..d34064e 100644 --- a/java-spiffe-core/src/main/java/spiffe/spiffeid/SpiffeIdUtils.java +++ b/java-spiffe-core/src/main/java/spiffe/spiffeid/SpiffeIdUtils.java @@ -1,12 +1,10 @@ package spiffe.spiffeid; import lombok.val; -import org.apache.commons.lang3.StringUtils; import java.io.IOException; import java.nio.file.Files; import java.nio.file.Path; -import java.security.Security; import java.util.Arrays; import java.util.List; import java.util.stream.Collectors; @@ -22,51 +20,6 @@ public class SpiffeIdUtils { private static final char DEFAULT_CHAR_SEPARATOR = ','; - /** - * Reads the Accepted SPIFFE IDs from a system property and parses them to {@link SpiffeId} instances. - * - * @param systemProperty name of the system property that contains a list of SPIFFE IDs separated by a commas. - * @return a list of {@link SpiffeId} parsed from the values read from the security property, in case there's no values - * in the System property, it returns an emtpy list - * - * @throws IllegalArgumentException if the given system property is empty or if any of the SPIFFE IDs - * cannot be parsed - */ - public static List getSpiffeIdsFromSystemProperty(final String systemProperty) { - if (isBlank(systemProperty)) { - throw new IllegalArgumentException("Argument systemProperty cannot be empty"); - } - - val spiffeIds = System.getProperty(systemProperty); - if (StringUtils.isBlank(spiffeIds)) { - return EMPTY_LIST; - } - return toListOfSpiffeIds(spiffeIds, DEFAULT_CHAR_SEPARATOR); - } - - /** - * Reads the accepted SPIFFE IDs from a security Property (defined in java.security file) and parses - * them to {@link SpiffeId} instances. - * - * @param securityProperty name of the security property that contains a list of SPIFFE IDs separated by commas. - * @return a List of {@link SpiffeId} parsed from the values read from the given security property - * - * @throws IllegalArgumentException if the security property is empty or if any of the SPIFFE IDs - * cannot be parsed - */ - public static List getSpiffeIdsFromSecurityProperty(final String securityProperty) { - if (isBlank(securityProperty)) { - throw new IllegalArgumentException("Argument securityProperty cannot be empty"); - } - - val spiffeIds = Security.getProperty(securityProperty); - if (StringUtils.isBlank(spiffeIds)) { - return EMPTY_LIST; - } - - return toListOfSpiffeIds(spiffeIds, DEFAULT_CHAR_SEPARATOR); - } - /** * Reads a file containing a list of SPIFFE IDs and parses them to {@link SpiffeId} instances. *

@@ -74,8 +27,7 @@ public class SpiffeIdUtils { * * @param spiffeIdsFile the path to the file containing a list of SPIFFE IDs * @return a List of {@link SpiffeId} parsed from the file provided - * - * @throws IOException if the given spiffeIdsFile cannot be read + * @throws IOException if the given spiffeIdsFile cannot be read * @throws IllegalArgumentException if any of the SPIFFE IDs in the file cannot be parsed */ public static List getSpiffeIdListFromFile(final Path spiffeIdsFile) throws IOException { @@ -92,9 +44,7 @@ public class SpiffeIdUtils { * * @param spiffeIds a list of SPIFFE IDs represented in a string * @param separator used to separate the SPIFFE IDs in the string. - * * @return a list of {@link SpiffeId} instances. - * * @throws IllegalArgumentException is the string provided is blank */ public static List toListOfSpiffeIds(final String spiffeIds, final char separator) { @@ -108,9 +58,17 @@ public class SpiffeIdUtils { .collect(Collectors.toList()); } + /** + * Return the list of the SPIFFE IDs parsed from the String parameter, using the default separator (comma) + * + * @param spiffeIds a String representing a list of SPIFFE IDs separeated by comma + * @return a list of {@link SpiffeId} instances + * @throws IllegalArgumentException is the string provided is blank + */ public static List toListOfSpiffeIds(final String spiffeIds) { return toListOfSpiffeIds(spiffeIds, DEFAULT_CHAR_SEPARATOR); } - private SpiffeIdUtils() {} + private SpiffeIdUtils() { + } } diff --git a/java-spiffe-core/src/main/java/spiffe/spiffeid/TrustDomain.java b/java-spiffe-core/src/main/java/spiffe/spiffeid/TrustDomain.java index 965acaa..260fe03 100644 --- a/java-spiffe-core/src/main/java/spiffe/spiffeid/TrustDomain.java +++ b/java-spiffe-core/src/main/java/spiffe/spiffeid/TrustDomain.java @@ -12,7 +12,7 @@ import java.net.URISyntaxException; import static spiffe.spiffeid.SpiffeId.SPIFFE_SCHEME; /** - * A TrustDomain represents a normalized SPIFFE trust domain (e.g. domain.test). + * Represents a normalized SPIFFE trust domain (e.g. 'domain.test'). */ @Value public class TrustDomain { @@ -28,7 +28,6 @@ public class TrustDomain { * * @param trustDomain a trust domain represented as a string, must not be blank. * @return an instance of a {@link TrustDomain} - * * @throws IllegalArgumentException if the given string is blank or cannot be parsed */ public static TrustDomain of(@NonNull String trustDomain) { @@ -50,8 +49,24 @@ public class TrustDomain { return new TrustDomain(host); } - public SpiffeId newSpiffeId(String ...path) { - return SpiffeId.of(this, path); + /** + * Creates a SPIFFE ID from this trust domain and the given path segments. + * + * @param segments path segments + * @return a {@link SpiffeId} with the current trust domain and the given path segments + */ + public SpiffeId newSpiffeId(String... segments) { + return SpiffeId.of(this, segments); + } + + /** + * Returns the trust domain as a String. + * + * @return a String with the trust domain + */ + @Override + public String toString() { + return name; } private static void validateHost(String host) { @@ -79,14 +94,4 @@ public class TrustDomain { } return s; } - - /** - * Returns the trust domain as a string. - * - * @return a String with the trust domain - */ - @Override - public String toString() { - return name; - } } diff --git a/java-spiffe-core/src/main/java/spiffe/svid/jwtsvid/JwtSvid.java b/java-spiffe-core/src/main/java/spiffe/svid/jwtsvid/JwtSvid.java index 8e8224d..a54bb9c 100644 --- a/java-spiffe-core/src/main/java/spiffe/svid/jwtsvid/JwtSvid.java +++ b/java-spiffe-core/src/main/java/spiffe/svid/jwtsvid/JwtSvid.java @@ -28,33 +28,33 @@ import java.util.List; import java.util.Map; /** - * A JwtSvid represents a SPIFFE JWT-SVID. + * Represents a SPIFFE JWT-SVID. */ @Value public class JwtSvid { /** - * SPIFFE ID of the JWT-SVID as present in the 'sub' claim + * SPIFFE ID of the JWT-SVID as present in the 'sub' claim. */ SpiffeId spiffeId; /** - * Audience is the intended recipients of JWT-SVID as present in the 'aud' claim + * Audience is the intended recipients of JWT-SVID as present in the 'aud' claim. */ List audience; /** - * Expiration time of JWT-SVID as present in 'exp' claim + * Expiration time of JWT-SVID as present in 'exp' claim. */ Date expiry; /** - * Parsed claims from token + * Parsed claims from token. */ Map claims; /** - * Serialized JWT token + * Serialized JWT token. */ String token; @@ -67,13 +67,14 @@ public class JwtSvid { } /** - * Parses and validates a JWT-SVID token and returns the - * JWT-SVID. The JWT-SVID signature is verified using the JWT bundle source. + * Parses and validates a JWT-SVID token and returns an instance of JwtSvid. + *

+ * The JWT-SVID signature is verified using the JWT bundle source. * * @param token a token as a string that is parsed and validated * @param jwtBundleSource an implementation of a {@link BundleSource} that provides the authority to verify the signature * @param audience audience as a List of String used to validate the 'aud' claim - * @return an instance of a {@link JwtSvid} with a spiffe id parsed from the 'sub', audience from 'aud', and expiry + * @return an instance of a {@link JwtSvid} with a SPIFFE ID parsed from the 'sub', audience from 'aud', and expiry * from 'exp' claim. * @throws spiffe.exception.JwtSvidException when the token expired or the expiration claim is missing, * when the algorithm is not supported, when the header 'kid' is missing, when the signature cannot be verified, or @@ -118,7 +119,9 @@ public class JwtSvid { } /** - * Parses and validates a JWT-SVID token and returns the JWT-SVID. The JWT-SVID signature is not verified. + * Parses and validates a JWT-SVID token and returns an instance of a JwtSvid. + *

+ * The JWT-SVID signature is not verified. * * @param token a token as a string that is parsed and validated * @param audience audience as a List of String used to validate the 'aud' claim diff --git a/java-spiffe-core/src/main/java/spiffe/svid/jwtsvid/JwtSvidSource.java b/java-spiffe-core/src/main/java/spiffe/svid/jwtsvid/JwtSvidSource.java index 6c0d79a..5b52eaf 100644 --- a/java-spiffe-core/src/main/java/spiffe/svid/jwtsvid/JwtSvidSource.java +++ b/java-spiffe-core/src/main/java/spiffe/svid/jwtsvid/JwtSvidSource.java @@ -4,16 +4,16 @@ import spiffe.exception.JwtSvidException; import spiffe.spiffeid.SpiffeId; /** - * A JwtSvidSource represents a source of SPIFFE JWT-SVIDs. + * Represents a source of SPIFFE JWT-SVIDs. */ public interface JwtSvidSource { /** - * Fetches a JWT-SVID from the source with the given parameters. + * Fetches a JWT-SVID from the source with the given subject and audiences. * * @param subject a {@link SpiffeId} * @param audience the audience - * @param extraAudiences an array of Strings + * @param extraAudiences a list of extra audiences as an array of String * @return a {@link JwtSvid} * @throws JwtSvidException when there is an error fetching the JWT SVID */ diff --git a/java-spiffe-core/src/main/java/spiffe/svid/x509svid/X509Svid.java b/java-spiffe-core/src/main/java/spiffe/svid/x509svid/X509Svid.java index 136b54f..22bdd43 100644 --- a/java-spiffe-core/src/main/java/spiffe/svid/x509svid/X509Svid.java +++ b/java-spiffe-core/src/main/java/spiffe/svid/x509svid/X509Svid.java @@ -21,7 +21,7 @@ import java.util.List; import static spiffe.internal.CertificateUtils.*; /** - * A X509Svid represents a SPIFFE X.509 SVID. + * Represents a SPIFFE X.509 SVID. *

* Contains a SPIFFE ID, a private key and a chain of X.509 certificates. */ @@ -33,7 +33,7 @@ public class X509Svid implements X509SvidSource { /** * The X.509 certificates of the X.509-SVID. The leaf certificate is * the X.509-SVID certificate. Any remaining certificates (if any) chain - * the X.509-SVID certificate back to a X.509 root for the trust domain. + * the X.509-SVID certificate back to an X.509 root for the trust domain. */ List chain; @@ -88,7 +88,7 @@ public class X509Svid implements X509SvidSource { } /** - * Return the chain of certificates as an array. + * Return the chain of certificates as an array of {@link X509Certificate} */ public X509Certificate[] getChainArray() { return chain.toArray(new X509Certificate[0]); diff --git a/java-spiffe-core/src/main/java/spiffe/svid/x509svid/X509SvidSource.java b/java-spiffe-core/src/main/java/spiffe/svid/x509svid/X509SvidSource.java index 54443be..24cf8af 100644 --- a/java-spiffe-core/src/main/java/spiffe/svid/x509svid/X509SvidSource.java +++ b/java-spiffe-core/src/main/java/spiffe/svid/x509svid/X509SvidSource.java @@ -1,7 +1,7 @@ package spiffe.svid.x509svid; /** - * A X509SvidSource represents a source of X.509 SVIDs. + * Represents a source of X.509 SVIDs. */ public interface X509SvidSource { diff --git a/java-spiffe-core/src/main/java/spiffe/svid/x509svid/X509SvidValidator.java b/java-spiffe-core/src/main/java/spiffe/svid/x509svid/X509SvidValidator.java index 0d62100..225b046 100644 --- a/java-spiffe-core/src/main/java/spiffe/svid/x509svid/X509SvidValidator.java +++ b/java-spiffe-core/src/main/java/spiffe/svid/x509svid/X509SvidValidator.java @@ -16,8 +16,7 @@ import java.util.List; import java.util.function.Supplier; /** - * A X509SvidValidator provides methods to validate - * a chain of X.509 certificates using an X.509 bundle source. + * Provides methods to validate a chain of X.509 certificates using an X.509 bundle source. */ public class X509SvidValidator { diff --git a/java-spiffe-core/src/main/java/spiffe/workloadapi/Address.java b/java-spiffe-core/src/main/java/spiffe/workloadapi/Address.java index 92498e7..abe604c 100644 --- a/java-spiffe-core/src/main/java/spiffe/workloadapi/Address.java +++ b/java-spiffe-core/src/main/java/spiffe/workloadapi/Address.java @@ -27,7 +27,7 @@ public class Address { /** * Returns the default Workload API address hold by the system environment variable - * defined by SOCKET_ENV_VARIABLE + * defined by SOCKET_ENV_VARIABLE. */ public static String getDefaultAddress() { return System.getenv(Address.SOCKET_ENV_VARIABLE); diff --git a/java-spiffe-core/src/main/java/spiffe/workloadapi/JwtSource.java b/java-spiffe-core/src/main/java/spiffe/workloadapi/JwtSource.java index 7df270d..f095b06 100644 --- a/java-spiffe-core/src/main/java/spiffe/workloadapi/JwtSource.java +++ b/java-spiffe-core/src/main/java/spiffe/workloadapi/JwtSource.java @@ -29,8 +29,7 @@ import java.util.logging.Level; import static spiffe.workloadapi.internal.ThreadUtils.await; /** - * A JwtSource represents a source of SPIFFE JWT SVIDs and JWT bundles - * maintained via the Workload API. + * Represents a source of SPIFFE JWT SVIDs and JWT bundles maintained via the Workload API. */ @Log public class JwtSource implements JwtSvidSource, BundleSource, Closeable { diff --git a/java-spiffe-core/src/main/java/spiffe/workloadapi/Watcher.java b/java-spiffe-core/src/main/java/spiffe/workloadapi/Watcher.java index 8b21a52..170d83f 100644 --- a/java-spiffe-core/src/main/java/spiffe/workloadapi/Watcher.java +++ b/java-spiffe-core/src/main/java/spiffe/workloadapi/Watcher.java @@ -1,7 +1,7 @@ package spiffe.workloadapi; /** - * a Watcher handles updates of type T. + * Watches updates of type T. * * @param is the type of the updates. */ diff --git a/java-spiffe-core/src/main/java/spiffe/workloadapi/WorkloadApiClient.java b/java-spiffe-core/src/main/java/spiffe/workloadapi/WorkloadApiClient.java index 924fb98..6bcf7e4 100644 --- a/java-spiffe-core/src/main/java/spiffe/workloadapi/WorkloadApiClient.java +++ b/java-spiffe-core/src/main/java/spiffe/workloadapi/WorkloadApiClient.java @@ -36,7 +36,7 @@ import java.util.concurrent.ScheduledExecutorService; import java.util.logging.Level; /** - * A WorkloadApiClient represents a client to interact with the Workload API. + * Represents a client to interact with the Workload API. *

* Supports one-shot calls and watch updates for X.509 and JWT SVIDs and bundles. *

@@ -74,7 +74,7 @@ public class WorkloadApiClient implements Closeable { } /** - * Creates a new Workload API client. + * Creates a new Workload API client configured with the given client options. *

* If the SPIFFE socket endpoint address is not provided in the options, it uses the default address. * @@ -121,11 +121,11 @@ public class WorkloadApiClient implements Closeable { } private WorkloadApiClient(SpiffeWorkloadAPIStub workloadApiAsyncStub, - SpiffeWorkloadAPIBlockingStub workloadApiBlockingStub, - ManagedChannelWrapper managedChannel, - BackoffPolicy backoffPolicy, - ScheduledExecutorService retryExecutor, - ExecutorService executorService) { + SpiffeWorkloadAPIBlockingStub workloadApiBlockingStub, + ManagedChannelWrapper managedChannel, + BackoffPolicy backoffPolicy, + ScheduledExecutorService retryExecutor, + ExecutorService executorService) { this.workloadApiAsyncStub = workloadApiAsyncStub; this.workloadApiBlockingStub = workloadApiBlockingStub; this.managedChannel = managedChannel; @@ -182,6 +182,7 @@ public class WorkloadApiClient implements Closeable { * @param audience the audience of the JWT-SVID * @param extraAudience the extra audience for the JWT_SVID * @return an instance of a {@link JwtSvid} + * @throws JwtSvidException if there is an error fetching or processing the JWT from the Workload API */ public JwtSvid fetchJwtSvid(@NonNull SpiffeId subject, @NonNull String audience, String... extraAudience) throws JwtSvidException { List audParam = new ArrayList<>(); @@ -210,8 +211,7 @@ public class WorkloadApiClient implements Closeable { } /** - * Validates the JWT-SVID token. The parsed and validated - * JWT-SVID is returned. + * Validates the JWT-SVID token. The parsed and validated JWT-SVID is returned. * * @param token JWT token * @param audience audience of the JWT diff --git a/java-spiffe-core/src/main/java/spiffe/workloadapi/X509Context.java b/java-spiffe-core/src/main/java/spiffe/workloadapi/X509Context.java index 322f011..9dc08fd 100644 --- a/java-spiffe-core/src/main/java/spiffe/workloadapi/X509Context.java +++ b/java-spiffe-core/src/main/java/spiffe/workloadapi/X509Context.java @@ -8,7 +8,7 @@ import spiffe.svid.x509svid.X509Svid; import java.util.List; /** - * A X509Context represents the X.509 materials that are fetched from the Workload API. + * Represents the X.509 materials that are fetched from the Workload API. *

* Contains a list of {@link X509Svid} and a {@link X509BundleSet}. */ diff --git a/java-spiffe-core/src/main/java/spiffe/workloadapi/X509Source.java b/java-spiffe-core/src/main/java/spiffe/workloadapi/X509Source.java index b30af3f..cdccdd7 100644 --- a/java-spiffe-core/src/main/java/spiffe/workloadapi/X509Source.java +++ b/java-spiffe-core/src/main/java/spiffe/workloadapi/X509Source.java @@ -28,8 +28,7 @@ import java.util.logging.Level; import static spiffe.workloadapi.internal.ThreadUtils.await; /** - * A X509Source represents a source of X.509 SVIDs and X.509 bundles maintained via the - * Workload API. + * Represents a source of X.509 SVIDs and X.509 bundles maintained via the Workload API. *

* It handles a {@link X509Svid} and a {@link X509BundleSet} that are updated automatically * whenever there is an update from the Workload API. @@ -97,7 +96,7 @@ public class X509Source implements X509SvidSource, BundleSource, Clo * Creates a new X.509 source. It blocks until the initial update * has been received from the Workload API or until the timeout configured * through the system property `spiffe.newX509Source.timeout` expires. - * If no timeout is configured, it blocks until it gets a X.509 update from the Workload API. + * If no timeout is configured, it blocks until it gets an X.509 update from the Workload API. *

* The {@link WorkloadApiClient} can be provided in the options, if it is not, a new client is created. * diff --git a/java-spiffe-core/src/main/java/spiffe/workloadapi/retry/BackoffPolicy.java b/java-spiffe-core/src/main/java/spiffe/workloadapi/retry/BackoffPolicy.java index 999df0e..917d653 100644 --- a/java-spiffe-core/src/main/java/spiffe/workloadapi/retry/BackoffPolicy.java +++ b/java-spiffe-core/src/main/java/spiffe/workloadapi/retry/BackoffPolicy.java @@ -7,6 +7,9 @@ import lombok.val; import java.time.Duration; import java.util.function.UnaryOperator; +/** + * Represents a backoff policy for performing retries using exponential increasing delays. + */ @Data public class BackoffPolicy { @@ -55,8 +58,8 @@ public class BackoffPolicy { * Calculate the nextDelay based on a currentDelay, applying the backoff function * If the calculated delay is greater than maxDelay, it returns maxDelay * - * @param currentDelay - * @return next delay + * @param currentDelay a {@link Duration} representing the current delay + * @return a {@link Duration} representing the next delay */ public Duration nextDelay(Duration currentDelay) { val next = backoffFunction.apply(currentDelay); @@ -71,7 +74,7 @@ public class BackoffPolicy { * or if the retriesCount param is lower than the maxRetries * * @param retriesCount the current number of retries - * @return + * @return false if the number of retries did not reach the max number of retries, true otherwise */ public boolean didNotReachMaxRetries(int retriesCount) { return (maxRetries == UNLIMITED_RETRIES || retriesCount < maxRetries); diff --git a/java-spiffe-core/src/main/java/spiffe/workloadapi/retry/RetryHandler.java b/java-spiffe-core/src/main/java/spiffe/workloadapi/retry/RetryHandler.java index 1de697d..356d87f 100644 --- a/java-spiffe-core/src/main/java/spiffe/workloadapi/retry/RetryHandler.java +++ b/java-spiffe-core/src/main/java/spiffe/workloadapi/retry/RetryHandler.java @@ -5,7 +5,7 @@ import java.util.concurrent.ScheduledExecutorService; import java.util.concurrent.TimeUnit; /** - * Provides methods to schedule the execution of retries based on a backoff policy + * Provides methods to schedule the execution of retries based on a backoff policy. */ public class RetryHandler { diff --git a/java-spiffe-core/src/test/java/spiffe/spiffeid/SpiffeIdUtilsTest.java b/java-spiffe-core/src/test/java/spiffe/spiffeid/SpiffeIdUtilsTest.java index a24b189..07ced38 100644 --- a/java-spiffe-core/src/test/java/spiffe/spiffeid/SpiffeIdUtilsTest.java +++ b/java-spiffe-core/src/test/java/spiffe/spiffeid/SpiffeIdUtilsTest.java @@ -8,96 +8,11 @@ import java.net.URISyntaxException; import java.nio.file.NoSuchFileException; import java.nio.file.Path; import java.nio.file.Paths; -import java.security.Security; import java.util.List; import static org.junit.jupiter.api.Assertions.*; -class piffeIdUtilsTest { - - @Test - void getSpiffeIdsFromSystemProperty() { - System.setProperty("spiffe.property", " spiffe://example.org/workload1, spiffe://example.org/workload2 "); - - List spiffeIdList = SpiffeIdUtils.getSpiffeIdsFromSystemProperty("spiffe.property"); - - assertNotNull(spiffeIdList); - assertEquals(2, spiffeIdList.size()); - assertEquals(SpiffeId.parse("spiffe://example.org/workload1"), spiffeIdList.get(0)); - assertEquals(SpiffeId.parse("spiffe://example.org/workload2"), spiffeIdList.get(1)); - } - - @Test - void getSpiffeIdsFromSystemPropertyThatHasNoValue_returnsEmptyList() { - System.setProperty("spiffe.property", ""); - - List spiffeIdList = SpiffeIdUtils.getSpiffeIdsFromSystemProperty("spiffe.property"); - - assertNotNull(spiffeIdList); - assertEquals(0, spiffeIdList.size()); - } - - @Test - void getSpiffeIdsFromBlankSystemProperty_throwsIllegalArgumentException() { - try { - SpiffeIdUtils.getSpiffeIdsFromSystemProperty(""); - fail("should have thrown exception"); - } catch (IllegalArgumentException e) { - //expected - } - } - - @Test - void getSpiffeIdsFromNullSystemProperty_throwsIllegalArgumentException() { - try { - SpiffeIdUtils.getSpiffeIdsFromSystemProperty(null); - fail("should have thrown exception"); - } catch (IllegalArgumentException e) { - //expected - } - } - - @Test - void getSpiffeIdsFromSecurityProperty() { - Security.setProperty("spiffe.property", " spiffe://example.org/workload1, spiffe://example.org/workload2 "); - - List spiffeIdList = SpiffeIdUtils.getSpiffeIdsFromSecurityProperty("spiffe.property"); - - assertNotNull(spiffeIdList); - assertEquals(2, spiffeIdList.size()); - assertEquals(SpiffeId.parse("spiffe://example.org/workload1"), spiffeIdList.get(0)); - assertEquals(SpiffeId.parse("spiffe://example.org/workload2"), spiffeIdList.get(1)); - } - - @Test - void getSpiffeIdsFromSecurityPropertyThatHasNoValue_returnsEmptyList() { - Security.setProperty("spiffe.property", ""); - - List spiffeIdList = SpiffeIdUtils.getSpiffeIdsFromSecurityProperty("spiffe.property"); - - assertNotNull(spiffeIdList); - assertEquals(0, spiffeIdList.size()); - } - - @Test - void getSpiffeIdsFromBlankSecurityProperty_throwsIllegalArgumentException() { - try { - SpiffeIdUtils.getSpiffeIdsFromSecurityProperty(""); - fail("should have thrown exception"); - } catch (IllegalArgumentException e) { - //expected - } - } - - @Test - void getSpiffeIdsFromNullSecurityProperty_throwsIllegalArgumentException() { - try { - SpiffeIdUtils.getSpiffeIdsFromSecurityProperty(null); - fail("should have thrown exception"); - } catch (IllegalArgumentException e) { - //expected - } - } +class SpiffeIdUtilsTest { @Test void getSpiffeIdListFromFile() throws URISyntaxException {