# Setup In-Service TLS

In-service TLS configuration is only required if you do not have a load balancer or proxy handling
TLS "in front" of the `embedded` service. Or, if you'd like to have TLS communication between your
load balancer and the service.

The embedded service supports TLS to secure connections over HTTPS. Configuration requires a
PEM-encoded X.509 certificate and corresponding private key.

## Generating Certificates

For production deployments, use a certificate issued by a trusted Certificate Authority along with
your corresponding private key.

For testing or proof-of-concept deployments, you can generate a self-signed certificate with
OpenSSL:


```bash
openssl ecparam -genkey -name secp384r1 -out tls.key
openssl req -new -x509 -sha256 -key tls.key -out tls.crt -days 365
```

This creates an ECDSA key pair using the secp384r1 curve and a self-signed certificate valid for one
year. When prompted, enter appropriate values for the certificate subject fields.

## Configuring the Embedded Service

Enable TLS by providing both the certificate and key files when starting the embedded service:


```bash
./embedded \
  --tls-crt=/path/to/tls.crt \
  --tls-key=/path/to/tls.key \
  [other flags...]
```

Both flags must be specified together. If only one is provided, the service will exit with an error.
When TLS is enabled, the service enforces a minimum of TLS 1.2 for all connections.

## Verifying TLS

After starting the service with TLS enabled, verify the configuration by making an HTTPS request:


```bash
curl -v https://localhost:8000/v1/health
```

If using a self-signed certificate, you may need to add the `-k` flag to skip certificate
verification.

A successful connection will show the TLS handshake details in the verbose output, including the
certificate subject and issuer.

## Troubleshooting

### "must specify both tls-crt and tls-key"

This error occurs when only one of the two TLS flags is provided. Both `--tls-crt` and `--tls-key`
are required to enable TLS.

### "certificate file not found" or "key file not found"

The service validates that both files exist before starting. Verify the paths are correct and the
files are readable by the process. Use absolute paths to avoid working directory issues.

### Certificate errors in clients

If clients report certificate validation errors, ensure the certificate matches the hostname being
accessed. For production certificates, ensure the full certificate chain is included in the
certificate file.