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:

1. If not verify certificate is not set:

   Debug output:

   client handshake

   Client cert: false

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

1. Client sends HTTPS request without SNI:

   [root@NxLinux certs]# openssl s_client -connect 5.1.1.100:443
   Debug output:
   Client handshake
   SNI: false

2. 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: clientside serverside 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