Multiple Certs, One VIP: TLS Server Name Indication via iRules
An age old question that we’ve seen time and time again in the iRules forums here on DevCentral is “How can I use iRules to manage multiple SSL certs on one VIP"?”. The answer has always historically been “I’m sorry, you can’t.”. The reasoning is sound. One VIP, one cert, that’s how it’s always been. You can’t do anything with the connection until the handshake is established and decryption is done on the LTM. We’d like to help, but we just really can’t. That is…until now.
The TLS protocol has somewhat recently provided the ability to pass a “desired servername” as a value in the originating SSL handshake. Finally we have what we’ve been looking for, a way to add contextual server info during the handshake, thereby allowing us to say “cert x is for domain x” and “cert y is for domain y”. Known to us mortals as "Server Name Indication" or SNI (hence the title), this functionality is paramount for a device like the LTM that can regularly benefit from hosting multiple certs on a single IP. We should be able to pull out this information and choose an appropriate SSL profile now, with a cert that corresponds to the servername value that was sent. Now all we need is some logic to make this happen.
Lucky for us, one of the many bright minds in the DevCentral community has whipped up an iRule to show how you can finally tackle this challenge head on. Because Joel Moses, the shrewd mind and DevCentral MVP behind this example has already done a solid write up I’ll quote liberally from his fine work and add some additional context where fitting. Now on to the geekery:
First things first, you’ll need to create a mapping of which servernames correlate to which certs (client SSL profiles in LTM’s case). This could be done in any manner, really, but the most efficient both from a resource and management perspective is to use a class. Classes, also known as DataGroups, are name->value pairs that will allow you to easily retrieve the data later in the iRule. Quoting Joel:
Create a string-type datagroup to be called "tls_servername". Each hostname that needs to be supported on the VIP must be input along with its matching clientssl profile. For example, for the site "testsite.site.com" with a ClientSSL profile named "clientssl_testsite", you should add the following values to the datagroup.
String: testsite.site.com
Value: clientssl_testsite
Once you’ve finished inputting the different server->profile pairs, you’re ready to move on to pools. It’s very likely that since you’re now managing multiple domains on this VIP you'll also want to be able to handle multiple pools to match those domains. To do that you'll need a second mapping that ties each servername to the desired pool. This could again be done in any format you like, but since it's the most efficient option and we're already using it, classes make the most sense here. Quoting from Joel:
If you wish to switch pool context at the time the servername is detected in TLS, then you need to create a string-type datagroup called "tls_servername_pool". You will input each hostname to be supported by the VIP and the pool to direct the traffic towards. For the site "testsite.site.com" to be directed to the pool "testsite_pool_80", add the following to the datagroup:
String: testsite.site.com Value: testsite_pool_80
If you don't, that's fine, but realize all traffic from each of these hosts will be routed to the default pool, which is very likely not what you want. Now then, we have two classes set up to manage the mappings of servername->SSLprofile and servername->pool, all we need is some app logic in line to do the management and provide each inbound request with the appropriate profile & cert. This is done, of course, via iRules. Joel has written up one heck of an iRule which is available in the codeshare (here) in it's entirety along with his solid write-up, but I'll also include it here in-line, as is my habit.
Effectively what's happening is the iRule is parsing through the data sent throughout the SSL handshake process and searching for the specific TLS servername extension, which are the bits that will allow us to do the profile switching magic. He's written it up to fall back to the default client SSL profile and pool, so it's very important that both of these things exist on your VIP, or you may likely find yourself with unhappy users.
One last caveat before the code: Not all browsers support Server Name Indication, so be careful not to implement this unless you are very confident that most, if not all, users connecting to this VIP will support SNI. For more info on testing for SNI compatibility and a list of browsers that do and don't support it, click through to Joel's awesome CodeShare entry, I've already plagiarized enough.
So finally, the code. Again, my hat is off to Joel Moses for this outstanding example of the power of iRules. Keep at it Joel, and thanks for sharing!
1: when CLIENT_ACCEPTED {
2: if { [PROFILE::exists clientssl] } {
3: 4: # We have a clientssl profile attached to this VIP but we need
5: # to find an SNI record in the client handshake. To do so, we'll
6: # disable SSL processing and collect the initial TCP payload.
7: 8: set default_tls_pool [LB::server pool]
9: set detect_handshake 1
10: SSL::disable
11: TCP::collect
12: 13: } else {
14: 15: # No clientssl profile means we're not going to work.
16: 17: log local0. "This iRule is applied to a VS that has no clientssl profile."
18: set detect_handshake 0
19: 20: } 21: 22: } 23: 24: when CLIENT_DATA {
25: 26: if { ($detect_handshake) } {
27: 28: # If we're in a handshake detection, look for an SSL/TLS header.
29: 30: binary scan [TCP::payload] cSS tls_xacttype tls_version tls_recordlen
31: 32: # TLS is the only thing we want to process because it's the only
33: # version that allows the servername extension to be present. When we
34: # find a supported TLS version, we'll check to make sure we're getting
35: # only a Client Hello transaction -- those are the only ones we can pull
36: # the servername from prior to connection establishment.
37: 38: switch $tls_version {
39: "769" -
40: "770" -
41: "771" {
42: if { ($tls_xacttype == 22) } {
43: binary scan [TCP::payload] @5c tls_action
44: if { not (($tls_action == 1) && ([TCP::payload length] > $tls_recordlen)) } {
45: set detect_handshake 0
46: } 47: } 48: }49: default {
50: set detect_handshake 0
51: } 52: } 53: 54: if { ($detect_handshake) } {
55: 56: # If we made it this far, we're still processing a TLS client hello.
57: #
58: # Skip the TLS header (43 bytes in) and process the record body. For TLS/1.0 we
59: # expect this to contain only the session ID, cipher list, and compression
60: # list. All but the cipher list will be null since we're handling a new transaction
61: # (client hello) here. We have to determine how far out to parse the initial record
62: # so we can find the TLS extensions if they exist.
63: 64: set record_offset 43
65: binary scan [TCP::payload] @${record_offset}c tls_sessidlen
66: set record_offset [expr {$record_offset + 1 + $tls_sessidlen}]
67: binary scan [TCP::payload] @${record_offset}S tls_ciphlen
68: set record_offset [expr {$record_offset + 2 + $tls_ciphlen}]
69: binary scan [TCP::payload] @${record_offset}c tls_complen
70: set record_offset [expr {$record_offset + 1 + $tls_complen}]
71: 72: # If we're in TLS and we've not parsed all the payload in the record
73: # at this point, then we have TLS extensions to process. We will detect
74: # the TLS extension package and parse each record individually.
75: 76: if { ([TCP::payload length] >= $record_offset) } {
77: binary scan [TCP::payload] @${record_offset}S tls_extenlen
78: set record_offset [expr {$record_offset + 2}]
79: binary scan [TCP::payload] @${record_offset}a* tls_extensions
80: 81: # Loop through the TLS extension data looking for a type 00 extension
82: # record. This is the IANA code for server_name in the TLS transaction.
83: 84: for { set x 0 } { $x < $tls_extenlen } { incr x 4 } {
85: set start [expr {$x}]
86: binary scan $tls_extensions @${start}SS etype elen
87: if { ($etype == "00") } {
88: 89: # A servername record is present. Pull this value out of the packet data
90: # and save it for later use. We start 9 bytes into the record to bypass
91: # type, length, and SNI encoding header (which is itself 5 bytes long), and
92: # capture the servername text (minus the header).
93: 94: set grabstart [expr {$start + 9}]
95: set grabend [expr {$elen - 5}]
96: binary scan $tls_extensions @${grabstart}A${grabend} tls_servername
97: set start [expr {$start + $elen}]
98: } else {
99: 100: # Bypass all other TLS extensions.
101: 102: set start [expr {$start + $elen}]
103: }104: set x $start
105: } 106: 107: # Check to see whether we got a servername indication from TLS. If so,
108: # make the appropriate changes.
109: 110: if { ([info exists tls_servername] ) } {
111: 112: # Look for a matching servername in the Data Group and pool.
113: 114: set ssl_profile [class match -value [string tolower $tls_servername] equals tls_servername]
115: set tls_pool [class match -value [string tolower $tls_servername] equals tls_servername_pool]
116: 117: if { $ssl_profile == "" } {
118: 119: # No match, so we allow this to fall through to the "default"
120: # clientssl profile.
121: 122: SSL::enable
123: } else {
124: 125: # A match was found in the Data Group, so we will change the SSL
126: # profile to the one we found. Hide this activity from the iRules
127: # parser.
128: 129: set ssl_profile_enable "SSL::profile $ssl_profile"
130: catch { eval $ssl_profile_enable }
131: if { not ($tls_pool == "") } {
132: pool $tls_pool
133: } else {
134: pool $default_tls_pool
135: }136: SSL::enable
137: }138: } else {
139: 140: # No match because no SNI field was present. Fall through to the
141: # "default" SSL profile.
142: 143: SSL::enable
144: } 145: 146: } else {
147: 148: # We're not in a handshake. Keep on using the currently set SSL profile
149: # for this transaction.
150: 151: SSL::enable
152: } 153: 154: # Hold down any further processing and release the TCP session further
155: # down the event loop.
156: 157: set detect_handshake 0
158: TCP::release
159: } else {
160: 161: # We've not been able to match an SNI field to an SSL profile. We will
162: # fall back to the "default" SSL profile selected (this might lead to
163: # certificate validation errors on non SNI-capable browsers.
164: 165: set detect_handshake 0
166: SSL::enable
167: TCP::release
168: 169: } 170: } 171: }Published Apr 05, 2011
Version 1.0
lla0_161646Nimbostratus
Great article! I am a novice with f5, but I could manage my configuration with this example. Thanks a lot!
Jari_ArtesThis solved my problem, thanks. A small fix to avoid runtime TCL errors when the signed tls_version variable becomes negative: 38: switch $tls_version { to 38: switch -- $tls_version {
vinzclorthoWe have been advised that when using native SNI on a virtual server, adding or removing a ClientSSL Profile from the virtual will cause all certs on it to be removed and re-added, breaking connections to the VS. Is that the case with this iRule approach, or can that behavior be avoided when using this iRule?
Raphael1Can SSL::sni make this iRule simpler?
Thanks!
Stanislas_Piro2Cumulonimbus
@Raphael, BIGIP supports SNI from version 11.1. from previous versions, this irule was the only solution to filter Servername
then, SSL::sin is only available from version 12.0, so between 11.1 and 12.0, to get Server name, you had to replace
bySSL::sni name[string range [SSL::extensions -type 0] 9 end]For your information, I tried
in version 13.0 HF2 and it did not return any value.[SSL::sni name]- Raphael1
For [SSL::sni name] returning value, there should be value set in server name indication in the client ssl profile, therefore, this irule may be the only way to capture SNI before client ssl handshake currently.
- nemmank
Wouldn't it be simpler to just see a code that just worked. I mean practically, dead simple. I have searched severally but every advise I get suggest adding multiple ssl profiles to the same VIP and let the VIP auto-select the best server ssl to use. I mean this is like completely handing off critical decision making to random sense. What if the server ssl are incorrectly selected and this leave room for difficult in pin-pointing the failure. I managed to put together few ideas and have an irule that really works, provides logging if the wrong ssl profile or nothing is selected. You need to prepare the fqdn or server IP:port pools to go with it though:
1) Create ephemeral Pools point to new fqdn or server IP:port pools
a) fqdn-a.new_fqdn_pool
b) fqdn-b.new_fqdn_pool
c) fqdn-c.new_fqdn_pool
d) fqdn-d.new_fqdn_pool
2) Create Server SSL profile for each of the new fqdn destination urls:
a) fqdn-a_serverssl
b) fqdn-b_serverssl
c) fqdn-c_serverssl
d) fqdn-d_serverssl
3) Create new iRule and attach to inbound VIP
when HTTP_REQUEST {
# Inspect inbound host header and replace based on original url
switch [HTTP::host] {
"fqdn-a.original_fqdn" {
set new_fqdn "fqdn-a.new_fqdn"
set doSSL 1
SSL::enable serverside
}
"fqdn-b.original_fqdn" {
set new_fqdn "fqdn-b.new_fqdn"
set doSSL 2
SSL::enable serverside
}
"fqdn-c.original_fqdn" {
set new_fqdn "fqdn-c.new_fqdn"
set doSSL 3
SSL::enable serverside
}
"fqdn-d.original_fqdn" {
set new_fqdn "fqdn-d.new_fqdn"
set doSSL 4
SSL::enable serverside
}
default {
log local0. "Inbound fqdn not known: [HTTP::host]"
reject
}
}
HTTP::header replace Host $new_fqdn
pool ${new_fqdn}_pool
}
when SERVER_CONNECTED {
#doSSL variable is checked and SSL disabled or profile selected
if {$doSSL == 1} {
SSL::profile fqdn-a_serverssl
log "Using Server SSL fqdn-a_serverssl"
} elseif {$doSSL == 2} {
SSL::profile fqdn-b_serverssl
log "Using Server SSL fqdn-b_serverssl"
} elseif {$doSSL == 3} {
SSL::profile fqdn-c_serverssl
log "Using Server SSL fqdn-c_serverssl"
} elseif {$doSSL == 4} {
SSL::profile fqdn-d_serverssl
log "Using Server SSL fqdn-d_serverssl"
}
}
John_KalanThe iRule in the original article works great except that it requires the entire CLIENT_HELLO fit within one TCP packet (because the CLIENT_DATA event gives you only the first packet). With the increasing number of extensions, very large CLIENT_HELLO messages are now possible (looking at you, Edge!).
Perhaps a fix is to remove the extra check in Line 44 ([TCP::payload length] > $tls_recordlen). This changes the requirement from "must fit in one packet" to "SNI must be present in the first packet".
TCL (binary scan) seems to defend well against the buffer overflow that might result.