# Configure proxy support and manage trust stores for AWS IoT SiteWise Edge
<a name="edge-apis-manage-trust-stores-proxy"></a>

In AWS IoT SiteWise Edge, configure and manage trust stores to set up proxy support for your edge devices. First, set up proxy configuration, then configure trust stores. You can configure trust stores either during gateway installation or manually after your gateway is established. 
+ **Proxies** – Facilitate connectivity between your edge devices and AWS services in various network environments.
+ **Trust stores** – Ensure secure connections by managing trusted certificates. Proper configurations help you comply with your network security policies, enable communication in restricted network environments, and optimize data transfer between edge devices and cloud services.

SiteWise Edge utilizes multiple trust stores for different component types, ensuring secure and efficient data flow from your edge devices to the cloud. You can configure trust stores and proxies on an existing gateway or during the installation process when creating a new gateway. 

## Requirements for trust store and proxy configurations
<a name="manage-trust-stores-proxy_implementation-requirements"></a>

Before you configure a trust store or install SiteWise Edge with proxy settings, ensure that you meet the prerequisites. There are varied implementation requirements based on your component usage and functionality requirements.

**Proxy support requirements**
+ The URL of your proxy server. The URL should include the user info, the port number for the host. For example, `scheme://[userinfo@]host[:port]`.
  + `scheme` – Must be HTTP or HTTPS
  + (Optional) `userinfo` – User name and password information
  + `host` – The host name or IP address of the proxy server
  + `port` – The port number
+ A list of addresses to bypass the proxy.
+ (Optional) The proxy CA certificate file if you're using an HTTPS proxy with a self-signed certificate.

**Trust store requirements**
+ For full data processing pack functionality with HTTPS proxy, you should update all three trust stores.
+ If you only use the IoT SiteWise OPC UA collector and IoT SiteWise publisher, update the certificates AWS IoT Greengrass Core and Java trust stores to the latest version.

## Best practices for trust store and proxy server edge configurations
<a name="manage-trust-stores-proxy_best-practices"></a>

For ongoing maintenance and to maintain the highest level of security in your edge environment:
+ Regularly review and update proxy settings to align with your network security requirements.
+ Monitor gateway connectivity and data flow to ensure proper proxy communication
+ Maintain and update trust stores according to your organization's certificate management policies
+ You can implement and follow our recommended best practices for secure communication in edge environments, such as:
+ Document your proxy and trust store configurations for operational visibility
+ Follow your organization's security practices for credential management

These practices help maintain secure and reliable operations for your SiteWise Edge gateways while remaining aligned with your broader security policies.

# Configure proxy settings during AWS IoT SiteWise Edge gateway installation
<a name="manage-trust-stores-proxy_config"></a>

You can configure AWS IoT SiteWise Edge to work with a proxy server during gateway installation. The installation script supports both HTTP and HTTPS proxies and can automatically configure trust stores for secure proxy connections.

When you run the installation script with proxy settings, it performs several important tasks:
+ Validates the proxy URL format and parameters to ensure they are correctly specified.
+ Downloads and installs required dependencies through the configured proxy.
+ If a proxy CA certificate is provided, it's appended to the AWS IoT Greengrass root CA certificate and imported into the Java KeyStore.
+ Configures AWS IoT Greengrass (which SiteWise Edge uses) to use the proxy for all outbound connections.
+ Completes the SiteWise Edge installation with the appropriate proxy and trust store configurations.

**To configure proxy settings when installing gateway software**

1. Create a SiteWise Edge gateway. For more information, see [Create a self-hosted SiteWise Edge gateway](create-gateway-ggv2.md) and [Install the AWS IoT SiteWise Edge gateway software on your local device](install-gateway-software-on-local-device.md).

