Fix Node HSM sample

Also:
- Tidy up README documentation.
- Add MacOS/Homebrew (Apple silicon) default SoftHSM library location to HSM scripts and sample applications to avoid the need to explicitly override the library location when running the sample.

Signed-off-by: Mark S. Lewis <mark_lewis@uk.ibm.com>

hardware-security-module/README.md

@@ -1,17 +1,12 @@
-# Fabric Gateway HSM Samples
+# Hardware Security Module Samples
 
-The samples show how to create client applications that invoke transactions with HSM Identities using the
-new embedded Gateway in Fabric.
+The samples show how to create client applications that invoke transactions using identity credentials stored in a Hardware Security Module (HSM). When using an HSM, private keys for a Fabric enrollment are stored within a dedicated hardware module. The private keys are not accessible outside of the HSM, and messages are sent to the HSM to be signed.
 
-The samples will only run against Fabric v2.4 and higher.
+The samples use the Fabric Gateway client API and will only run against Fabric v2.4 and higher.
 
-Sample client applications are available to demonstrate the features of the Fabric Gateway and associated SDKs using this network.
+## Install prerequisites
 
-> **_NOTE:_**  When you use an HSM, private keys for a Fabric enrollment are stored within a dedicated hardware module, rather than in plain text on a local file system.
-
-## Installations
-
-### C Compilers
+### C compilers
 
 In order for the client application to run successfully you must ensure you have C compilers and Python 3 (Note that Python 2 may still work however Python 2 is out of support and could stop working in the future) installed otherwise the node dependency `pkcs11js` will not be built and the application will fail. The failure will have an error such as
 
@@ -23,26 +18,15 @@ how to install the required C Compilers and Python will depend on your operating
 
 ### SoftHSM
 
