Key extraction using JCE
The Java Cryptography Extension (JCE) uses an architecture that allows different cryptography implementations to be plugged in. AWS CloudHSM ships one such JCE provider that offloads cryptographic operations to the HSM. For most other JCE providers to work with keys stored in AWS CloudHSM, they must extract the key bytes from your HSMs in clear text into your machine’s memory for their use. HSMs typically only allow keys to be extracted as wrapped objects, not clear text. However, to support inter-provider integration use cases, AWS CloudHSM allows an opt-in configuration option to enable extraction of the key bytes in the clear.
Important
JCE offloads operations to AWS CloudHSM whenever the AWS CloudHSM provider is specified or an AWS CloudHSM key object is used. You do not need to extract keys in clear if you expect your operation to happen inside the HSM. Key extraction in clear text is only needed when your application cannot use secure mechanisms such as wrapping and unwrapping a key due to restrictions from a third party library or JCE provider.
The AWS CloudHSM JCE Provider allows extraction of public keys to work with external JCE providers by default. The following methods are always allowed:
| Class | Method | Format (getEncoded) |
|---|---|---|
| EcPublicKey | getEncoded() | X.509 |
| getW() | N/A | |
| RSAPublicKey | getEncoded() | X.509 |
| getPublicExponent() | N/A | |
| CloudHsmRsaPrivateCrtKey | getPublicExponent() | N/A |
The AWS CloudHSM JCE Provider doesn’t allow extraction of key bytes in clear for the private or secret keys by default. If your use case requires it, you can enable extraction of key bytes in clear for private or secret keys under the following conditions:
The
EXTRACTABLEattribute for private and secret keys is set to true.By default, the
EXTRACTABLEattribute for private and secret keys is set to true.EXTRACTABLEkeys are keys that are permitted to be exported out of the HSM. For more information see Supported Java attributes for Client SDK 5.
The
WRAP_WITH_TRUSTEDattribute for the private and secret keys is set to false.getEncoded,getPrivateExponent, andgetScannot be used with private keys that cannot be exported in clear.WRAP_WITH_TRUSTEDdoesn't allow your private keys to exported out of the HSM in clear. For more information see Using trusted keys to control key unwraps.
Allowing the AWS CloudHSM JCE provider to extract private key secrets out of AWS CloudHSM
Important
This configuration change allows extraction of all EXTRACTABLE key bytes in clear from your HSM cluster. For better security,
you should consider using key wrapping methods to extract the key out of the HSM securely. This prevents unintentional extraction of your key bytes from the HSM.
Use the following commands to enable your private or secret keys to be extracted in JCE:
-
Once you enable your clear key extraction, the following methods are enabled for extracting private keys into memory.
Class Method Format (getEncoded) Key getEncoded() RAW ECPrivateKey getEncoded() PKCS#8 getS() N/A RSAPrivateCrtKey getEncoded() X.509 getPrivateExponent() N/A getPrimeP() N/A getPrimeQ() N/A getPrimeExponentP() N/A getPrimeExponentQ() N/A getCrtCoefficient() N/A
If you want restore the default behavior and not allow JCE to export keys in clear, run the following command:
