Implement cleaner to replace deprecated finalizers (#893)

The cleaner is the replacement for the deprecated finalize() method for
cleaning objects before garbage collection.

Each class that was previously using finalize() will have an anonymous
function that cleans up the necessary resources. The number of cleaner
threads can be set by a property with the default value being 2. The
object and its anonymous function are registered to one of the cleaner
threads in round robin order.

Signed-off-by: Sabrina Lee <[email protected]>
Co-authored-by: Sabrina Lee <[email protected]>

Author: sabrinajlee

README.md

@@ -6,6 +6,7 @@
   - [Run All Tests](#run-all-tests)
   - [Run Single Test](#run-single-test)
 - [OpenJCEPlus and OpenJCEPlusFIPS Provider SDK Installation](#openjceplus-and-openjceplusfips-provider-sdk-installation)
+- [Configuration Options](#configuration-options)
 - [Features and Algorithms](#features-and-algorithms)
 - [Contributions](#contributions)
 
@@ -263,6 +264,13 @@ take effect.
         ```console
         -Djgskit.library.path=$ANYDIRECTORY
         ```
+## Configuration Options
+
+The following properties can be used to configure application behavior at runtime.
+
+| Property | Use Case |
+|----------|----------|
+| `-Dopenjceplus.cleaners.num=<number_cleaner_threads>` | The cleaner is used for cleaning up native memory no longer in use by OpenJCEPlus and OpenJCEPlusFIPS providers. This option sets the number of cleaner threads to improve cleaning efficiency, particularly useful when encountering `Out Of Memory` (OOM) errors. Default value is `2`. |
 
 # Features And Algorithms
 
@@ -423,7 +431,6 @@ AES Key Wrap based on NIST SP800-38F.
 
 Code does not allow the specification of an IV. However, it will return the default ICV as defined in the NIST SP800-38F. 
 
-
 # Contributions
 
 The following contribution guidelines should be followed:

src/main/java/com/ibm/crypto/plus/provider/DSASignature.java

@@ -1,5 +1,5 @@
 /*
- * Copyright IBM Corp. 2023
+ * Copyright IBM Corp. 2023, 2025
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms provided by IBM in the LICENSE file that accompanied
@@ -28,7 +28,7 @@ abstract class DSASignature extends SignatureSpi {
     DSASignature(OpenJCEPlusProvider provider, String ockDigestAlgo) {
         try {
             this.provider = provider;
-            this.signature = Signature.getInstance(provider.getOCKContext(), ockDigestAlgo);
+            this.signature = Signature.getInstance(provider.getOCKContext(), ockDigestAlgo, provider);
         } catch (Exception e) {
             throw provider.providerException("Failed to initialize DSA signature", e);
         }

src/main/java/com/ibm/crypto/plus/provider/ECDSASignature.java

@@ -1,5 +1,5 @@
 /*
- * Copyright IBM Corp. 2023, 2024
+ * Copyright IBM Corp. 2023, 2025
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms provided by IBM in the LICENSE file that accompanied
@@ -32,7 +32,7 @@ abstract class ECDSASignature extends SignatureSpi {
     ECDSASignature(OpenJCEPlusProvider provider, String ockDigestAlgo) {
         try {
             this.provider = provider;
-            this.signature = Signature.getInstance(provider.getOCKContext(), ockDigestAlgo);
+            this.signature = Signature.getInstance(provider.getOCKContext(), ockDigestAlgo, provider);
         } catch (Exception e) {
             throw provider.providerException("Failed to initialize ECDSA signature", e);
         }

src/main/java/com/ibm/crypto/plus/provider/MessageDigest.java

@@ -19,7 +19,7 @@ abstract class MessageDigest extends MessageDigestSpi implements Cloneable {
     MessageDigest(OpenJCEPlusProvider provider, String ockDigestAlgo) {
         try {
             this.provider = provider;
-            this.digest = Digest.getInstance(provider.getOCKContext(), ockDigestAlgo);
+            this.digest = Digest.getInstance(provider.getOCKContext(), ockDigestAlgo, provider);
         } catch (Exception e) {
             throw provider.providerException("Failure in MessageDigest", e);
         }

src/main/java/com/ibm/crypto/plus/provider/OpenJCEPlus.java

@@ -24,7 +24,6 @@
 import java.util.List;
 import java.util.Map;
 import javax.crypto.SecretKey;
-import sun.security.util.Debug;
 
 @SuppressWarnings({"removal", "deprecation"})
 public final class OpenJCEPlus extends OpenJCEPlusProvider {
@@ -65,9 +64,6 @@ public final class OpenJCEPlus extends OpenJCEPlusProvider {
     // to find ourselves or run the risk of not being in the list.
     private static volatile OpenJCEPlus instance;
 
-    // User enabled debugging
-    private static Debug debug = Debug.getInstance(DEBUG_VALUE);
-
     private static boolean ockInitialized = false;
     private static OCKContext ockContext;
     private static Map<String, String> attrs;

src/main/java/com/ibm/crypto/plus/provider/OpenJCEPlusFIPS.java

@@ -24,7 +24,6 @@
 import java.util.List;
 import java.util.Map;
 import javax.crypto.SecretKey;
-import sun.security.util.Debug;
 
 @SuppressWarnings({"removal", "deprecation"})
 public final class OpenJCEPlusFIPS extends OpenJCEPlusProvider {
@@ -64,9 +63,6 @@ public final class OpenJCEPlusFIPS extends OpenJCEPlusProvider {
     // to find ourselves or run the risk of not being in the list.
     private static volatile OpenJCEPlusFIPS instance;
 
-    // User enabled debugging
-    private static Debug debug = Debug.getInstance(DEBUG_VALUE);
-
     private static boolean ockInitialized = false;
     private static OCKContext ockContext;
 

src/main/java/com/ibm/crypto/plus/provider/OpenJCEPlusProvider.java

@@ -9,7 +9,10 @@
 package com.ibm.crypto.plus.provider;
 
 import com.ibm.crypto.plus.provider.ock.OCKContext;
+import java.lang.ref.Cleaner;
 import java.security.ProviderException;
+import java.util.concurrent.atomic.AtomicInteger;
+import sun.security.util.Debug;
 
 // Internal interface for OpenJCEPlus and OpenJCEPlus implementation classes.
 // Implemented as an abstract class rather than an interface so that 
@@ -26,10 +29,40 @@ public abstract class OpenJCEPlusProvider extends java.security.Provider {
 
     static final String DEBUG_VALUE = "jceplus";
 
+    private final Cleaner[] cleaners;
+
+    private final int DEFAULT_NUM_CLEANERS = 2;
+
+    private final int numCleaners;
+
+    private AtomicInteger count = new AtomicInteger(0);
+
+    protected static final Debug debug = Debug.getInstance(DEBUG_VALUE); 
+
     OpenJCEPlusProvider(String name, String info) {
         super(name, PROVIDER_VER, info);
+
+        numCleaners = Integer.getInteger("openjceplus.cleaners.num", DEFAULT_NUM_CLEANERS);
+        if (numCleaners < 1){
+            throw new IllegalArgumentException(numCleaners + " is an invalid number of cleaner threads, must be at least 1.");
+        }
+
+        cleaners = new Cleaner[numCleaners];
+        for (int i = 0; i < numCleaners; i++) {
+            final Cleaner cleaner = Cleaner.create();
+            cleaners[i] = cleaner;
+        }
     }
 
+    public void registerCleanable(Object owner, Runnable cleanAction) {
+        Cleaner cleaner = cleaners[Math.abs(count.getAndIncrement() % numCleaners)];
+        cleaner.register(owner, cleanAction);
+    }
+
+    public static Debug getDebug() {
+        return debug;
+    }
+    
     // Get OCK context for crypto operations
     //
     abstract OCKContext getOCKContext();

src/main/java/com/ibm/crypto/plus/provider/RSASignature.java

@@ -35,7 +35,7 @@ abstract class RSASignature extends SignatureSpi {
         try {
             this.provider = provider;
             this.ockDigestAlgo = ockDigestAlgo;
-            this.signature = Signature.getInstance(provider.getOCKContext(), ockDigestAlgo);
+            this.signature = Signature.getInstance(provider.getOCKContext(), ockDigestAlgo, provider);
         } catch (Exception e) {
             throw provider.providerException("Failed to initialize RSA signature", e);
         }

src/main/java/com/ibm/crypto/plus/provider/ock/Digest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright IBM Corp. 2023, 2024
+ * Copyright IBM Corp. 2023, 2025
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms provided by IBM in the LICENSE file that accompanied
@@ -8,6 +8,7 @@
 
 package com.ibm.crypto.plus.provider.ock;
 
+import com.ibm.crypto.plus.provider.OpenJCEPlusProvider;
 import java.security.AccessController;
 import java.security.PrivilegedAction;
 import java.util.concurrent.ConcurrentLinkedQueue;
@@ -29,7 +30,7 @@ public final class Digest implements Cloneable {
     // -2   : Not a SHA* digest algorithm
     private int algIndx = -1;
 
-    private boolean needsReinit = false;
+    private BoolWrapper needsReinit = new BoolWrapper(false);
 
     private boolean contextFromQueue = false;
 
@@ -137,44 +138,28 @@ void getContext() throws OCKException {
                 this.contextFromQueue = true;
             }
         }
-        this.needsReinit = false;
+        this.needsReinit.setValue(false);
     }
 
-    void releaseContext() throws OCKException {
+    /* end digest caching mechanism
+     * ===========================================================================
+     */
 
-        if (this.digestId == 0) {
-            return;
+    /* This wrapper is used to pass a primitive variable as a parameter by reference instead of by value to the cleaner. */
+    public class BoolWrapper {
+        boolean value;
+        public BoolWrapper(boolean value) {
+            this.value = value;
         }
 
-        // not SHA* algorithm
-        if (this.algIndx == -2) {
-            if (validId(this.digestId)) {
-                NativeInterface.DIGEST_delete(this.ockContext.getId(),
-                        this.digestId);
-                this.digestId = 0;
-            }
-        } else {
-            if (this.contextFromQueue) {
-                // reset now to make sure all contexts in the queue are ready to use
-                this.reset();
-                contexts[this.algIndx].add(this.digestId);
-                this.digestId = 0;
-                this.contextFromQueue = false;
-            } else {
-                // delete context
-                if (validId(this.digestId)) {
-                    NativeInterface.DIGEST_delete(this.ockContext.getId(),
-                            this.digestId);
-                    this.digestId = 0;
-                }
-            }
+        public boolean getValue(){
+            return this.value;
         }
-        this.digestId = 0;
-    }
 
-    /* end digest caching mechanism
-     * ===========================================================================
-     */
+        public void setValue(boolean value) {
+            this.value = value;
+        }
+    }
 
     private OCKContext ockContext = null;
     private int digestLength = 0;
@@ -185,7 +170,9 @@ void releaseContext() throws OCKException {
 
     private long digestId = 0;
 
-    public static Digest getInstance(OCKContext ockContext, String digestAlgo) throws OCKException {
+    private OpenJCEPlusProvider provider;
+
+    public static Digest getInstance(OCKContext ockContext, String digestAlgo, OpenJCEPlusProvider provider) throws OCKException {
         if (ockContext == null) {
             throw new IllegalArgumentException("context is null");
         }
@@ -194,15 +181,23 @@ public static Digest getInstance(OCKContext ockContext, String digestAlgo) throw
             throw new IllegalArgumentException("digestAlgo is null/empty");
         }
 
-        return new Digest(ockContext, digestAlgo);
+        return new Digest(ockContext, digestAlgo, provider);
     }
 
-    private Digest(OCKContext ockContext, String digestAlgo) throws OCKException {
+    private Digest(OCKContext ockContext, String digestAlgo, OpenJCEPlusProvider provider) throws OCKException {
         //final String methodName = "Digest(String)";
         this.ockContext = ockContext;
         this.digestAlgo = digestAlgo;
+        this.provider = provider;
         getContext();
         //OCKDebug.Msg(debPrefix, methodName,  "digestAlgo :" + digestAlgo);
+
+        if (provider == null) {
+            throw new IllegalArgumentException("Provider cannot be null.");
+        }
+        
+        this.provider.registerCleanable(this, cleanOCKResources(digestId, algIndx,
+            contextFromQueue, needsReinit, ockContext));
     }
 
     private Digest() {
@@ -245,7 +240,7 @@ public synchronized void update(byte[] input, int offset, int length) throws OCK
         if (errorCode < 0) {
             throwOCKException(errorCode);
         }
-        this.needsReinit = true;
+        this.needsReinit.setValue(true);
     }
 
     public synchronized byte[] digest() throws OCKException {
@@ -267,7 +262,7 @@ public synchronized byte[] digest() throws OCKException {
         if (errorCode < 0) {
             throwOCKException(errorCode);
         }
-        this.needsReinit = false;
+        this.needsReinit.setValue(false);
 
         return digestBytes;
     }
@@ -299,10 +294,10 @@ public synchronized void reset() throws OCKException {
         if (!validId(this.digestId)) {
             throw new OCKException(badIdMsg);
         }
-        if (this.needsReinit) {
+        if (this.needsReinit.getValue()) {
             NativeInterface.DIGEST_reset(this.ockContext.getId(), this.digestId);
         }
-        this.needsReinit = false;
+        this.needsReinit.setValue(false);
     }
 
     private synchronized void obtainDigestLength() throws OCKException {
@@ -324,18 +319,6 @@ private synchronized void obtainDigestLength() throws OCKException {
         }
     }
 
-    @Override
-    protected synchronized void finalize() throws Throwable {
-        //final String methodName = "finalize";
-
-        try {
-            //OCKDebug.Msg(debPrefix, methodName,  "digestId =" + this.digestId);
-            releaseContext();
-        } finally {
-            super.finalize();
-        }
-    }
-
     /* At some point we may enhance this function to do other validations */
     protected static boolean validId(long id) {
         //final String methodName = "validId";
@@ -355,9 +338,10 @@ public synchronized Object clone() throws CloneNotSupportedException {
         copy.digestLength = this.digestLength;
         copy.algIndx = this.algIndx;
         copy.digestAlgo = new String(this.digestAlgo);
-        copy.needsReinit = this.needsReinit;
+        copy.needsReinit.setValue(this.needsReinit.getValue());
         copy.ockContext = this.ockContext;
         copy.contextFromQueue = false;
+        copy.provider = this.provider;
 
         // Allocate a new context for the digestId and copy all state information from our
         // original context into the copy. 
@@ -374,6 +358,41 @@ public synchronized Object clone() throws CloneNotSupportedException {
                                       .collect(Collectors.joining("\n"));
             throw new CloneNotSupportedException(stackTrace);
         }
+
+        this.provider.registerCleanable(copy, cleanOCKResources(copy.digestId, copy.algIndx,
+            copy.contextFromQueue, copy.needsReinit, copy.ockContext));
         return copy;
     }
+
+    private Runnable cleanOCKResources(long digestId, int algIndx, boolean contextFromQueue,
+            BoolWrapper needsReinit, OCKContext ockContext) {
+        return () -> {
+            try {
+                if (digestId == 0) {
+                    throw new OCKException("Digest Identifier is not valid");
+                }
+                // not SHA* algorithm
+                if (algIndx == -2) {
+                    if (validId(digestId)) {
+                        NativeInterface.DIGEST_delete(ockContext.getId(), digestId);
+                    }
+                } else {
+                    if (contextFromQueue) {
+                        // reset now to make sure all contexts in the queue are ready to use
+                        if (needsReinit.getValue()) {
+                            NativeInterface.DIGEST_reset(ockContext.getId(), digestId);
+                        }
+                        Digest.contexts[algIndx].add(digestId);
+                    } else {
+                        NativeInterface.DIGEST_delete(ockContext.getId(), digestId);
+                    }
+                }
+            } catch (OCKException e) {
+                if (OpenJCEPlusProvider.getDebug() != null) {
+                    OpenJCEPlusProvider.getDebug().println("An error occurred while cleaning : " + e.getMessage());
+                    e.printStackTrace();
+                }
+            }
+        };
+    }
 }