TLS Encryption

This section contains declarations use SSL/TLS certificates and keys.

Use the index under Current Page on the left to locate specific examples.

1: Referencing an existing SSL certificate and key in the Common partition

This example shows how to reference an SSL certificate and key that exist in the Common partition. For more information, see our video on referencing existing objects, including SSL certificates and keys, at https://www.youtube.com/watch?v=b55noytozMU.

This declaration creates the following objects on the BIG-IP:

  • Partition (tenant) named Sample_cert_01.
  • A virtual server named serviceMain.
  • A pool named pool monitored by the default http health monitor.
  • TLS/SSL profile (which references the default BIG-IP certificate and key in the Common partition) named pTlsServer_Local. In the BIG-IP UI, this is called a Client SSL profile.
{
    "class": "ADC",
    "id": "myid",
    "schemaVersion": "3.0.0",
    "controls": {
      "class": "Controls",
      "trace": true,
      "logLevel": "debug"
    },
    "Sample_cert_01": {
      "class": "Tenant",
      "test_https": {
        "class": "Application",
        "template": "https",
        "pool": {
          "class": "Pool",
          "members": [
            {
              "serverAddresses": [
                "192.0.2.100"
              ],
              "servicePort": 8080
            }
          ],
          "monitors": [
            "http"
          ]
        },
        "serviceMain": {
          "class": "Service_HTTPS",
          "persistenceMethods": [],
          "pool": "pool",
          "serverTLS": "pTlsServer_Local",
          "snat": "auto",
          "virtualAddresses": [
            "192.168.0.2"
          ],
          "virtualPort": 443
        },
        "pTlsServer_Local": {
          "class": "TLS_Server",
          "label": "simplest decl requires just cert",
          "certificates": [
            {
              "certificate": "tlsserver_local_cert"
            }
          ]
        },
        "tlsserver_local_cert": {
          "class": "Certificate",
          "certificate": {"bigip":"/Common/default.crt"},
          "privateKey": {"bigip":"/Common/default.key"}
        }
      }
    }
  }
  

Back to top

2: Using multiple SSL/TLS certificates in a single profile

This simple example shows how you can use multiple SSL/TLS certificates in a single TLS_Server object in AS3 3.7.0 and later. See the Schema Reference for usage options for using these features in your AS3 declarations.

Note: This example does not include real certificates, so if you post the following declaration, you will receive an invalid certificate error. Replace the values of certificate and privateKey with your own certificates.

This declaration creates the following objects on the BIG-IP:

  • A partition (tenant) named Sample_cert_02.
  • A certificate named webtls.
  • A TLS_Server object (SSL profile on the BIG-IP) containing two certificates and keys (webcert1 and webcert2)
{
    "class": "AS3",
    "action": "deploy",
    "persist": true,
    "declaration": {
        "class": "ADC",
        "schemaVersion": "3.0.0",
        "id": "123abc",
        "label": "Multiple certificates example",
        "remark": "Using multiple certificates",
        "Sample_cert_02": {
            "class": "Tenant",
            "A1": {
                "class": "Application",
                "template": "https",
                "serviceMain": {
                    "class": "Service_HTTPS",
                    "virtualAddresses": [
                        "192.0.2.19"
                    ],
                    "serverTLS": "webtls"
                },
                "webtls": {
                    "class": "TLS_Server",
                    "certificates": [{
                        "certificate": "webcert1"
                    },
                    {
                        "certificate": "webcert2"
                    }]
                },
                "webcert1": {
                    "class": "Certificate",
                    "remark": "replace these with real certificates and keys",
                    "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
                    "privateKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
                },
                "webcert2": {
                    "class": "Certificate",
                    "remark": "replace these with real certificates and keys",
                    "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
                    "privateKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
                }
            }
        }
    }
}

Back to top

3: Using matchToSNI with a TLS_Server profile

