TLS Encryption¶
This section contains declarations use SSL/TLS certificates and keys.
Use the index on the right 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"}
}
}
}
}
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-----"
}
}
}
}
}
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.0.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-----"
}
}
}
}
}
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" }
}
}
}
}
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
}]
}]
}
}
}
}
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"
}
}
}
}
}
}
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.
This declaration creates the following objects on the BIG-IP:
- Partition (tenant) named Sample_cert_05.
- A virtual server named serviceMain
- A client TLS profile named pTlsClient_Local with a certificate and key
- A server TLS profile named pTlsServer_Local with a certificate and key.
{
"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
}
}
}
}
}
8: Using Client Certificate Constrained Delegation (C3D) features in a declaration¶
This example shows how you can use Client Certificate Constrained Delegation (C3D) in a declaration. C3D is used to support complete end-to-end encryption when interception of SSL traffic in a reverse proxy environment is required and when client certificates are used for mutual authentication. See the C3D documentation and Schema Reference for usage options and information.
This declaration creates the following objects on the BIG-IP:
- Partition (tenant) named Sample_C3D.
- An virtual server named appC3D.
- A server TLS profile (which creates a BIG-IP Client SSL profile) named webtls that uses matchToSNI and multiple certificates, and C3D features enabled.
- A client TLS profile (which creates a BIG-IP Server SSL profile) named clienttls with C3D features enabled.
{
"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
}
}
}
}
}
9: Securing client and server side LDAP traffic¶
This example shows how you can use STARTTLS encryption in a declaration to secure your LDAP traffic. With AS3, you use the ldapStartTLS option to activate the STARTTLS communication protocol that allows or requires STARTTLS encryption. The STARTTLS protocol effectively upgrades a plain-text connection to an encrypted connection on the same port (port 389), instead of using a separate port for encrypted communication. For detailed information, see the Securing LDAP Traffic chapter of the SSL Administration guide.
The ldapStartTLS property only accepts none, allow (allows STARTTLS but doesn’t require it), and require. See the STARTTLS property in TLS_Client in the Schema Reference and the section following that, TLS_Server.
This declaration creates the following objects on the BIG-IP:
- Partition (tenant) named TLS_ldap.
- An virtual server named ldapVip.
- A server TLS profile (which creates a BIG-IP Client SSL profile) named tlsServer that requires STARTTLS (a server LDAP profile is also created with the STARTTLS setting) and a certificate and key.
- A client TLS profile (which creates a BIG-IP Server SSL profile) named tlsClient that allows STARTTLS (a client LDAP profile is also created with the STARTTLS setting).
{
"class": "ADC",
"schemaVersion": "3.10.0",
"id": "TLS_Client",
"TLS_ldap": {
"class": "Tenant",
"Application": {
"class": "Application",
"template": "generic",
"ldapVip": {
"class": "Service_UDP",
"virtualAddresses": [
"10.0.1.186"
],
"clientTLS": "tlsClient",
"serverTLS": "tlsServer",
"virtualPort": 443
},
"tlsClient": {
"class": "TLS_Client",
"ldapStartTLS": "allow"
},
"tlsServer": {
"class": "TLS_Server",
"certificates": [
{
"certificate": "tlsservercert"
}
],
"ldapStartTLS": "require"
},
"tlsservercert": {
"class": "Certificate",
"remark": "in practice using a passphrase is recommended",
"certificate": "-----BEGIN CERTIFICATE-----\nMIID7TCCAtWgAwIBAgIJAJH4sMVzl1dMMA0GCSqGSIb3DQEBCwUAMIGMMQswCQYDVQQGEwJVUzETMBEGA1UECAwKV2FzaGluZ3RvbjEQMA4GA1UEBwwHU2VhdHRsZTELMAkGA1UECgwCRjUxDTALBgNVBAsMBFRlc3QxEzARBgNVBAMMCnRscy1zZXJ2ZXIxJTAjBgkqhkiG9w0BCQEWFnNvbWVib2R5QHNvbWV3aGVyZS5jb20wHhcNMTgwMjI4MTkwNzMyWhcNMjgwMjI2MTkwNzMyWjCBjDELMAkGA1UEBhMCVVMxEzARBgNVBAgMCldhc2hpbmd0b24xEDAOBgNVBAcMB1NlYXR0bGUxCzAJBgNVBAoMAkY1MQ0wCwYDVQQLDARUZXN0MRMwEQYDVQQDDAp0bHMtc2VydmVyMSUwIwYJKoZIhvcNAQkBFhZzb21lYm9keUBzb21ld2hlcmUuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwEMNPATg7Vz3jqInIVf2jnOi/9/HYIr8xZYgU0YHHFEiquQ6nYfX4mwezZ6zo9GJom7gHiQ3FNy3fN+RatatZmBmuyvJ+z/uZ6pbKmsuJLPLT89olO9JxMtb4a83oHDz3f6rcc2j8KwTr4lUDc452jLF4ZQ55O17s2tYMg4XW2G5DqUGzp1UKiClaDvpN23ZVOlnqDVpIlnVvJ1mz12AzFPny8xD1lhILv78yMltimdaWhyCLcFom0DbloRvYmowjGLHqLTAZ40jI3YUdw39LEqTXgfDF3DnOgZCIdRpouD9cVZBoQroXpVVfWG7sfzKLqWaAEHhjbhdK5l/p3mT7wIDAQABo1AwTjAdBgNVHQ4EFgQUBlCKIZ0+9DQ4ylW86qsyXoW8KjkwHwYDVR0jBBgwFoAUBlCKIZ0+9DQ4ylW86qsyXoW8KjkwDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQsFAAOCAQEAuiE5MocznYDc+JHvEgSaiK9fyRBl/bitKTkiOtxWjEFpF5nH6QddV0pqQziXLb6iSbTBwlDJr9Bwzng8moOYbsD7hP2/mCKJj8o/lsRaPAk+abekWXRqYFNucct/ipBG3s+N2PH+MEpy3ioPH1OBuam6UomjE+mqoP09FrQha1hHEbabt4nN11l8fM5GW+0zRU0SwLFvnR58zUSlTMwczSPA0eUrhEU4AGPD/KN8d1fYnCcWqPF5ePcU11k7SNFl5PZQsgXv9cOc2Vq+qc/NmDBO0rQyKEAPDxbM8CK212G1M+ENTqmuePnr+mNope3AhEsqfH8IOPEoT7fIwmpqLw==\n-----END CERTIFICATE-----",
"privateKey": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDAQw08BODtXPeOoichV/aOc6L/38dgivzFliBTRgccUSKq5Dqdh9fibB7NnrOj0YmibuAeJDcU3Ld835Fq1q1mYGa7K8n7P+5nqlsqay4ks8tPz2iU70nEy1vhrzegcPPd/qtxzaPwrBOviVQNzjnaMsXhlDnk7Xuza1gyDhdbYbkOpQbOnVQqIKVoO+k3bdlU6WeoNWkiWdW8nWbPXYDMU+fLzEPWWEgu/vzIyW2KZ1paHIItwWibQNuWhG9iajCMYseotMBnjSMjdhR3Df0sSpNeB8MXcOc6BkIh1Gmi4P1xVkGhCuhelVV9Ybux/MoupZoAQeGNuF0rmX+neZPvAgMBAAECggEAHm3eV9v7z4WRxtjiMZRO+Q/TQgUkdKK6y/jtR9DDClfLEVoK7ujTocnz/B48l1ZwHq3Gue6IazxdrB1kUhEFI7lpOQF+t83QCUc8o5OQG437RTfx+PSAa+21rpwBRVrrNfz7HIlsA4jwmq01CPRVUrQLfp7rpNBzbhu0u0Ngrf0ccOwXZkEUVvZ55WaPY1YADI9PBExQ2k04LvHJjoz/tJH3nsQLA/+90UXqy8ctUSMJ8Ko3crxJhnIO91BtCugkgS+U+pTEnvdAebE4pd7J5e6qqEyCu9F3DC5R6hH+K8bAj76VGwjxOr9a90o/js92HoCVAlQMHnW06Uk2RdIRmQKBgQD0uQPlA2PLBysWA+IQvd8oBfZuXWQjUZPBU9MK5k7bfuRbNeCA2kbTt1MVf15lv7vcwrwAbYo+Ur+L9CVL3lA8d/lQkz51r1ISChTPUiAMyU+CDDnXjQ1Gik/nC399AeluxS62Tur8hGPAb4rkVEyU60hPFVZTjmv13n81EjUoNwKBgQDJHyiPIgbwI+OoZYMUcGQrsr+yp1MdJrjpuFloc7+sdUpsvelyc146h3+TSAlhDce2BMH68kMUWUYHxHIooQjtDMu9S9b8VAF52F3E9osyjMzsywTri3hgBPy69j/Kr623gbZpbm6lYmdxRp/FKZyWtAbPts45GH1GPdv+9fUmCQKBgQCX7CfDy1fvWXLhBuYXuJfJs/HpT+bzmhgdA5nXgWRhFSRUj1zhASDJHFzi0qBakC3i/a1Soq4YxKwPCTECKXAsKdrHr7Etw/oyIroKfpRQ+8R1GnvqGbGtIf46k8PAaihtUNIP8Wwl+VYnx9c0qjSkmm/YUIm384mIKGlWHAiN/wKBgDV5bF5KLNASqsguXWDE1U1tFF0a8hVRI185HcSQ6gifku9Au14r4ITtW/U79QpyEISL1Uu0uDMj3WPZToUQ8/+bJFyrWnjymQXdimkBKFeDakUXYbKC/bmB+fR33tQ0S5r8CRUVQKQGevx6S6avfqvvJ9R4hXJW2ZAgiGrM2KaJAoGAPXuy4KHRmeeBZj8AT/shQ0VrDWIMNYDrhx0T6q9hVMahBS0SJaKDlQn6cSF7TX5N9PFAbwzcrvRKKfNjQVSZpQdR4l42f+N/5q0c1wihf43k9FgeYQ8jHGJ05uJnh3nj/O57FKgjlZ4FZVQdR8ieHN+rT4sHWj36a/FLHa6p1oo=\n-----END PRIVATE KEY-----"
}
}
}
}
10: Using OCSP Certificate Validation in a declaration¶
This example shows how you can define an OCSP Certificate Validator. See the Certificate_Validator_OCSP class in the Schema Reference. The DNS resolver referenced in the Certificate_Validator_OCSP class must already exist on the BIG-IP device.
- 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:
- Partition (tenant) named TEST_Cert_Validator_OCSP.
- A Certificate Validator OCSP object named testCertOcsp that includes a DNS resolver (which must already exist on the target BIG-IP), the signingHashAlgorithm set to sha256 and a reference to the signing certificate.
- A certificate named testCert which includes a certificate and key.
{
"class": "ADC",
"schemaVersion": "3.11.0",
"id": "Certificate_Validator_OCSP",
"TEST_Cert_Validator_OCSP": {
"class": "Tenant",
"Application": {
"class": "Application",
"template": "generic",
"testCertOcsp": {
"class": "Certificate_Validator_OCSP",
"dnsResolver": {
"bigip": "/Common/10.1.1.10"
},
"timeout": 8,
"signingHashAlgorithm": "sha256",
"signingCertificate": {
"use": "testCert"
}
},
"testCert": {
"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
}
}
}
},
"updateMode": "selective"
}
11: Using the staplerOCSP parameter in a certificate¶
This example shows in detail how you can use the staplerOCSP parameter in a certificate as a part of a declaration. OCSP stapling is a standard for checking the revocation status of X.509 digital certificates. See the staplerOCSP property in Certificate class and Certificate_Validator_OCSP class in the Schema Reference.
Important notes about this declaration:
- In the certificate you are referencing in TLS_Server, staplerOCSP must be set on the certificate, as shown in this declaration.
- For a certificate to be able to use staplerOCSP, it cannot be a self-signed certificate.
- In this example, the issuer certificate already exists on the BIG-IP device (you can also use a pointer).
- The DNS resolver referenced in the Certificate_Validator_OCSP class must already exist on the BIG-IP device
- This example does not include a real certificate, so if you post the following declaration, you will receive an invalid certificate error. Replace the value of certificate with your own certificate.
This declaration creates the following objects on the BIG-IP:
- Partition (tenant) named TLS_Server_OCSP.
- A server TLS profile (which creates a BIG-IP Client SSL profile) named testItem, with staplerOCSPEnabled set to true, and a reference to the certificate.
- A certificate named cert which includes references to the certificate validator OCSP object and an issuer certificate that already exists on our BIG-IP system.
- A Certificate Validator OCSP object named testOcsp that includes a DNS resolver (which must already exist on the target BIG-IP) and a responder URL (which specifies the absolute URL that overrides the OCSP responder URL obtained from the certificate’s AIA extension(s)).
{
"class": "ADC",
"schemaVersion": "3.11.0",
"id": "TLS_Server",
"TLS_Server_OCSP": {
"class": "Tenant",
"Application": {
"class": "Application",
"template": "generic",
"testItem": {
"class": "TLS_Server",
"certificates": [
{
"certificate": "cert"
}
],
"staplerOCSPEnabled": true
},
"cert": {
"class": "Certificate",
"remark": "replace these with real certificates",
"certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
"staplerOCSP": {
"use": "testOcsp"
},
"issuerCertificate": {
"bigip": "/Common/issuer.crt"
}
},
"testOcsp": {
"class": "Certificate_Validator_OCSP",
"dnsResolver": {
"bigip": "/Common/198.168.111.22"
},
"timeout": 250,
"responderUrl": "http://oscp.test.com"
}
}
}
}