-In order to run the application in the absence of a real HSM, a software
-emulator of the PKCS#11 interface is required.
-For more information please refer to [SoftHSM](https://www.opendnssec.org/softhsm/).
-
-SoftHSM can either be installed using the package manager for your host system:
-
-* Ubuntu: `sudo apt install softhsm2`
-* macOS: `brew install softhsm`
-* Windows: **unsupported**
-
-Or compiled and installed from source:
-
-1. install openssl 1.0.0+ or botan 1.10.0+
-2. download the source code from <https://dist.opendnssec.org/source/softhsm-2.5.0.tar.gz>
-3. `tar -xvf softhsm-2.5.0.tar.gz`
-4. `cd softhsm-2.5.0`
-5. `./configure --disable-gost` (would require additional libraries, turn it off unless you need 'gost' algorithm support for the Russian market)
-6. `make`
-7. `sudo make install`
+In order to run the application in the absence of a real HSM, a software emulator of the PKCS#11 interface ([SoftHSM v2](https://www.opendnssec.org/softhsm/)) is required. This can either be:
 
+- installed using the package manager for your host system:
+  - Ubuntu: `sudo apt install softhsm2`
+  - macOS: `brew install softhsm`
+  - Windows: **unsupported**
+- or compiled and installed from source, following the [SoftHSM2 install instructions](https://wiki.opendnssec.org/display/SoftHSMDOCS/SoftHSM+Documentation+v2)
+  - It is recommended to use the `--disable-gost` option unless you need **gost** algorithm support for the Russian market, since it requires additional libraries.
+  
 ### PKCS#11 enabled fabric-ca-client binary
 To be able to register and enroll identities using an HSM you need a PKCS#11 enabled version of `fabric-ca-client`
 To install this use the following command
@@ -51,17 +35,17 @@ To install this use the following command
 go install -tags 'pkcs11' github.com/hyperledger/fabric-ca/cmd/fabric-ca-client@latest
 ```
 
-## Running the sample
+## Create Fabric network and deploy the smart contract
 
 The Fabric test network is used to deploy and run this sample. Follow these steps in order:
 
 1. Create the test network and a channel (from the `test-network` folder).
-   ```
+   ```bash
    ./network.sh up createChannel -ca
    ```
 
 2. Deploy one of the smart contract implementations (from the `test-network` folder).
-   ```
+   ```bash
    # To deploy the TypeScript chaincode implementation
    ./network.sh deployCC -ccn basic -ccp ../asset-transfer-basic/chaincode-typescript/ -ccl typescript
 
@@ -77,9 +61,9 @@ The Fabric test network is used to deploy and run this sample. Follow these step
 If you have not initialized a token previously (or it has been deleted) then you will need to perform this one time operation
 
 ```bash
-echo directories.tokendir = /tmp > $HOME/softhsm2.conf
-export SOFTHSM2_CONF=$HOME/softhsm2.conf
-softhsm2-util --init-token --slot 0 --label "ForFabric" --pin 98765432 --so-pin 1234
+mkdir -p "${TMPDIR:-/tmp}/softhsm"
+echo "directories.tokendir = ${TMPDIR:-/tmp}/softhsm" > "${HOME}/softhsm2.conf"
+SOFTHSM2_CONF="${HOME}/softhsm2.conf" softhsm2-util --init-token --slot 0 --label "ForFabric" --pin 98765432 --so-pin 1234
 ```
 
 This will create a SoftHSM configuration file called `softhsm2.conf` and will be stored in the home directory. This is
@@ -93,37 +77,46 @@ generating and retrieving keys.
 
 A user, `HSMUser`, who is HSM managed needs to be registered then enrolled for the sample.
 
-If your PKCS11 library (libsofthsm2.so) is not located in one of the typical Linux system locations checked by this sample's scripts and applications, you will need to explicitly specify the library location using the `PKCS11_LIB` environment variable.
+If your PKCS11 library (libsofthsm2.so) is not located in one of the typical system locations checked by this sample's scripts and applications, you will need to explicitly specify the library location using the `PKCS11_LIB` environment variable.
 
 ```bash
 export PKCS11_LIB='<path to PKCS11 library location>'
 ```
 Register a user `HSMUser` with the CA in Org1 (if not already registered) and then enroll that user which will generate a certificate on the file system for use by the sample. The private key is stored in SoftHSM.
 
+From the `hardware-security-module` folder, run the command:
+
 ```bash
-scripts/generate-hsm-user.sh HSMUser
+SOFTHSM2_CONF="${HOME}/softhsm2.conf" ./scripts/generate-hsm-user.sh HSMUser
 ```
 
-### Go SDK
+## Run the sample application
 
-For HSM support you need to ensure you include the `pkcs11` build tag.
+### Go
+
+For HSM support you need to ensure you include the `pkcs11` build tag. From the `hardware-security-module/application-go` folder, run the command:
 
 ```
-cd hardware-security-module/application-go
-go run -tags pkcs11 .
+SOFTHSM2_CONF="${HOME}/softhsm2.conf" go run -tags pkcs11 .
 ```
 
-### Node SDK
+### Node
+
+From the `hardware-security-module/application-typescript` folder, run the commands:
 
 ```
-cd hardware-security-module/application-typescript
 npm install
-npm start
+SOFTHSM2_CONF="${HOME}/softhsm2.conf" npm start
 ```
+
 ## Cleanup
 
 When you are finished running the samples, the local test-network can be brought down with the following command (from the `test-network` folder):
 
  ```
 ./network.sh down
-```
+```
+
+Created public credentials can be removed from the filesystem by deleting the `hardware-security-module/crypto-material` folder.
+
+SoftHSM tokens and private credentials stored within them can be removed by deleting the `${TMPDIR:-/tmp}/softhsm` folder.

hardware-security-module/application-go/hsm-sample.go

@@ -190,6 +190,7 @@ func findSoftHSMLibrary() string {
 		"/usr/lib/x86_64-linux-gnu/softhsm/libsofthsm2.so",
 		"/usr/local/lib/softhsm/libsofthsm2.so",
 		"/usr/lib/libacsp-pkcs11.so",
+		"/opt/homebrew/lib/softhsm/libsofthsm2.so",
 	}
 	pkcs11lib := os.Getenv("PKCS11_LIB")
 	if pkcs11lib != "" {

hardware-security-module/application-typescript/src/hsm-sample.ts

@@ -22,7 +22,7 @@ const utf8Decoder = new TextDecoder();
 
 const certPath = path.resolve(__dirname, '..', '..', 'crypto-material', 'hsm', user, 'signcerts', 'cert.pem');
 
-const tlsCertPath = path.resolve('..', '..', 'test-network','organizations','peerOrganizations', 'org1.example.com', 'peers', 'peer0.org1.example.com', 'tls', 'ca.crt');
+const tlsCertPath = path.resolve(__dirname, '..', '..', '..', 'test-network','organizations','peerOrganizations', 'org1.example.com', 'peers', 'peer0.org1.example.com', 'tls', 'ca.crt');
 const peerEndpoint = 'localhost:7051';
 
 async function main() {
@@ -55,16 +55,15 @@ async function main() {
     } finally {
         gateway?.close();
         client?.close();
-        hsmSignerFactory?.dispose();
-        // close the HSM Signer
         hsmSigner?.close();
+        hsmSignerFactory?.dispose();
     }
 }
 
 async function exampleTransaction(gateway: Gateway):Promise<void> {
 
     const channelName = envOrDefault('CHANNEL_NAME', 'mychannel');
-    const chaincodeName = envOrDefault('CHAINCODE_NAME', 'default-basic');
+    const chaincodeName = envOrDefault('CHAINCODE_NAME', 'basic');
 
     const network = gateway.getNetwork(channelName);
     const contract = network.getContract(chaincodeName);
@@ -122,6 +121,7 @@ function findSoftHSMPKCS11Lib(): string {
         '/usr/lib/x86_64-linux-gnu/softhsm/libsofthsm2.so',
         '/usr/local/lib/softhsm/libsofthsm2.so',
         '/usr/lib/libacsp-pkcs11.so',
+        '/opt/homebrew/lib/softhsm/libsofthsm2.so'
     ];
     const pkcs11lib = process.env['PKCS11_LIB'];
     if (pkcs11lib) {

hardware-security-module/scripts/generate-hsm-user.sh

@@ -19,6 +19,7 @@ LocateHsmLib() {
     '/usr/lib/x86_64-linux-gnu/softhsm/libsofthsm2.so' \
     '/usr/local/lib/softhsm/libsofthsm2.so' \
     '/usr/lib/libacsp-pkcs11.so' \
+    '/opt/homebrew/lib/softhsm/libsofthsm2.so' \
   )
   for TEST_LIB in "${POSSIBLE_LIB_LOC[@]}"; do
     if [ -f "${TEST_LIB}" ]; then