Upgrade Gradle and enforce javadocs

.sdkmanrc

@@ -1,3 +1,2 @@
 java=26-amzn
-gradle=9.5.0
-
+gradle=9.5.1

build.gradle

@@ -43,7 +43,7 @@ subprojects {
         'https://oss.sonatype.org/content/repositories/snapshots/' :
         'https://ossrh-staging-api.central.sonatype.com/service/local/staging/deploy/maven2/'
     configurations.implementation.transitive = true
-    javadoc.failOnError = false
+    javadoc.failOnError = true
 
     java {
        sourceCompatibility = JavaVersion.VERSION_25
@@ -183,7 +183,14 @@ task aggregatedJavadoc (type: Javadoc, description: "Aggregated Javadocs") {
     destinationDir = new File(buildDir, 'docs/javadoc')
     classpath = files(subprojects.collect {project ->
         project.sourceSets.main.compileClasspath})
-    failOnError = false
+    failOnError = true
+    configure(options) {
+        tags(
+            'apiNote:a:API Note:',
+            'implSpec:a:Implementation Requirements:',
+            'implNote:a:Implementation Note:'
+        )
+    }
 }
 
 

gradle/libs.versions.toml

@@ -3,7 +3,7 @@ jdom = "2.0.6.1"
 sleepycatje = "18.3.12"
 commonscli = "1.11.0"
 commonslang3 = "3.20.0"
-jline = "4.0.14"
+jline = "4.1.0"
 jna = '5.18.1'
 jansi = '2.4.3'
 beanshell = "2.0b6"
@@ -49,4 +49,3 @@ jacksonDataBind = { module = 'com.fasterxml.jackson.core:jackson-databind', vers
 jacksonDataTypeJSR310 = { module = 'com.fasterxml.jackson.datatype:jackson-datatype-jsr310', version.ref = 'jackson' }
 jacksonDataFormatXML = { module = 'com.fasterxml.jackson.dataformat:jackson-dataformat-xml', version.ref = 'jackson' }
 mapdb = { module = "org.mapdb:mapdb", version.ref = "mapdb" }
-

gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-9.5.0-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.5.1-bin.zip
 networkTimeout=10000
 retries=0
 retryBackOffMs=500

jpos/src/main/java/org/jpos/security/EMVCAPublicKey.java

@@ -51,22 +51,40 @@ public record EMVCAPublicKey(byte[] rid, byte index, byte[] modulus,
                              byte[] exponent, byte hashAlgorithmIndicator,
                              byte publicKeyAlgorithmIndicator) {
 
+    /**
+     * Creates an EMV CA public key and defensively copies array components.
+     */
     public EMVCAPublicKey {
         rid = copy(rid);
         modulus = copy(modulus);
         exponent = copy(exponent);
     }
 
+    /**
+     * Returns a defensive copy of the RID.
+     *
+     * @return the Registered Application Provider Identifier
+     */
     @Override
     public byte[] rid() {
         return copy(rid);
     }
 
+    /**
+     * Returns a defensive copy of the RSA modulus.
+     *
+     * @return the RSA modulus
+     */
     @Override
     public byte[] modulus() {
         return copy(modulus);
     }
 
+    /**
+     * Returns a defensive copy of the RSA public exponent.
+     *
+     * @return the RSA public exponent
+     */
     @Override
     public byte[] exponent() {
         return copy(exponent);

jpos/src/main/java/org/jpos/security/EMVCDAResult.java

@@ -42,10 +42,18 @@
  */
 public record EMVCDAResult(byte[] iccDynamicNumber, byte cid) {
 
+    /**
+     * Creates a CDA result and defensively copies array components.
+     */
     public EMVCDAResult {
         iccDynamicNumber = copy(iccDynamicNumber);
     }
 
+    /**
+     * Returns a defensive copy of the ICC dynamic number.
+     *
+     * @return the ICC dynamic number
+     */
     @Override
     public byte[] iccDynamicNumber() {
         return copy(iccDynamicNumber);

jpos/src/main/java/org/jpos/security/EMVDerivedKey.java

@@ -51,10 +51,18 @@
  */
 public record EMVDerivedKey<T>(T key, byte[] kcv) {
 
+    /**
+     * Creates a derived-key result and defensively copies array components.
+     */
     public EMVDerivedKey {
         kcv = copy(kcv);
     }
 
+    /**
+     * Returns a defensive copy of the Key Check Value.
+     *
+     * @return the Key Check Value
+     */
     @Override
     public byte[] kcv() {
         return copy(kcv);

jpos/src/main/java/org/jpos/security/EMVICCPublicKey.java

@@ -57,6 +57,9 @@ public record EMVICCPublicKey(byte[] applicationPan, byte[] expirationDate,
                               byte[] exponent, byte hashAlgorithmIndicator,
                               byte publicKeyAlgorithmIndicator) {
 
+    /**
+     * Creates an EMV ICC public key and defensively copies array components.
+     */
     public EMVICCPublicKey {
         applicationPan = copy(applicationPan);
         expirationDate = copy(expirationDate);
@@ -65,26 +68,51 @@ public record EMVICCPublicKey(byte[] applicationPan, byte[] expirationDate,
         exponent = copy(exponent);
     }
 
+    /**
+     * Returns a defensive copy of the application PAN.
+     *
+     * @return the application PAN
+     */
     @Override
     public byte[] applicationPan() {
         return copy(applicationPan);
     }
 
+    /**
+     * Returns a defensive copy of the certificate expiration date.
+     *
+     * @return the expiration date
+     */
     @Override
     public byte[] expirationDate() {
         return copy(expirationDate);
     }
 
+    /**
+     * Returns a defensive copy of the certificate serial number.
+     *
+     * @return the serial number
+     */
     @Override
     public byte[] serialNumber() {
         return copy(serialNumber);
     }
 
+    /**
+     * Returns a defensive copy of the RSA modulus.
+     *
+     * @return the RSA modulus
+     */
     @Override
     public byte[] modulus() {
         return copy(modulus);
     }
 
+    /**
+     * Returns a defensive copy of the RSA public exponent.
+     *
+     * @return the RSA public exponent
+     */
     @Override
     public byte[] exponent() {
         return copy(exponent);

jpos/src/main/java/org/jpos/security/EMVIssuerPublicKey.java

@@ -56,6 +56,9 @@ public record EMVIssuerPublicKey(byte[] issuerIdentifier, byte[] expirationDate,
                                  byte[] exponent, byte hashAlgorithmIndicator,
                                  byte publicKeyAlgorithmIndicator) {
 
+    /**
+     * Creates an EMV issuer public key and defensively copies array components.
+     */
     public EMVIssuerPublicKey {
         issuerIdentifier = copy(issuerIdentifier);
         expirationDate = copy(expirationDate);
@@ -64,26 +67,51 @@ public record EMVIssuerPublicKey(byte[] issuerIdentifier, byte[] expirationDate,
         exponent = copy(exponent);
     }
 
+    /**
+     * Returns a defensive copy of the issuer identifier.
+     *
+     * @return the issuer identifier
+     */
     @Override
     public byte[] issuerIdentifier() {
         return copy(issuerIdentifier);
     }
 
+    /**
+     * Returns a defensive copy of the certificate expiration date.
+     *
+     * @return the expiration date
+     */
     @Override
     public byte[] expirationDate() {
         return copy(expirationDate);
     }
 
+    /**
+     * Returns a defensive copy of the certificate serial number.
+     *
+     * @return the serial number
+     */
     @Override
     public byte[] serialNumber() {
         return copy(serialNumber);
     }
 
+    /**
+     * Returns a defensive copy of the RSA modulus.
+     *
+     * @return the RSA modulus
+     */
     @Override
     public byte[] modulus() {
         return copy(modulus);
     }
 
+    /**
+     * Returns a defensive copy of the RSA public exponent.
+     *
+     * @return the RSA public exponent
+     */
     @Override
     public byte[] exponent() {
         return copy(exponent);

jpos/src/main/java/org/jpos/security/jceadapter/JCESecurityModule.java

@@ -675,7 +675,7 @@ protected byte[] paddingISO9797Method2(byte[] d) {
      * @param key DES double length key
      * @param d data to calculate MAC on it
      * @return 8 byte of mac value
-     * @throws JCEHandlerException
+     * @throws JCEHandlerException if the MAC key cannot be formed or used
      */
     protected byte[] calculateMACISO9797Alg3(Key key, byte[] d) throws JCEHandlerException {
         Key kl = jceHandler.formDESKey(SMAdapter.LENGTH_DES
@@ -959,7 +959,7 @@ private EncryptedPIN translatePINExt (EncryptedPIN oldPinUnderKd1, EncryptedPIN
      * @param mkac unique ICC Master Key for Application Cryptogams or Secure Messaging
      * @param atc ICC generated Application Transaction Counter as diversification value
      * @return derived 16-bytes Session Key with adjusted DES parity
-     * @throws JCEHandlerException
+     * @throws JCEHandlerException if the session key cannot be derived
      */
     protected Key deriveSK_VISA(Key mkac, byte[] atc) throws JCEHandlerException {
 
@@ -988,7 +988,7 @@ protected Key deriveSK_VISA(Key mkac, byte[] atc) throws JCEHandlerException {
      * @param mksm unique ICC Master Key for Secure Messaging
      * @param rand Application Cryptogram as diversification value
      * @return derived 16-bytes Session Key with adjusted DES parity
-     * @throws JCEHandlerException
+     * @throws JCEHandlerException if the session key cannot be derived
      */
     protected Key deriveCommonSK_SM(Key mksm, byte[] rand) throws JCEHandlerException {
       byte[] rl = Arrays.copyOf(rand,8);
@@ -1011,7 +1011,7 @@ protected Key deriveCommonSK_SM(Key mksm, byte[] rand) throws JCEHandlerExceptio
      * @param mkac unique ICC Master Key for Application Cryptogams.
      * @param atc ICC generated Application Transaction Counter as diversification value.
      * @return derived 16-bytes Session Key with adjusted DES parity.
-     * @throws JCEHandlerException
+     * @throws JCEHandlerException if the session key cannot be derived
      */
     protected Key deriveCommonSK_AC(Key mkac, byte[] atc) throws JCEHandlerException {
 
@@ -1024,14 +1024,14 @@ protected Key deriveCommonSK_AC(Key mkac, byte[] atc) throws JCEHandlerException
     /**
      * MasterCard Proprietary Session Key Derivation (SKD) method.
      * <p>
-     * Described in M/Chip 4 version 1.1 Security & Key Management manual
+     * Described in M/Chip 4 version 1.1 Security &amp; Key Management manual
      * paragraph 7 ICC Session Key Derivation.
      *
      * @param mkac unique ICC Master Key for Application Cryptogams
      * @param atc ICC generated Application Transaction Counter as diversification value
      * @param upn terminal generated random as diversification value
      * @return derived 16-bytes Session Key with adjusted DES parity
-     * @throws JCEHandlerException
+     * @throws JCEHandlerException if the session key cannot be derived
      */
     protected Key deriveSK_MK(Key mkac, byte[] atc, byte[] upn) throws JCEHandlerException {