Skip to main content
Version: 1.x

CA Certificates

wasmCloud​

wasmCloud can be configured to trust additional certificates when establishing secure connections for OCI and OTEL. This is useful when working with private certificates, such as those used in private networks or with self-signed certificates.

shell
./wasmcloud --tls-ca-path /path/to/cert.pem --tls-ca-path /path/to/another-cert.pem ...

Passing CAs to the wasmCloud host on Kubernetes​

When using the wasmCloud operator on Kubernetes, you can pass one or more Certificate Authorities (CAs) into wasmCloud via ConfigMaps and Secrets.

CAs can be defined as in the examples below:

yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: org-authorities
data:
  dontmountme: |
    -----BEGIN CERTIFICATE-----
    Custom CA certificate bundle.
    -----END CERTIFICATE-----
  root.crt: |
    -----BEGIN CERTIFICATE-----
    Custom CA certificate bundle.
    -----END CERTIFICATE-----

---
apiVersion: v1
kind: Secret
metadata:
  name: email-authorities
stringData:
  email.crt: |
    -----BEGIN CERTIFICATE-----
    Custom CA certificate bundle.
    -----END CERTIFICATE-----
  notifications.crt: |
    -----BEGIN CERTIFICATE-----
    Custom CA certificate bundle.
    -----END CERTIFICATE-----

The CAs are then passed as part of a wasmCloud host definition:

yaml
apiVersion: k8s.wasmcloud.dev/v1alpha1
kind: WasmCloudHostConfig
metadata:
  name: wasmcloud-host
spec:
  lattice: default
  version: "1.0.4"
  natsAddress: nats://nats-cluster.default.svc.cluster.local
  certificates:
    authorities:
      - name: org-wide-authorities
         configmap:
           name: org-authorities
      - name: partner-authorities
         secret:
           secretName: email-authorities

The authorities list follows the Volume convention.

The wasmCloud operator mounts the org-authorities ConfigMap into the wasmCloud host container under /wasmcloud/certificates/ca-org-wide-authorities. Note that the authority name is prefixed with ca-.

The operator scans the ConfigMap for items that end in .crt (i.e., certificates) and appends them to the arguments passed to wasmCloud host. For example, if the ConfigMap includes the keys dontmountme and root.crt, only root.crt will be passed into wasmCloud as --tls-ca-path /wasmcloud/certificates/ca-org-wide-authorities/root.crt.

The operator uses the same process when passing CAs defined as Secrets.

Configuration via hostConfig​

When deploying wasmCloud on Kubernetes with the wasmcloud-platform Helm chart, you can configure wasmCloud hosts to use additional CAs in the chart's values.yaml file under hostConfig:

yaml
hostConfig:
  enabled: true
  # Other configuration...
  certificates:
    authorities:
      - name: intermediate-ca
        configMap:
          name: private-intermediate-ca
      - name: private-root-ca
        secret:
          secretName: private-root-ca

Troubleshooting​

When deploying components from your OCI registry that uses private or self-signed SSL certificates, wasmCloud may return errors like the following:

shell
failed to fetch provider: failed to fetch provider under OCI reference `<OCI_REFERENCE>`: failed to fetch OCI path: failed to fetch OCI bytes: error sending request for url (URL): client error (Connect): invalid peer certificate: UnknownIssuer

To print and diagnose the signing of the certificate, run:

shell
# Edit URL to point to your registry
export OCI_REGISTRY_URL=ghcr.io
echo | openssl s_client -showcerts -servername $OCI_REGISTRY_URL -connect $OCI_REGISTRY_URL:443 2>/dev/null | openssl x509 -inform pem -noout -text

Application HTTP Client Requests​

If applications deployed on wasmCloud use the HTTP client capability provider and make outbound requests to services that use private certificates, the application must be configured to trust the private certificates. This can be done by providing the HTTP client with the custom certificates.

The HTTP client capability provider README details these options in more detail, at a high level:

HTTP Client Configuration​

KeyValueDescriptionDefault
load_native_certs"true" / "false"Use the platform's native certificate store at runtime. Any value other than "true" will be assumed as "false""true"
load_webpki_certs"true" / "false"Uses a compiled-in set of root certificates trusted by Mozilla. Any value other than "true" will be assumed as "false""true"
ssl_certs_file"/path/to/certs.pem"Path to a file available on the machine where the HTTP client runs that contains one or more root certificates to trust. The provider will fail to instantiate if the file is not present.N/A

An example of starting this provider with all of the configuration values looks like this in wash:

bash
wash config put http-client-config load_native_certs=true load_webpki_certs=true ssl_certs_file=/tmp/certs.pem
wash start provider ghcr.io/wasmcloud/http-client:0.11.0 http-client --config http-client-config

An example of starting this provider with all of the configuration values looks like this in wadm:

yaml
- name: httpclient
  type: capability
  properties:
    image: ghcr.io/wasmcloud/http-client:0.11.0
    config:
      - name: http-client-config
        properties:
          load_native_certs: 'true'
          load_webpki_certs: 'true'
          ssl_certs_file: /tmp/certs.pem