# PKCS\$111 provider
<a name="pkcs11-provider-component"></a>

The PKCS\$111 provider component (`aws.greengrass.crypto.Pkcs11Provider`) enables you to configure the AWS IoT Greengrass Core software to use a hardware security module (HSM) through the [PKCS\$111 interface](https://en.wikipedia.org/wiki/PKCS_11). This component enables you to securely store certificate and private key files so that they aren't exposed or duplicated in software. For more information, see [Hardware security integration](hardware-security.md).

**Note**  
This component is required for [Greengrass nucleus](greengrass-nucleus-component.md) only. [Greengrass nucleus lite](greengrass-nucleus-lite-component.md) v2.5.0 and later includes built-in PKCS\$111 support and does not require this component. For more information, see [PKCS\$111 support](https://github.com/aws-greengrass/aws-greengrass-lite/blob/main/docs/PKCS11_SUPPORT.md) in the AWS IoT Greengrass nucleus lite GitHub repository.

To provision a Greengrass core device that stores its certificate and private key in an HSM, you must specify this component as a provisioning plugin when you install the AWS IoT Greengrass Core software. For more information, see [Install AWS IoT Greengrass Core software with manual resource provisioning](manual-installation.md).

AWS IoT Greengrass provides this component as JAR file that you can download to specify as a provisioning plugin during installation. You can download the latest version of the component's JAR file as the following URL: [https://d2s8p88vqu9w66.cloudfront.net/releases/Pkcs11Provider/aws.greengrass.crypto.Pkcs11Provider-latest.jar](https://d2s8p88vqu9w66.cloudfront.net/releases/Pkcs11Provider/aws.greengrass.crypto.Pkcs11Provider-latest.jar).

**Topics**
+ [Versions](#pkcs11-provider-component-versions)
+ [Type](#pkcs11-provider-component-type)
+ [Operating system](#pkcs11-provider-component-os-support)
+ [Requirements](#pkcs11-provider-component-requirements)
+ [Dependencies](#pkcs11-provider-component-dependencies)
+ [Configuration](#pkcs11-provider-component-configuration)
+ [Local log file](#pkcs11-provider-component-log-file)
+ [Changelog](#pkcs11-provider-component-changelog)

## Versions
<a name="pkcs11-provider-component-versions"></a>

This component has the following versions:
+ 2.0.x

## Type
<a name="pkcs11-provider-component-type"></a>

<a name="public-component-type-plugin-para1"></a>This component is a plugin component (`aws.greengrass.plugin`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when you change this component's version on the core device.

<a name="public-component-type-plugin-para2"></a>This component uses the same log file as the Greengrass nucleus. For more information, see [Monitor AWS IoT Greengrass logs](monitor-logs.md).

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system
<a name="pkcs11-provider-component-os-support"></a>

This component can be installed on Linux core devices only.

## Requirements
<a name="pkcs11-provider-component-requirements"></a>

This component has the following requirements:
+ <a name="hardware-security-module-requirements-key"></a>A hardware security module that supports the [PKCS\$11 v1.5](https://tools.ietf.org/html/rfc2313) signature scheme and RSA keys with an RSA-2048 key size (or larger) or ECC keys.
**Note**  <a name="hardware-security-module-requirements-key-notes"></a>
To use a hardware security module with ECC keys, you must use [Greengrass nucleus](greengrass-nucleus-component.md) v2.5.6 or later.  
To use a hardware security module and [secret manager](secret-manager-component.md), you must use a hardware security module with RSA keys.
+ <a name="hardware-security-module-requirements-pkcs11-provider-library"></a>A PKCS\$111 provider library that the AWS IoT Greengrass Core software can load at runtime (using libdl) to invoke PKCS\$111 functions. The PKCS\$111 provider library must implement the following PKCS\$111 API operations:
  + `C_Initialize`
  + `C_Finalize`
  + `C_GetSlotList`
  + `C_GetSlotInfo`
  + `C_GetTokenInfo`
  + `C_OpenSession`
  + `C_GetSessionInfo`
  + `C_CloseSession`
  + `C_Login`
  + `C_Logout`
  + `C_GetAttributeValue`
  + `C_FindObjectsInit`
  + `C_FindObjects`
  + `C_FindObjectsFinal`
  + `C_DecryptInit`
  + `C_Decrypt`
  + `C_DecryptUpdate`
  + `C_DecryptFinal`
  + `C_SignInit`
  + `C_Sign`
  + `C_SignUpdate`
  + `C_SignFinal`
  + `C_GetMechanismList`
  + `C_GetMechanismInfo`
  + `C_GetInfo`
  + `C_GetFunctionList`
+ <a name="hardware-security-module-requirements-slot-label"></a>The hardware module must be resolvable by slot label, as defined in the PKCS\$111 specification.
+ <a name="hardware-security-module-requirements-private-key-and-certificate"></a>You must store the private key and certificate in the HSM in the same slot, and they must use the same object label and object ID, if the HSM supports object IDs.
+ <a name="hardware-security-module-requirements-object-label"></a>The certificate and private key must be resolvable by object labels.
+ <a name="hardware-security-module-requirements-private-key-permissions"></a>The private key must have the following permissions:
  + `sign`
  + `decrypt`
+ <a name="hardware-security-module-requirements-secret-manager-permissions"></a>(Optional) To use the [secret manager component](secret-manager-component.md), you must use version 2.1.0 or later, and the private key must have the following permissions:
  + `unwrap`
  + `wrap`
+ <a name="hardware-security-module-requirements-environment-variable"></a>(Optional) If you are using the TPM2 library and running the Greengrass core as a service, you must provide an environment variable with the location of the PKCS\$111 store. The following example is a systemd service file with the required environment variable:

  ```
  [Unit]
  Description=Greengrass Core
  After=network.target
  
  [Service]
  Type=simple
  PIDFile=/var/run/greengrass.pid
  Environment=TPM2_PKCS11_STORE=/path/to/store/directory
  RemainAfterExit=no
  Restart=on-failure
  RestartSec=10
  ExecStart=/bin/sh /greengrass/v2/alts/current/distro/bin/loader
  
  [Install]
  WantedBy=multi-user.target
  ```

## Dependencies
<a name="pkcs11-provider-component-dependencies"></a>

When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#pkcs11-provider-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.0.11 ]

The following table lists the dependencies for version 2.0.11 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.3 <2.17.0 | Soft | 

------
#### [ 2.0.10 ]

The following table lists the dependencies for version 2.0.10 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.3 <2.16.0  | Soft | 

------
#### [ 2.0.9 ]

The following table lists the dependencies for version 2.0.9 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.3 <2.15.0  | Soft | 

------
#### [ 2.0.8 ]

The following table lists the dependencies for version 2.0.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.3 <2.14.0  | Soft | 

------
#### [ 2.0.7 ]

The following table lists the dependencies for version 2.0.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.3 <2.13.0  | Soft | 

------
#### [ 2.0.6 ]

The following table lists the dependencies for version 2.0.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.3 <2.12.0  | Soft | 

------
#### [ 2.0.5 ]

The following table lists the dependencies for version 2.0.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.3 <2.11.0  | Soft | 

------
#### [ 2.0.4 ]

The following table lists the dependencies for version 2.0.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.3 <2.10.0  | Soft | 

------
#### [ 2.0.3 ]

The following table lists the dependencies for version 2.0.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.3 <2.9.0  | Soft | 

------
#### [ 2.0.2 ]

The following table lists the dependencies for version 2.0.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.3 <2.8.0  | Soft | 

------
#### [ 2.0.1 ]

The following table lists the dependencies for version 2.0.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.5.3 <2.7.0  | Soft | 

------
#### [ 2.0.0 ]

The following table lists the dependencies for version 2.0.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.5.3 <2.6.0  | Soft | 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration
<a name="pkcs11-provider-component-configuration"></a>

This component provides the following configuration parameters that you can customize when you deploy the component.<a name="pkcs11-provider-component-configuration-parameters"></a>

`name`  
A name for the PKCS\$111 configuration.

`library`  
The absolute file path to the PKCS\$111 implementation's library that the AWS IoT Greengrass Core software can load with libdl.

`slot`  
The ID of the slot that contains the private key and device certificate. This value is different than the slot index or slot label.

`userPin`  
The user PIN to use to access the slot.

**Example: Configuration merge update**  

```
{
  "name": "softhsm_pkcs11",
  "library": "/usr/lib/softhsm/libsofthsm2.so",
  "slot": 1,
  "userPin": "1234"
}
```

## Local log file
<a name="pkcs11-provider-component-log-file"></a>

This component uses the same log file as the [Greengrass nucleus](greengrass-nucleus-component.md) component.

------
#### [ Linux ]

```
/greengrass/v2/logs/greengrass.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\greengrass.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/greengrass.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
  ```

------

## Changelog
<a name="pkcs11-provider-component-changelog"></a>

The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.0.12  |  Updates the component version for the Greengrass nucleus version 2.17.0 release.  | 
|  2.0.11  |  Version updated for Greengrass nucleus version 2.16.0 release.  | 
|  2.0.10  | Version updated for Greengrass nucleus version 2.15.0 release. | 
|  2.0.9  | Version updated for Greengrass nucleus version 2.14.0 release. | 
|  2.0.8  | Version updated for Greengrass nucleus version 2.13.0 release. | 
|  2.0.7  | Version updated for Greengrass nucleus version 2.12.0 release. | 
|  2.0.6  | Version updated for Greengrass nucleus version 2.11.0 release. | 
|  2.0.5  | Version updated for Greengrass nucleus version 2.10.0 release. | 
|  2.0.4  | Version updated for Greengrass nucleus version 2.9.0 release. | 
|  2.0.3  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  2.0.2  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  2.0.1  |  Version updated for Greengrass nucleus version 2.6.0 release.  | 
|  2.0.0  |  Initial version.  |