1. Run the installation script with the appropriate proxy settings for your environment. Replace the placeholders with your specific proxy information 

   Replace each of the following items:
   + `-p`, `--proxy-url` – The URL of the proxy server. The URL must be either `http` or `https`.
   + `-n`, `--no-proxy` – A comma-separated list of addresses to bypass the proxy.
   + (Optional)`-c`, `--proxy-ca-cert` – Path to the proxy CA certificate file.
   + (Optional)`-j`, `--javastorepass` – The Java KeyStore password. The default password is `changeit`.

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

   For Linux systems, use the following command structure:

   ```
   sudo ./install.sh -p proxy-url -n no-proxy-addresses [-c proxy-ca-cert-path] [-j javastorepass]
   ```

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

   For Microsoft Windows systems using PowerShell, use this command structure:

   ```
   .\install.ps1 -ProxyUrl proxy-url -NoProxyAddresses no-proxy-addresses [-ProxyCaCertPath proxy-ca-cert-path] [-JavaStorePass javastorepass]
   ```

------

## Troubleshooting during proxy-enabled installation
<a name="manage-trust-stores-proxy_installation-process_troubleshooting"></a>

For more information on resolving trust store issues related to a SiteWise Edge gateway, see [Proxy-enabled installation issues](troubleshooting-gateway.md#troubleshoot-proxy-during-installation).

# Manually configure trust stores for HTTPS proxy support in AWS IoT SiteWise Edge
<a name="manage-trust-stores-proxy_trust-store-locations-and-configuration"></a>

When configuring AWS IoT SiteWise Edge components to connect through an HTTPS proxy, add the proxy server's certificate to the appropriate trust stores. SiteWise Edge uses multiple trust stores to secure communications. There are three trust stores and your use of them depends upon the SiteWise Edge component type in your gateway implementation.

Trust stores are automatically updated during the installation process when proxy settings are provided.
+ [Configure an AWS IoT Greengrass Core component trust store](#manage-trust-stores-proxy_greengrass-core-components) – The AWS IoT Greengrass root CA certificate is included in the trust stores to verify the authenticity of AWS services.

  This trust store helps AWS IoT Greengrass components securely communicate with AWS services through the proxy while verifying the authenticity of those services.
+ [Configure a Java-based component trust store](#manage-trust-stores-proxy_java-based-components) – The Java KeyStore (JKS) is the main trust store used by Java-based components for SSL/TLS connections. 

   Java applications rely on the JKS to establish secure connections. For example, if you're using the IoT SiteWise publisher or IoT SiteWise OPC UA collector, which are Java-based, you'll need to configure this trust store. This ensures these components can securely communicate through the HTTPS proxy when sending data to the cloud or collecting data from OPC UA servers.
+ [System-level component trust store configuration](#manage-trust-stores-proxy_system-level-components) – When using HTTPS proxies, their certificates must be added to the appropriate trust stores to enable secure connections.

  When using HTTPS proxies, their certificates must be added to the appropriate trust stores to enable secure connections. This is necessary because system-level components, often written in languages like Rust or Go, rely on the system's trust store rather than Java's JKS. For example, if you're using system utilities that need to communicate through the proxy (like for software updates or time synchronization), you'll need to configure the system-level trust store. This ensures these components and utilities can establish secure connections through the proxy.

## Configure an AWS IoT Greengrass Core component trust store
<a name="manage-trust-stores-proxy_greengrass-core-components"></a>

For AWS IoT Greengrass Core functions that use Amazon's root CA:

1. Locate the certificate file at `/greengrass/v2/AmazonRootCA1.pem`

1. Append the HTTPS proxy root certificate (self-signed) to this file.

```
-----BEGIN CERTIFICATE-----
MIIEFTCCAv2gAwIQWgIVAMHSAzWG/5YVRYtRQOxXUTEpHuEmApzGCSqGSIb3DQEK
\nCwUAhuL9MQswCQwJVUzEPMAVUzEYMBYGA1UECgwP1hem9uLmNvbSBJbmMuMRww
... content of proxy CA certificate ...
+vHIRlt0e5JAm5\noTIZGoFbK82A0/nO7f/t5PSIDAim9V3Gc3pSXxCCAQoFYnui
GaPUlGk1gCE84a0X\n7Rp/lND/PuMZ/s8YjlkY2NmYmNjMCAXDTE5MTEyN2cM216
gJMIADggEPADf2/m45hzEXAMPLE=
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
MIIDQTCCAimgF6AwIBAgITBmyfz/5mjAo54vB4ikPmljZKyjANJmApzyMZFo6qBg
ADA5MQswCQYDVQQGEwJVUzEPMA0tMVT8QtPHRh8jrdkGA1UEChMGDV3QQDExBBKW
... content of root CA certificate ...
o/ufQJQWUCyziar1hem9uMRkwFwYVPSHCb2XV4cdFyQzR1KldZwgJcIQ6XUDgHaa
5MsI+yMRQ+hDaXJiobldXgjUka642M4UwtBV8oK2xJNDd2ZhwLnoQdeXeGADKkpy
rqXRfKoQnoZsG4q5WTP46EXAMPLE
-----END CERTIFICATE-----
```

### Configure HTTPS proxy on an established gateway
<a name="manage-trust-stores-proxy_proxy-configuration"></a>

You can add proxy support to an established gateway by connecting to port 443 instead of port 8883. For more information on using a proxy server, see [Connect on port 443 or through a network proxy](https://docs.aws.amazon.com/greengrass/v2/developerguide/configure-greengrass-core-v2.html#configure-alpn-network-proxy) in the *AWS IoT Greengrass Version 2 Developer Guide*. If you create a new gateway, you can set the proxy configuration during gateway installation. For more information, see [Configure proxy settings during AWS IoT SiteWise Edge gateway installation](manage-trust-stores-proxy_config.md).

When you use an HTTPS proxy with AWS IoT Greengrass on SiteWise Edge, the software automatically chooses between HTTP and HTTPS for proxy connections based on the provided URL.

**Important**  
Update all required trust stores before attempting to connect through an HTTPS proxy.

## Configure a Java-based component trust store
<a name="manage-trust-stores-proxy_java-based-components"></a>

For IoT SiteWise publisher, IoT SiteWise OPC UA collector, and Java services in the data processing pack, the default Java trust store location is `$JAVA_HOME/jre/lib/security/cacerts`

**To add a certificate**

1. Create a file to store the proxy server's certificate, such as `proxy.crt`.
**Note**  
Create the file ahead of time using the proxy server's certificate.

1. Add the file to Java's trust store using the following command:

   ```
   sudo keytool -import -alias proxyCert -keystore /usr/lib/jvm/java-11-openjdk-amd64/lib/security/cacerts -file proxy.crt
   ```

1. When prompted, use the default password: `changeit`

## System-level component trust store configuration
<a name="manage-trust-stores-proxy_system-level-components"></a>

For components written in Rust, Go, and other languages that use the system trust store:

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

Linux systems: Add certificates to `/etc/ssl/certs/ca-certificates.crt`

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

Microsoft Windows systems: To configure the trust store, follow the [Certificate Store](https://learn.microsoft.com/en-us/windows-hardware/drivers/install/certificate-stores) procedure in the *Microsoft Ignite* documentation.

Windows offers multiple certificate stores, including separate stores for User and Computer scopes, each with several sub-stores. For most SiteWise Edge setups, we recommend adding certificates to the `COMPUTER | Trusted Root Certification Authorities` store. However, depending on your specific configuration and security requirements, you might need to use a different store.

------

## Troubleshooting trust store issues
<a name="manage-trust-stores-proxy_trust-stores-troubleshooting"></a>

For more information on resolving trust store issues related to a SiteWise Edge gateway, see [Trust store issues](troubleshooting-gateway.md#troubleshoot-trust-stores).