Certificate

APISIX supports to load multiple SSL certificates by TLS extension Server Name Indication (SNI).

Single SNI

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. #!/usr/bin/env python
  2. # coding: utf-8
  3. # save this file as ssl.py
  4. import sys
  5. # sudo pip install requests
  6. import requests
  8. if len(sys.argv) <= 3:
  9.     print("bad argument")
  10.     sys.exit(1)
  11. with open(sys.argv[1]) as f:
  12.     cert = f.read()
  13. with open(sys.argv[2]) as f:
  14.     key = f.read()
  15. sni = sys.argv[3]
  16. api_key = "edd1c9f034335f136f87ad84b625c8f1"
  17. resp = requests.put("http://127.0.0.1:9080/apisix/admin/ssl/1", json={
  18.     "cert": cert,
  19.     "key": key,
  20.     "snis": [sni],
  21. }, headers={
  22.     "X-API-KEY": api_key,
  23. })
  24. print(resp.status_code)
  25. print(resp.text)
  1. # create SSL object
  2. ./ssl.py t.crt t.key test.com
  4. # create Router object
  5. curl http://127.0.0.1:9080/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: */*

wildcard SNI

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

multiple domain

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:

  1. {
  2.     "snis": ["www.test.com", "mail.test.com"]
  3. }

multiple certificates for a single domain

If you want to configure multiple certificate for a single domain, for instance, supporting both the ECC and RSA key-exchange algorithm, then just configure the extra certificates (the first certificate and private key should be still put in cert and key) and private keys by certs and keys.

  • 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.