Fabric and AWS CloudHSM doc updates

[theblop]

Hello,

Are there any detailed docs about how to configure fabric with AWS CloudHSM?

I've set up a CloudHSM instance and can connect to it with the cloudhsm_mgmt_util tool. I created a CU "fabric" user and I configured the fabric-ca-client tool like this:

bccsp:
  default: PKCS11
  pkcs11:
      Library: /opt/cloudhsm/lib/libcloudhsm_pkcs11.so
      Pin: 'fabric:password'
      AltId: FABRIC
      Label: cavium
      hash: SHA2
      security: 256                                        

However when I try to enroll a user with fabric-ca-client I get this error:
Error: Failed to get BCCSP with opts: Could not initialize BCCSP PKCS11: pkcs11: could not find token with label cavium

Here is the libcloudhsm log:

root@ee2506438d16:/etc/hyperledger/fabric-ca-client# cat /opt/cloudhsm/run/cloudhsm-pkcs11.log.2021-10-06 
2021-10-06T20:20:03.895+02:00 INFO  [30] ThreadId(5) [cloudhsm_provider::hsm1::connection::connection_pool] Adding HSM connection to connection pool: HsmConnection { hsm_info: HSM { IP: "10.4.1.189", Port: 2223 } }
2021-10-06T20:20:03.899+02:00 INFO  [30] ThreadId(5) [cloudhsm_provider::hsm1::hsm_connection::server_connection::common] Initializing new connection: HSM { IP: "10.4.1.189", Port: 2223 }
2021-10-06T20:20:03.944+02:00 INFO  [30] ThreadId(5) [cloudhsm_provider::hsm1::hsm_connection::server_properties] Version handshake with server succeeded. Received version: ComponentVersion { major: 2, minor: 3 }
2021-10-06T20:20:03.945+02:00 INFO  [30] ThreadId(5) [hsm1_marshaling::server_handshake] Reporting sdk version Pkcs11:5.2-1-bionic:CodeBuildBatchProject-uFu5sNXfquqK:ed9a3dbd-7172-439f-8ee3-79408d4e3f39
2021-10-06T20:20:03.992+02:00 WARN  [30] ThreadId(2) [cloudhsm_provider::hsm1::hsm_connection::dispatcher_strategy] UX000: Discarding HSM response because it does not match a pending request.
2021-10-06T20:20:04.043+02:00 INFO  [30] ThreadId(5) [cloudhsm_provider::hsm1::connection::device] Retrieving HSM information.

(I know I'm talking about fabric-ca-client and not fabric-peer or orderer but I guess it's the same code between the 2 projects)

In any case, a detailed setup guide with AWS CloudHSM would be very welcome in the Fabric docs.

[theblop]

After some extensive googling I found that the label should be the HSM cluster name:

This gets me a bit further (I init a brand new fabric ca server here as a simpler example than enroll):

env FABRIC_CA_SERVER_BCCSP_PKCS11_LABEL=cluster-dzetr75hznp fabric-ca-server init -b admin:adminpw

2021/10/06 22:14:40 [FATAL] Initialization failure: Failed generating ECDSA P256 key: P11: keypair generate failed [pkcs11: 0x13: CKR_ATTRIBUTE_VALUE_INVALID]

[denyeart]

@davidkel Should the label suggestion and/or other troubleshooting tips be added to the HSM docs?

[theblop]

2021/10/06 22:14:40 [FATAL] Initialization failure: Failed generating ECDSA P256 key: P11: keypair generate failed [pkcs11: 0x13: CKR_ATTRIBUTE_VALUE_INVALID]

Actually that error was because the AltId value was the same between 2 fabric-ca-server init runs... Now I have that same issue with the TLS cert generation when starting the ca server. Maybe it's trying to use the same AltId to generate the TLS cert in the HSM?
Anyway I'll report that issue in the fabric-ca repo...

[davidkel]

@denyeart Looks like the label field is dependent on the version of the cloudhsm library used. For v3 it's cavium but for v5 its looks to have changed and is the cluster name (I would hope that the AWS docs would provide this information though). We could add some detail to the docs about this as well as iterate that the AltId value for each certificate in the same HSM must be unique.

[theblop]

We could add some detail to the docs about this as well as iterate that the AltId value for each certificate in the same HSM must be unique.

Ah that was my guess, the only discussion/documentation I found about the need and use of AltId for AWS CloudHSM are these links:

• https://jira.hyperledger.org/browse/FAB-16951
• and the corresponding github PR: [FAB-16951] Alternative mechanisms to find pkcs11 key #2479

I forgot to mention I am using fabric-ca v1.5.2 and fabric-peer v2.2.4.

If the AltId must really be unique for each cert enrolment then I think it's impossible to bootstrap a root fabric-ca-server with TLS enabled. The bootstrap steps are supposed to be:

1. fabric-ca-server init -b <bootstrap_user>:<password> => generates a self-signed identity cert for the root CA
2. fabric-ca-server start -d=> generates a self-signed TLS cert

These 2 steps use the same AltId value (there is no config option for a different AltId for TLS) so maybe that's why the TLS step fails with:

2021/10/06 22:14:40 [FATAL] Initialization failure: Failed generating ECDSA P256 key: P11: keypair generate failed [pkcs11: 0x13: CKR_ATTRIBUTE_VALUE_INVALID]

I'll be continuing this discussion about bootstrapping fabric-ca-server in hyperledger/fabric-ca#259 but as a first step it would indeed be very helpful to have more documentation regarding the peculiarities of the AWS CloudHSM configuration and limitations compared to softhsm for example.

[davidkel]

The documentation should also be checked to see if it states that TLS certificates cannot be managed by HSM for fabric (for a start TLS certs are outside the control of BCCSP) and should be added if it isn't there

[bh4rtp]

The documentation should also be checked to see if it states that TLS certificates cannot be managed by HSM for fabric (for a start TLS certs are outside the control of BCCSP) and should be added if it isn't there

I have confirmed that TLS certs are not managed by HSM in release-2.3.2.

[lakshaygaur]

@theblop Im facing the same issue, are you planning to write a blog or if you could explain the resolution here would be of great help, thanks.

[chetagra]

HI can u guys confirm if documentation for cloudhsm integration for fabric is updated

[denyeart]

The suggestions from this issue are not yet included in Fabric docs. We would welcome anybody with knowledge/experience on this topic to edit this page via pull request:
https://github.com/hyperledger/fabric/blob/main/docs/source/hsm.md

See also #2486 which was backported to release-2.2 and later branches.
"Add support for mapping subject key identifiers to cryptoki object CKA_ID attributes. This allows Fabric to use keys from token providers that do not support CKA_ID attribute modification." , such as AWS CloudHSM.

[denyeart]

While I don't have AWS CloudHSM expertise to update the docs, I've at least updated the docs in #5030 to indicate that HSM is not supported for TLS keys as per the above comment #2972 (comment).