In this declaration, we add the matchToSNI parameter. When you use matchToSNI with a value of an FQDN, the system ignores all names in the certificate and selects this cert when SNI matches value (or by default).

Note: This example does not include real certificates (it’s the same declaration as #2 with the matchToSNI parameter), so if you post the following declaration, you will receive an invalid certificate error. Replace the values of certificate and privateKey with your own certificates.

This declaration creates the following objects on the BIG-IP:

  • A partition (tenant) named Sample_cert_03.
  • A certificate named webtls.
  • A TLS_Server object (SSL profile on the BIG-IP) containing two certificates and keys (webcert1 and webcert2), the first of which uses matchToSNI.
{
    "class": "AS3",
    "action": "deploy",
    "persist": true,
    "declaration": {
       "class": "ADC",
       "schemaVersion": "3.0.0",
       "id": "123abc",
       "label": "test",
       "remark": "test",
     "Sample_cert_03": {
       "class": "Tenant",
       "A1": {
           "class": "Application",
           "template": "https",
         "serviceMain": {
             "class": "Service_HTTPS",
             "virtualAddresses": [
               "192.02.2.19"
             ],
             "serverTLS": "webtls"
         },
           "webtls": {
               "class": "TLS_Server",
               "certificates": [{
                   "matchToSNI": "wwww.domain.com",
                   "certificate": "webcert1"
               },
               {
                   "certificate": "webcert2"
               }]
           },
           "webcert1": {
               "class": "Certificate",
               "remark": "test",
               "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
               "privateKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
           },
           "webcert2": {
               "class": "Certificate",
               "remark": "test",
               "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
               "privateKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
           }
       }
     }
 }
}

Back to top

4: Using PKCS 12 in a declaration

This example shows how you can use PKCS 12 in your declarations. See the Schema Reference for usage options for using these features in your AS3 declarations.

Important notes about AS3 and PKCS

  • There are two passphrases used for p12/pfx: file protection (import/export integrity) and private key passphrase (encryption). AS3 only supports using the same passphrase for both. The BIG-IP Configuration Utility (GUI) supports using different password values. However, openSSL CLI notes that most software only handles the scenario where both passphrases have the same value. For more information, see -twopass arg for openssl.

  • If you use the OpenSSL CLI to generate the PKCS12 file, and at the passphrase prompt you don’t type a passphrase and just press Enter, the system actually creates an empty file (so pressing Enter does not mean there is no password). To account for this in a declaration, you must add the following to your declaration:

    "passphrase": {
        "ciphertext": "IA==",
        "protected": "eyJhbGciOiJkaXIiLCJlbmMiOiJub25lIn0",
        "ignoreChanges": true
    },
    
  • If you do not expect the PKCS12 value to change on subsequent deployments of the declaration, set the following property to true: pkcs12Options: { ignoreChanges: true }. If you leave this property set to the default of false (or omit this property), a diff is detected because of the nature of the encrypted value of the private key.

  • For the property keyImportFormat (pkcs12Options: { keyImportFormat: "<pkcs8 or openssl-legacy>" }, the default value is pkcs8, which saves the private key in PEM format:
    (---BEGIN ENCRYPTED PRIVATE KEY---).
    If it is set to openssl-legacy, it is saved with headers:

    -----BEGIN RSA PRIVATE KEY-----
    Proc-Type: 4,ENCRYPTED
    DEK-Info: AES-128-CBC,D019D34F0792CEAB8CD895E6F29437D6
    

This declaration creates the following objects on the BIG-IP:

  • A partition (tenant) named Sample_cert_04.
  • A certificate named pkcs_crt.crt.
  • In this example, my_12.p12 contains one cert, so the following objects are created: a certificate named pkcs12_crt_key_encr_url.crt and an encrypted private key named pkcs12_crt_key_encr_url.key, with key password value of “password”.
  • In this example, my_pfx.pfx contains multiple certs, so the following object is created: a cert bundle named pkcs12_crt_key_encr_bundle_url containing multiple certs
{
    "class": "ADC",
    "schemaVersion": "3.7.0",
    "id": "TEST_PKCS12",
    "remark": "Test PKCS12",
    "example_cert_04": {
      "class": "Tenant",
      "TEST_Certificate": {
        "class": "Application",
        "template": "generic",
        "pkcs12_crt": {
            "class": "Certificate",
            "remark": "generated with openssl cli - empty password on prompt",
            "passphrase": {
            "ciphertext": "IA==",
            "protected": "eyJhbGciOiJkaXIiLCJlbmMiOiJub25lIn0",
            "ignoreChanges": true
          },
            "pkcs12": {
                "base64": "MIIEdAIBAzCCBDoGCSqGSIb3DQEHAaCCBCsEggQnMIIEIzCCBB8GCSqGSIb3DQEHBqCCBBAwggQMAgEAMIIEBQYJKoZIhvcNAQcBMBwGCiqGSIb3DQEMAQYwDgQIMFpvfHSvJ6sCAggAgIID2PQxcEhhEPgU+sTVw9UncA+U0QYK2/JWQAzfxfD30uR9hXMdFnCF8wJcuUL+4jR+xnrJ9i+F5mISD8zLPipCLs3JuBDGQ8CibTMjcbm54eEzcX6knoQ8r6WZh8tXL+Dniwsnl7FrTwE6br+V/1LQvc03NepYA+xDPgHCOj1qfIcqMyylsf7ZyqYp76nmlv2tkcQrM/f+hcA9UtDuseeRae4ugx5IKkrcIAVYPMfCwRSPkGFWJJofHZaCzeCT4Nq5+ocljogAlqtWSH9nIGEsYxDCrhj3qgZNAPODa1vfnMna3/1md4oRuqI5qe7UQF6e/eltAunZDUtT1vTW+O3vyt3Bqfl18moXocUOuVVi7CNejcA0+IhqryrkI3w4aIXxWVmZ4tl/El/OSjXCRMs+tnTwRZjiCd1dPnKJHjesygupnS4rHus31dQKMmxjyKVrhsl3N+oopbGVWAlaR7p/0DyTdUywBrExyi/c7QvVN/0D08F1TRed4ys3/AVl43dvM9IFGm+ZwsvYyBhRmYn/oL5Dr5u5/jHFhPrWTR35sE5uvcYsJR96hmMqxN57K95MggRcthsrdIvDN+86pqifZoVPTmezFgRuO7NfzhCj/uOd1l61dOKbFNT5DuE5DoyJ8IaVnTJvZ4CAq3O2Ix62LVw0t/lM7AXhkak52LsyJ8VGcaK8R9PhM/X0CYGoRgWyPzJ3GGNX6s9Pw6rV6k5gtYkUagElrsJbcmfabEMZAGwIsVmOpaxdpyuaoo2TR+tz/E1FasC9K3aJ0cEwt6Cm9/tW4qEsb65TBm7C2kXNglUHEmrxndVfMVzKG2dkxUhvJdqw3BxcPukjzk4lpBv2YrTeJs4+y+aRn7F7GUrR4r9Z903ZTbu2DiOEbFEERPq/08zO7zl9pD76KyJfrWWlNW+urwPqEz8i6eDj+/zBlCd6JfXxVgXy8ctHwqKChBNDyimVBvXDD6zIySnazdYVcYycfnSbNo4p2VWztF4C6CvqqOtN39I11LZZ1okZsxpacQEU3nhaRXHw+bMrHfRZNlt5RmCIYnNuB6qTBjL9yaaq/9BNzW2dQnRP2OkeIbfVJN3N00Sey0sbsXUlajEMJW7Efsz6iHtOXZkeTdu8ME7eGBsaRNAX5tcDqMJjnxhGsZSmxLNHW+5OnmNB54sdEMhyM/wYEbxGh6qQEPtbdBhSZIuXiSkfmtI64IdKhBYpLl2rUxDB+nLZisRgea3xCBDxHVd7c0e9u67lT3GetAmFX2GOTA5+a8k3zXnj6te+gN+9ZJhVCOasifNzKpk7WLwZXAgnFWtuXjAxMCEwCQYFKw4DAhoFAAQUL+jxIL4tVgP9Hb2ux92Idbur6QEECEfy4yQcB7vhAgIIAA==" }
  
        },
        "pkcs12_crt_key_encr_url": {
          "class": "Certificate",
          "remark": "saves encr key in openssl format (with dek-info, proctype headers)",
          "passphrase": {
            "ciphertext": "cGFzc3dvcmQ=",
            "protected": "eyJhbGciOiJkaXIiLCJlbmMiOiJub25lIn0",
            "ignoreChanges": true
          },
          "pkcs12Options": {
              "keyImportFormat": "openssl-legacy"
          },
          "pkcs12": {
              "url": "https://mycompany/certs/my_p12.p12" }
  
        },
        "pkcs12_crt_key_bundle": { 
            "class": "Certificate",
            "remark": "multiple certs, no passphrase, ignore change on subsequent deploy",
            "pkcs12Options": {
              "keyImportFormat": "openssl-legacy",
              "ignoreChanges": true
            },
            "pkcs12": {
                "url": "http://mycompany/certs/my_pfx.pfx" }
  
        }
      }
    }
  }
  

Back to top

5: Enabling and disabling Server SSL from Endpoint policies

This simple example shows how you enable or disable a Server SSL profile from an Endpoint policy (LTM Policy to the BIG-IP) in your declaration. See the Schema Reference for usage options and information on Endpoint policies. You can also see Application Security for example policy declarations.

This declaration creates the following objects on the BIG-IP:

  • Partition (tenant) named Sample_cert_05.
  • An endpoint policy named testItem.
  • A rule named requestRule.
  • An action for server SSL with a value of true. You could use false to disable the Server SSL profile.
{
    "class": "ADC",
    "schemaVersion": "3.7.0",
    "id": "Endpoint_Policy",
    "Sample_cert_05": {
        "class": "Tenant",
        "Application": {
            "class": "Application",
            "template": "generic",
            "testItem": {
                "class": "Endpoint_Policy",
                "rules": [{
                    "name": "requestRule",
                    "actions": [{
                        "type": "serverSsl",
                        "enabled": true
                    }]
                }]
            }
        }
    }
}

Back to top

6: HTTP and HTTPS virtual services in one declaration

This example creates the following objects on the BIG-IP:

  • Partition (tenant) named Sample_http_04.
  • An HTTP virtual server named serviceMain (called _A1 in the BIG-IP GUI) and an HTTPS virtual server named A2.
  • A pool named gce_pool and a pool named web_pool, each containing two members using the HTTP health monitor.
  • TLS/SSL profile (including certificate and private key) named TLS_Server. In the BIG-IP UI, this is a Client SSL profile.

Note: This example does not include real certificates, so if you post the following declaration, you will receive an invalid certificate error. Replace the values of certificate and privateKey with your own certificates.

{
  "class": "AS3",
  "action": "deploy",
  "persist": true,
  "declaration": {
    "class": "ADC",
    "schemaVersion": "3.0.0",
    "id": "lmnop543421",
    "label": "Sample 4",
    "remark": "An HTTP and an HTTPS application",
    "controls": {
      "trace": true
    },
    "Sample_http_04": {
      "class": "Tenant",
      "A1": {
        "class": "Application",
        "template": "http",
        "serviceMain": {
          "class": "Service_HTTP",
          "virtualAddresses": [
            "10.0.9.10"
          ],
          "pool": "gce_pool"
        },
        "gce_pool": {
          "class": "Pool",
          "monitors": [
            "http"
          ],
          "members": [{
            "servicePort": 80,
            "serverAddresses": [
              "192.0.7.10",
              "192.0.7.11"
            ]
          }]
        }
      },
      "A2": {
        "class": "Application",
        "template": "https",
        "serviceMain": {
          "class": "Service_HTTPS",
          "virtualAddresses": [
            "10.0.9.20"
          ],
          "pool": "web_pool",
          "serverTLS": "webtls"
        },
        "web_pool": {
          "class": "Pool",
          "monitors": [
            "http"
          ],
          "members": [{
            "servicePort": 80,
            "serverAddresses": [
              "192.0.9.10",
              "192.0.9.11"
            ]
          }]
        },
        "webtls": {
          "class": "TLS_Server",
          "certificates": [{
            "certificate": "webcert"
          }]
        },
        "webcert": {
          "class": "Certificate",
          "remark": "in practice we recommend using a passphrase",
          "certificate": "-----BEGIN CERTIFICATE-----\nMIICnDCCAgWgAwIBAgIJAJ5n2b0OCEjwMA0GCSqGSIb3DQEBCwUAMGcxCzAJBgNVBAYTAlVTMRMwEQYDVQQIDApXYXNoaW5ndG9uMRAwDgYDVQQHDAdTZWF0dGxlMRQwEgYDVQQKDAtmNV9OZXR3b3JrczEbMBkGA1UEAwwSc2FtcGxlLmV4YW1wbGUubmV0MB4XDTE3MTEyNjE5NTAyNFoXDTE4MDIyNTE5NTAyNFowZzELMAkGA1UEBhMCVVMxEzARBgNVBAgMCldhc2hpbmd0b24xEDAOBgNVBAcMB1NlYXR0bGUxFDASBgNVBAoMC2Y1X05ldHdvcmtzMRswGQYDVQQDDBJzYW1wbGUuZXhhbXBsZS5uZXQwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBALEsuXmSXVQpYjrZPW+WiTBjn491mwZYT7Q92V1HlSBtM6WdWlK1aZN5sovfKtOX7Yrm8xa+e4o/zJ2QYLyyv5O+t2EGN/4qUEjEAPY9mwJdfzRQy6Hyzm84J0QkTuUJ/EjNuPji3D0QJRALUTzu1UqqDCEtiN9OGyXEkh7uvb7BAgMBAAGjUDBOMB0GA1UdDgQWBBSVHPNrGWrjWyZvckQxFYWO59FRFjAfBgNVHSMEGDAWgBSVHPNrGWrjWyZvckQxFYWO59FRFjAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBCwUAA4GBAJeJ9SEckEwPhkXOm+IuqfbUS/RcziifBCTmVyE+Fa/j9pKSYTgiEBNdbJeBEa+gPMlQtbV7Y2dy8TKx/8axVBHiXC5geDML7caxOrAyHYBpnx690xJTh5OIORBBM/a/NvaR+P3CoVebr/NPRh9oRNxnntnqvqD7SW0U3ZPe3tJc\n-----END CERTIFICATE-----",
          "privateKey": "-----BEGIN RSA PRIVATE KEY-----\nProc-Type: 4,ENCRYPTED\nDEK-Info: AES-256-CBC,D8FFCE6B255601587CB54EC29B737D31\n\nkv4Fc3Jn0Ujkj0yRjt+gQQfBLSNF2aRLUENXnlr7Xpzqu0Ahr3jS1bAAnd8IWnsR\nyILqVmKsYF2DoHh0tWiEAQ7/y/fe5DTFhK7N4Wml6kp2yVMkP6KC4ssyYPw27kjK\nDBwBZ5O8Ioej08A5sgsLCmglbmtSPHJUn14pQnMTmLOpEtOsu6S+2ibPgSNpdg0b\nCAJNG/KHe+Vkx59qNDyDeKb7FZOlsX30+y67zUq9GQqJEDuysPJ2BUNP0IJXAjst\nFIt1qNoZew+5KDYs7u/lPxcMGTirUhgI84Jy4WcDvSOsP/tKlxj04TbIE3epmSKy\n+TihHkwY7ngIGtcm3Sfqk5jz2RXoj1/Ac3SW8kVTYaOUogBhn7zAq4Wju6Et4hQG\nRGapsJp1aCeZ/a4RCDTxspcKoMaRa97/URQb0hBRGx3DGUhzpmX9zl7JI2Xa5D3R\nmdBXtjLKYJTdIMdd27prBEKhMUpae2rz5Mw4J907wZeBq/wu+zp8LAnecfTe2nGY\nE32x1U7gSEdYOGqnwxsOexb1jKgCa67Nw9TmcMPV8zmH7R9qdvgxAbAtwBl1F9OS\nfcGaC7epf1AjJLtaX7krWmzgASHl28Ynh9lmGMdv+5QYMZvKG0LOg/n3m8uJ6sKy\nIzzvaJswwn0j5P5+czyoV5CvvdCfKnNb+3jUEN8I0PPwjBGKr4B1ojwhogTM248V\nHR69D6TxFVMfGpyJhCPkbGEGbpEpcffpgKuC/mEtMqyDQXJNaV5HO6HgAJ9F1P6v\n5ehHHTMRvzCCFiwndHdlMXUjqSNjww6me6dr6LiAPbejdzhL2vWx1YqebOcwQx3G\n-----END RSA PRIVATE KEY-----",
          "passphrase": {
            "ciphertext": "ZjVmNQ==",
            "protected": "eyJhbGciOiJkaXIiLCJlbmMiOiJub25lIn0"
          }
        }
      }
    }
  }
}

Back to top

7: Using a client and server TLS profile in the same declaration

This example shows how you can use both a client and server TLS (SSL) profile in your declarations. See the Schema Reference for usage options and information on Endpoint policies.

This declaration creates the following objects on the BIG-IP:

  • Partition (tenant) named Sample_cert_05.
  • An endpoint policy named testItem.
  • A rule named requestRule.
  • An action for server SSL with a value of true. You could use false to disable the Server SSL profile.
{
    "class": "ADC",
    "schemaVersion": "3.0.0",
    "id": "TEST_Service_HTTPS",
    "Sample_cert_06": {
      "class": "Tenant",
      "TEST_Service_Https_MultiAddr_Local": {
        "class": "Application",
        "template": "https",
        "serviceMain": {
          "class": "Service_HTTPS",
          "virtualAddresses": [
            "192.0.2.1"
          ],
          "virtualPort": 443,
          "clientTLS": "pTlsClient_Local",
          "serverTLS": "pTlsServer_Local"
        },
        "pTlsClient_Local": {
          "class": "TLS_Client",
          "label": "simplest decl requires just cert",
          "clientCertificate": "tlsclient_local_cert"
        },
        "tlsclient_local_cert": {
          "class": "Certificate",
          "remark": "replace these with real certificates and keys",
          "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
          "privateKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
          "passphrase": {
            "ciphertext": "ZjVmNQ==",
            "protected": "eyJhbGciOiJkaXIiLCJlbmMiOiJub25lIn0",
            "ignoreChanges": true
          }
        },
        "pTlsServer_Local": {
          "class": "TLS_Server",
          "label": "simplest decl requires just cert",
          "certificates": [
            {
              "certificate": "tlsserver_local_cert"
            }
          ]
        },
        "tlsserver_local_cert": {
          "class": "Certificate",
          "remark": "replace these with real certificates and keys",
          "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
          "privateKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
          "passphrase":{
              "ciphertext": "ZjVmNQ==",
              "protected": "eyJhbGciOiJkaXIiLCJlbmMiOiJub25lIn0",
              "ignoreChanges": true
          }
        }
      }
    }
  }
  

Back to top