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: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