SSL commands
SSL commands contain functions for obtaining SSL related information, such as obtaining certificates and SNI:
SSL:cipher() — Returns the cipher in the handshake.
SSL:version() — Returns the SSL version in the handshake.
SSL:alg_keysize() — Returns the SSL encryption key size in the handshake.
SSL:client_cert() — Returns the status of client-certificate-verify, whether or not it is enabled.
SSL:sni() — Returns the SNI or false (if no SNI).
SSL:npn() — Returns the next protocol negotiation string or false (if no NPN).
SSL:alpn() — Allows you to get the SSL ALPN extension.
SSL:session(t) — Allows you to get SSL session ID, reuse the session, or remove it from the cache.
SSL:cert(t) — Allows you to get the certificate information between local or remote.
SSL:cert_der() — Returns the DER certificate when the client enables verify certificate.
SSL:peer_cert(str) — Returns the peer certificate.
SSL:disable() — Disables SSL processing on either the client or server side when non-SSL traffic is expected or desired.
SSL:cipher()
Returns the cipher in the handshake.
Syntax
SSL:cipher();
Arguments
N/A
Example
when CLIENTSSL_HANDSHAKE{ debug("client_handshake\n") ci=SSL:cipher(); debug("Cipher: %s \n",ci); } Result: (if client send https request with cipher ECDHE-RSA-DES-CBC3-SHA) Cipher: ECDHE-RSA-DES-CBC3-SHA
FortiADC version: V5.0
Used in events: CLIENTSSL_HANDSHAKE / SERVERSSL_HANDSHAKE
SSL:version()
Returns the SSL version in the handshake.
Syntax
SSL:version();
Arguments
N/A
Example
when CLIENTSSL_HANDSHAKE{ debug("client handshake\n") ver=SSL:version(); debug("SSL Version: %s \n",ver); } Result: (client send https request with various version) client handshake SSL Version: TLSv1 or client handshake SSL Version: TLSv1.1 or client handshake SSL Version: TLSv1.2 or client handshake SSL Version: SSLv3
FortiADC version: V5.0
Used in events: CLIENTSSL_HANDSHAKE / SERVERSSL_HANDSHAKE
SSL:alg_keysize()
Returns the SSL encryption key size in the handshake.
Syntax
SSL:alg_keysize();
Arguments
N/A
Example
when CLIENTSSL_HANDSHAKE{ debug("client handshake\n") ci=SSL:cipher(); key=SSL:alg_keysize(); debug("Cipher: %s\n",ci) debug("Alg key size: %s \n",key); } Result: (client send https request with various ciphers) client handshake Cipher: ECDHE-RSA-RC4-SHA Alg key size: 128 or client handshake Cipher: ECDHE-RSA-DES-CBC3-SHA Alg key size: 168 or client handshake Cipher: EDH-RSA-DES-CBC-SHA Alg key size: 56 or client handshake Cipher: ECDHE-RSA-AES256-GCM-SHA384 Alg key size: 256
FortiADC version: V5.0
Used in events: CLIENTSSL_HANDSHAKE / SERVERSSL_HANDSHAKE
SSL:client_cert()
Returns the status of client-certificate-verify, whether or not it is enabled.
Syntax
SSL:client_cert();
Arguments
N/A
Example
when CLIENTSSL_HANDSHAKE{ debug("client handshake\n") cc=SSL:client_cert(); debug("Client cert: %s \n",cc); }
Result:
-
If not verify certificate is not set:
Debug output:
client handshake
Client cert: false
-
If enabled verify in client-ssl-profile:
config system certificate certificate_verify edit "verify" config group_member edit 2 set ca-certificate ca6 next end next end config load-balance client-ssl-profile edit "csp" set client-certificate-verify verify next end debug output: client handshake Client cert: true
FortiADC version: V5.0
Used in events: CLIENTSSL_HANDSHAKE / SERVERSSL_HANDSHAKE / CLIENTSSL_RENEGOTIATE / SERVERSSL_RENEGOTIATE
SSL:sni()
Returns the SNI or false (if no SNI).
Syntax
SSL:sni();
Arguments
N/A
Example
when CLIENTSSL_HANDSHAKE { debug("client handshake\n") cc=SSL:sni(); debug("SNI: %s \n",cc); }
Result:
Enable sni in client-ssl-profile
config load-balance client-ssl-profile
edit "csp"
set client-sni-required enable
next
end
-
Client sends HTTPS request without SNI:
[root@NxLinux certs]# openssl s_client -connect 5.1.1.100:443 Debug output: Client handshake SNI: false
-
Client sends HTTPS request with SNI:
openssl s_client -connect 5.1.1.100:443 -servername 4096-rootca-rsa-server1 debug output : client handshake SNI: 4096-rootca-rsa-server1
FortiADC version: V5.0
Used in events: CLIENTSSL_HANDSHAKE / SERVERSSL_HANDSHAKE / CLIENTSSL_RENEGOTIATE / SERVERSSL_RENEGOTIATE
SSL:npn()
Returns the next protocol negotiation string or false (if no NPN).
Syntax
SSL:npn();
Arguments
N/A
Example
when CLIENTSSL_HANDSHAKE { npn = SSL:npn() }
FortiADC version: V5.0
Used in events: CLIENTSSL_HANDSHAKE / SERVERSSL_HANDSHAKE / CLIENTSSL_RENEGOTIATE / SERVERSSL_RENEGOTIATE
SSL:alpn()
Allows you to get the SSL ALPN extension.
Syntax
SSL:alpn();
Arguments
N/A
Example
when CLIENTSSL_HANDSHAKE { alpn = SSL:alpn() }
FortiADC version: V5.0
Used in events: CLIENTSSL_HANDSHAKE / SERVERSSL_HANDSHAKE / CLIENTSSL_RENEGOTIATE / SERVERSSL_RENEGOTIATE
SSL:session(t)
Allows you to get SSL session ID, reuse the session, or remove it from the cache.
Syntax
SSL:session(t);
Arguments
Name | Description |
---|---|
t |
A table which specifies the operation to the session. |
Example
when CLIENTSSL_HANDSHAKE { t={} t[“operation”] = “get_id”; --can be “get_id” or “remove” or “reused” sess_Id = SSL:session(t) if sess_id then id = to_HEX(sess_id) debug(“client sess id %s\n”, id) else sess_id = “FALSE” end }
FortiADC version: V5.0
Used in events: CLIENTSSL_HANDSHAKE / SERVERSSL_HANDSHAKE / CLIENTSSL_RENEGOTIATE / SERVERSSL_RENEGOTIATE
SSL:cert(t)
Allows you to get the certificate information between local or remote.
Syntax
SSL:cert(t);
Arguments
Name | Description |
---|---|
t |
A table which specifies the certificate direction, and operation. |
Example
when CLIENTSSL_HANDSHAKE{ debug("client handshake\n") t={} t["direction"]="remote"; t["operation"]="index"; t["idx"]=0; t["type"]="info"; cert=SSL:cert(t) if cert then debug("client has cert\n") end for k,v in pairs(cert) do if k=="serial_number" or k=="digest" then debug("cert info name %s, value in HEX %s\n", k, to_HEX(v)); else debug("cert info name %s, value %s\n", k, v); end end }
Note:
-
direction: local and remote. In CLIENTSSL_HANDSHAKE, local means FortiADC's cert, remote means client's cert.
-
operation: index, count, issuer
-
type: info, der, (pem)
This command returns a table that contains all the information in the certificate.
In the return, it contains: key_algorithm, hash, serial_number, not Before, not After, signature_algorithm, version, digest, issuer_name, subject_name, old_hash, pin-sha256, finger_print.
FortiADC version: V5.0
Used in events: CLIENTSSL_HANDSHAKE / SERVERSSL_HANDSHAKE / CLIENTSSL_RENEGOTIATE / SERVERSSL_RENEGOTIATE
SSL:cert_der()
Returns the DER certificate when the client enables verify certificate.
Syntax
SSL:cert_der();
Arguments
N/A
Example
when CLIENTSSL_HANDSHAKE{ debug("client handshake\n") cder=SSL:cert_der(); --debug("cder in HEX %s\n", to_HEX(cder)); if cder then cder_hex=b64_enc_str(cder); debug("whole cert : %s\n", cder_hex); end }
FortiADC version: V5.0
Used in events: CLIENTSSL_HANDSHAKE / CLIENTSSL_RENEGOTIATE
SSL:peer_cert(str)
Returns the peer certificate.
Syntax
SSL:peer_cert(str);
Arguments
Name | Description |
---|---|
str |
A string which specifies the certificate format. |
Example
when CLIENTSSL_HANDSHAKE { cder = SSL:peer_cert(“der”); --for remote leaf certificate, the input parameter can be “info” or “der” or “pem” if cder then hash = sha1_hex_str(cder) debug(“whole cert sha1 hash is: %s\n”, hash) end }
FortiADC version: V5.0
Used in events: CLIENTSSL_HANDSHAKE / SERVERSSL_HANDSHAKE / CLIENTSSL_RENEGOTIATE / SERVERSSL_RENEGOTIATE
SSL:disable()
Disables SSL processing on either the client or server side when non-SSL traffic is expected or desired.
Returns Boolean true if successful, otherwise, returns Boolean false.
This command only disables the SSL function on the current virtual server, and does not change any settings of the virtual server.
Before executing this command, ensure that HTTP connections are able to work in your virtual server environment.
Syntax
SSL:disable([side_name]);
Arguments
Name | Description |
---|---|
side_name |
A Lua string to indicate on which side the SSL will be disabled. You can input either of the following:
This argument is optional. If it is not specified, FortiADC will determine which side to use based on the event where this API is called. |
Examples
--Client side must be TCP ACCEPTED when TCP_ACCEPTED { debug("------> TCP accepted begin:\n"); srcIP = IP:client_addr(); srcPort = IP:client_port(); debug("------> Client ip:port %s:%s\n", srcIP, srcPort); destIP = IP:local_addr(); destPort = IP:local_port(); debug("------> Local ip:port %s:%s\n", destIP, destPort); if tonumber(destPort) == 80 then ret = SSL:disable("clientside"); if ret then debug("------> SSL disable clientside successfully.\n"); else debug("------> SSL disable clientside failed.\n"); end else debug("------> SSL disable clientside skipped.\n"); end debug("------> TCP accepted end.\n"); }
--Server side can be called within many events when HTTP_REQUEST { debug("------> HTTP Request begin:\n"); srcIP = IP:client_addr(); srcPort = IP:client_port(); debug("------> Client ip:port %s:%s\n", srcIP, srcPort); destIP = IP:local_addr(); destPort = IP:local_port(); debug("------> Local ip:port %s:%s\n", destIP, destPort); if tonumber(destPort) == 80 then ret = SSL:disable("serverside"); if ret then debug("------> SSL disable serverside successfully.\n"); else debug("------> SSL disable serverside failed.\n"); end else debug("------> SSL disable serverside skipped.\n"); end debug("------> HTTP Request end.\n"); }
FortiADC version: V7.4.3
Used in events:
Client side:
-
TCP_ACCEPTED
Server side:
-
HTTP_REQUEST
-
BEFORE_AUTH
-
AUTH_RESULT
-
PERSISTENCE
-
POST_PERSIST
-
SERVER_BEFORE_CONNECT