Establishing encryption in transit for zonal file shares

You can establish an encrypted mount connection between the virtual server instance and a zonal file share by using the Internet Security Protocol (IPsec) security profile and X.509 certificate. By enabling encryption in transit, you create secure end-to-end encryption for your data.

IPsec is a group of protocols that together set up encrypted connections between devices. It helps keep data sent over public networks secure. IPsec Encrypts IP packets, and authenticates the source where the packets come from. To configure IPsec on your virtual server instance, you can use strongSwan, which is an open source IPsec-based VPN solution. For more information about how strongSwan works, see Introduction to strongSwan and IPsec Protocol, too.

The IPsec connection requires that you have an X.509 certificate for authentication. X.509 is an international standard format for public key certificates, digital documents that securely associate cryptographic key pairs with identities such as websites, individuals, or organizations. The metadata service is used to create the certificates.

A Certificate Signing Request (CSR) is a block of encoded texts that are forwarded to a certificate authority (CA) when users apply for a certificate. CSR is created on the server where the certificate is to be installed. CSR includes information such as domain name, organization name, locality, and country. The request also contains the public key, which is associated with the certificate that is generated, and the private key. The CA uses only the public key when the certificate is created. The private key must be saved and kept secret. As the private key is part of the key pair with the public key, and the certificate does not work if the private key is lost.

Encryption in transit is not supported on Bare Metal Servers for VPC.

Before you begin configuring encryption in transit with IPsec

To use the feature, the following requirements need to be met:

The file share must be based on the dp2 profile and be configured with Security Group access mode.
The mount target must be created with a virtual network interface. The virtual server instance and the mount target must be members of the same security group. For more information, see Creating file shares and mount targets.
Data encryption in transit must be enabled. In the console, you can toggle encryption in transit on when you create the mount target. The API transit_encryption property accepts the ipsec value to enable the feature.
The metadata service must be enabled on the compute host. For more information, see Metadata service on virtual server instances.

The IBM Cloud® file service provides a Mount Helper utility to automate the following tasks that are performed on the compute host.

If you want to connect a file share to instances that are running in different VPCs in a zone, you can create multiple mount targets. You can create one mount target for each VPC.

Obtaining the instance identity certificate

Obtain the X.509 certificates that are needed for authentication. The same certificates cannot be used across multiple regions.

The following command generates a Certificate Signing Request (CSR) and RSA Key Pair by using openssl.
```
openssl req -sha256 -newkey rsa:4096 -subj '/C=US' -out ./sslcert.csr -keyout file.key -nodes
```
When you run the command, replace the country code US with your two-digit country code in '/C=US'.

OpenSSL is an open source command-line toolkit that you can use to work with X.509 certificates, certificate signing requests (CSRs), and cryptographic keys. For more information, see OpenSSL Documentation.

If you're using a different software to create the CSR, you might be prompted to enter information about your location. Your location information can include country code (C), state (ST), locality (L), your organization name (O), and organization unit (OU). Any one of these naming attributes can be used. Any other naming attributes, such as common name, are rejected. CSRs with Common Name specified are rejected because when you make the request, the system automatically applies instance ID values to the subject Common Name for the instance identity certificates. CSRs with extensions are also rejected.
Format the csr before you make an API call to the metadata service by using the following command.
```
awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' sslcert.csr
```
Then, use the metadata service on the virtual server instance to create a client certificate.
1. Make a PUT /instance_identity/v1/token (virtual server instance) or PUT /identity/v1/tokens (bare metal server) request to get a token from the VPC identity service to be used for subsequent calls. For more information, see the following topic:
  - Acquiring an instance identity access token.
2. Use the identity token to create an identity certificate. Make a POST /instance_identity/v1/certificates request for a virtual server instance or a POST /identity/v1/certificates for a bare metal server. Specify the identity token in the HTTP Authorization header, plus a Certificate Signing Request (as csr property) and a validity duration (as expires_in property). The call returns a new client certificate and intermediate certificate chain that allows the client to access file shares by using IPsec Encryption in Transit. For more information, see the following topic:
  - Generating an instance identity certificate by using an instance identity access token.
3. Copy the API response output, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines, and save it to a file with a recognizable name, such as ca-cert.pem. Make sure that the file you create has the .pem extension.
Copy the instance identity certificate in the /etc/ipsec.d/cacerts directory.
```
sudo cp /tmp/ca-cert.pem /etc/ipsec.d/cacerts
```

Configuring the host and mounting the share

Install and configure the strongSwan client. You must configure IPsec Transport Mode for the mount target address.
Make sure that you install the required plug-ins (libcharon-extra-plugins) for authentication, and update the configuration files with the location of the instance identity certificate.
Establish a secure connection by starting the strongSwan client.
Mount your file share.