1 /** 2 * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. 3 * SPDX-License-Identifier: Apache-2.0. 4 */ 5 6 package software.amazon.awssdk.crt.io; 7 8 import software.amazon.awssdk.crt.CrtResource; 9 10 /** 11 * Handle to a loaded PKCS#11 library. 12 * 13 * For most use cases, a single instance of Pkcs11Lib should be used for the 14 * lifetime of your application. 15 */ 16 public class Pkcs11Lib extends CrtResource { 17 18 /** 19 * Controls how Pkcs11Lib calls {@code C_Initialize()} and {@code C_Finalize()} 20 * on the PKCS#11 library. 21 */ 22 public enum InitializeFinalizeBehavior { 23 /** 24 * Default behavior that accommodates most use cases. 25 * 26 * {@code C_Initialize()} is called on creation, and "already-initialized" 27 * errors are ignored. {@code C_Finalize()} is never called, just in case 28 * another part of your application is still using the PKCS#11 library. 29 */ 30 DEFAULT(0), 31 32 /** 33 * Skip calling {@code C_Initialize()} and {@code C_Finalize()}. 34 * 35 * Use this if your application has already initialized the PKCS#11 library, and 36 * you do not want {@code C_Initialize()} called again. 37 */ 38 OMIT(1), 39 40 /** 41 * {@code C_Initialize()} is called on creation and {@code C_Finalize()} is 42 * called on cleanup. 43 * 44 * If {@code C_Initialize()} reports that's it's already initialized, this is 45 * treated as an error. Use this if you need perfect cleanup (ex: running 46 * valgrind with --leak-check). 47 */ 48 STRICT(2); 49 InitializeFinalizeBehavior(int nativeValue)50 InitializeFinalizeBehavior(int nativeValue) { 51 this.nativeValue = nativeValue; 52 } 53 54 int nativeValue; 55 } 56 57 /** 58 * Load and initialize a PKCS#11 library. 59 * 60 * {@code C_Initialize()} and {@code C_Finalize()} are called on the PKCS#11 61 * library in the {@link InitializeFinalizeBehavior#DEFAULT DEFAULT} way. 62 * 63 * @param path path to PKCS#11 library. 64 */ Pkcs11Lib(String path)65 public Pkcs11Lib(String path) { 66 this(path, InitializeFinalizeBehavior.DEFAULT); 67 } 68 69 /** 70 * Load a PKCS#11 library, specifying how {@code C_Initialize()} and 71 * {@code C_Finalize()} will be called. 72 * 73 * @param path path to PKCS#11 library. 74 * @param initializeFinalizeBehavior specifies how {@code C_Initialize()} and 75 * {@code C_Finalize()} will be called on the 76 * PKCS#11 library. 77 */ Pkcs11Lib(String path, InitializeFinalizeBehavior initializeFinalizeBehavior)78 public Pkcs11Lib(String path, InitializeFinalizeBehavior initializeFinalizeBehavior) { 79 acquireNativeHandle(pkcs11LibNew(path, initializeFinalizeBehavior.nativeValue)); 80 } 81 82 @Override canReleaseReferencesImmediately()83 protected boolean canReleaseReferencesImmediately() { 84 return true; 85 } 86 87 @Override releaseNativeHandle()88 protected void releaseNativeHandle() { 89 if (!isNull()) { 90 pkcs11LibRelease(getNativeHandle()); 91 } 92 } 93 94 /******************************************************************************* 95 * native methods 96 ******************************************************************************/ pkcs11LibNew(String path, int initializeFinalizeBehavior)97 private static native long pkcs11LibNew(String path, int initializeFinalizeBehavior); 98 pkcs11LibRelease(long nativeHandle)99 private static native void pkcs11LibRelease(long nativeHandle); 100 } 101