Certificate

    It is most common for an SSL certificate to contain only one domain. We can create an ssl object. Here is a simple case, creates a ssl object and route object.

    • cert: PEM-encoded public certificate of the SSL key pair.
    • key: PEM-encoded private key of the SSL key pair.
    • snis: Hostname(s) to associate with this certificate as SNIs. To set this attribute this certificate must have a valid private key associated with it.

    We will use the Python script below to simplify the example:

    1. # create SSL object
    2. ./ssl.py t.crt t.key test.com
    4. # create Router object
    5. curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
    6. {
    7.     "uri": "/hello",
    8.     "hosts": ["test.com"],
    9.     "methods": ["GET"],
    10.     "upstream": {
    11.         "type": "roundrobin",
    12.         "nodes": {
    13.             "127.0.0.1:1980": 1
    14.         }
    15.     }
    16. }'
    18. # make a test
    20. curl --resolve 'test.com:9443:127.0.0.1' https://test.com:9443/hello  -vvv
    21. * Added test.com:9443:127.0.0.1 to DNS cache
    22. * About to connect() to test.com port 9443 (#0)
    23. *   Trying 127.0.0.1...
    24. * Connected to test.com (127.0.0.1) port 9443 (#0)
    25. * Initializing NSS with certpath: sql:/etc/pki/nssdb
    26. * skipping SSL peer certificate verification
    27. * SSL connection using TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
    28. * Server certificate:
    29. *   subject: CN=test.com,O=iresty,L=ZhuHai,ST=GuangDong,C=CN
    30. *   start date: Jun 24 22:18:05 2019 GMT
    31. *   expire date: May 31 22:18:05 2119 GMT
    32. *   common name: test.com
    33. *   issuer: CN=test.com,O=iresty,L=ZhuHai,ST=GuangDong,C=CN
    34. > GET /hello HTTP/1.1
    35. > User-Agent: curl/7.29.0
    36. > Host: test.com:9443
    37. > Accept: */*

    Sometimes, one SSL certificate may contain a wildcard domain like *.test.com, that means it can accept more than one domain, eg: www.test.com or mail.test.com.

    Here is an example, note that the value we pass as sni is *.test.com.

    1. ./ssl.py t.crt t.key '*.test.com'
    3. curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
    4. {
    5.     "hosts": ["*.test.com"],
    6.     "methods": ["GET"],
    7.     "upstream": {
    8.         "type": "roundrobin",
    9.         "nodes": {
    10.             "127.0.0.1:1980": 1
    11.         }
    12.     }
    13. }'
    15. # make a test
    17. curl --resolve 'www.test.com:9443:127.0.0.1' https://www.test.com:9443/hello  -vvv
    18. * Added test.com:9443:127.0.0.1 to DNS cache
    19. * About to connect() to test.com port 9443 (#0)
    20. *   Trying 127.0.0.1...
    21. * Connected to test.com (127.0.0.1) port 9443 (#0)
    22. * Initializing NSS with certpath: sql:/etc/pki/nssdb
    23. * skipping SSL peer certificate verification
    24. * SSL connection using TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
    25. * Server certificate:
    26. *   subject: CN=test.com,O=iresty,L=ZhuHai,ST=GuangDong,C=CN
    27. *   start date: Jun 24 22:18:05 2019 GMT
    28. *   expire date: May 31 22:18:05 2119 GMT
    29. *   common name: test.com
    30. *   issuer: CN=test.com,O=iresty,L=ZhuHai,ST=GuangDong,C=CN
    31. > GET /hello HTTP/1.1
    32. > User-Agent: curl/7.29.0
    33. > Host: test.com:9443
    34. > Accept: */*

    If your SSL certificate may contain more than one domain, like www.test.com and mail.test.com, then you can add them into the snis array. For example:

    • certs: PEM-encoded certificate array.
    • keys: PEM-encoded private key array.

    APISIX will pair certificate and private key with the same indice as a SSL key pair. So the length of certs and keys must be same.

    APISIX currently uses CA certificates in several places, such as , etcd with mTLS, and .

    In these places, ssl_trusted_certificate or trusted_ca_cert will be used to set up the CA certificate, but these configurations will eventually be translated into lua_ssl_trusted_certificate directive in OpenResty.

    If you need to set up different CA certificates in different places, then you can package these CA certificates into a CA bundle file and point to this file when you need to set up CAs. This will avoid the problem that the generated lua_ssl_trusted_certificate has multiple locations and overwrites each other.

    The following is a complete example to show how to set up multiple CA certificates in APISIX.

    The following table details the configurations involved in this example and what they do:

    1. Create CA bundle files
    1. cat /path/to/foo_ca.crt /path/to/bar_ca.crt > apisix.ca-bundle
    1. Start the ETCD cluster and enable client authentication

    Start by writing a goreman configuration named Procfile-single-enable-mtls, the content as:

    1. # Use goreman to run `go get github.com/mattn/goreman`
    2. etcd1: etcd --name infra1 --listen-client-urls https://127.0.0.1:12379 --advertise-client-urls https://127.0.0.1:12379 --listen-peer-urls http://127.0.0.1:12380 --initial-advertise-peer-urls http://127.0.0.1:12380 --initial-cluster-token etcd-cluster-1 --initial-cluster 'infra1=http://127.0.0.1:12380,infra2=http://127.0.0.1:22380,infra3=http://127.0.0.1:32380' --initial-cluster-state new --cert-file /path/to/bar_etcd.crt --key-file /path/to/bar_etcd.key --client-cert-auth --trusted-ca-file /path/to/apisix.ca-bundle
    3. etcd2: etcd --name infra2 --listen-client-urls https://127.0.0.1:22379 --advertise-client-urls https://127.0.0.1:22379 --listen-peer-urls http://127.0.0.1:22380 --initial-advertise-peer-urls http://127.0.0.1:22380 --initial-cluster-token etcd-cluster-1 --initial-cluster 'infra1=http://127.0.0.1:12380,infra2=http://127.0.0.1:22380,infra3=http://127.0.0.1:32380' --initial-cluster-state new --cert-file /path/to/bar_etcd.crt --key-file /path/to/bar_etcd.key --client-cert-auth --trusted-ca-file /path/to/apisix.ca-bundle

    Use goreman to start the ETCD cluster:

    1. Update config.yaml
    1. deployment:
    2.   admin:
    3.     admin_key
    4.       - name: admin
    5.         key: edd1c9f034335f136f87ad84b625c8f1
    6.         role: admin
    7.     admin_listen:
    8.       ip: 127.0.0.1
    9.       port: 9180
    10.     admin_api_mtls:
    11.       admin_ssl_ca_cert: /path/to/apisix.ca-bundle
    12.       admin_ssl_cert: /path/to/foo_server.crt
    13.       admin_ssl_cert_key: /path/to/foo_server.key
    15. apisix:
    16.   ssl:
    17.     ssl_trusted_certificate: /path/to/apisix.ca-bundle
    19. deployment:
    20.   role: traditional
    21.   role_traditional:
    22.     config_provider: etcd
    23.   etcd:
    24.     host:
    25.       - "https://127.0.0.1:12379"
    26.       - "https://127.0.0.1:22379"
    27.       - "https://127.0.0.1:32379"
    28.     tls:
    29.       cert: /path/to/bar_apisix.crt
    30.       key: /path/to/bar_apisix.key
    31.       sni: etcd.cluster.dev
    1. Test APISIX Admin API

    Start APISIX, if APISIX starts successfully and there is no abnormal output in logs/error.log, it means that mTLS communication between APISIX and ETCD is normal.

    Use curl to simulate a client, communicate with APISIX Admin API with mTLS, and create a route:

    1. curl -vvv \
    2.     --resolve 'admin.apisix.dev:9180:127.0.0.1' https://admin.apisix.dev:9180/apisix/admin/routes/1 \
    3.     --cert /path/to/foo_client.crt \
    4.     --key /path/to/foo_client.key \
    5.     --cacert /path/to/apisix.ca-bundle \
    6.     -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
    7. {
    8.     "uri": "/get",
    9.     "upstream": {
    10.         "type": "roundrobin",
    11.         "nodes": {
    12.             "httpbin.org:80": 1
    13.         }
    14.     }
    15. }'
    1. Verify APISIX proxy
    1. curl http://127.0.0.1:9080/get -i
    3. HTTP/1.1 200 OK
    4. Content-Type: application/json
    5. Content-Length: 298
    6. Connection: keep-alive
    7. Date: Tue, 26 Jul 2022 16:31:00 GMT
    8. Access-Control-Allow-Origin: *
    9. Access-Control-Allow-Credentials: true
    10. Server: APISIX/2.14.1
    11. ...

    APISIX proxied the request to the /get path of the upstream httpbin.org and returned . The whole process is working fine using CA bundle instead of CA certificate.