SSL Profiles Part 1: Handshakes
This is the first in a series of tech tips on the F5 BIG-IP LTM SSL profiles. SSL Overview and Handshake SSL Certificates Certificate Chain Implementation Cipher Suites SSL Options SSL Renegotiation Server Name Indication Client Authentication Server Authentication All the "Little" Options SSL, or the Secure Socket Layer, was developed by Netscape back in the ‘90s to secure the transport of web content. While adopted globally, the standards body defined the Transport Layer Security, or TLS 1.0, a few years later. Commonly interchanged in discussions, the final version of SSL (v3) and the initial version of TLS (v1) do not interoperate, though TLS includes the capabality to downgrade to SSLv3 if necessary. Before we dive into the options within the SSL profiles, we’ll start in this installment with a look at the SSL certificate exchanges and take a look at what makes a client versus a server ssl profile. Server-Only Authentication This is the basic TLS handshake, where the only certificate required is on the serverside of the connection. The exchange is shown in Figure 1 below. In the first step. the client sends a ClientHello message containing the cipher suites (I did a tech tip a while back on manipulating profiles that has a good breakdown of the fields in a ClientHello message), a random number, the TLS version it supports (highest), and compression methods. The ServerHello message is then sent by the server with the version, a random number, the ciphersuite, and a compression method from the clients list. The server then sends its Certificate and follows that with the ServerDone message. The client responds with key material (depending on cipher selected) and then begins computing the master secret, as does the server upon receipt of the clients key material. The client then sends the ChangeCipherSpec message informing the server that future messages will be authenticated and encrypted (encryption is optional and dependent on parameters in server certificate, but most implementations include encryption). The client finally sends its Finished message, which the server will decrypt and verify. The server then sends its ChangeCipherSpec and Finished messages, with the client performing the same decryption and verification. The application messages then start flowing and when complete (or there are SSL record errors) the session will be torn down. Question—Is it possible to host multiple domains on a single IP and still protect with SSL/TLS without certificate errors? This question is asked quite often in the forums. The answer is in the details we’ve already discussed, but perhaps this isn’t immediately obvious. Because the application messages—such as an HTTP GET—are not received until AFTER this handshake, there is no ability on the server side to switch profiles, so the default domain will work just fine, but the others will receive certificate errors. There is hope, however. In the TLSv1 standard, there is an option called Server Name Indication, or SNI, which will allow you to extract the server name and switch profiles accordingly. This could work today—if you control the client base. The problem is most browsers don’t default to TLS, but rather SSLv3. Also, TLS SNI is not natively supported in the profiles, so you’ll need to get your hands dirty with some serious iRule-fu (more on this later in the series). Anyway, I digress. Client-Authenticated Handshake The next handshake is the client-authenticated handshake, shown below in Figure 2. This handshake adds a few steps (in bold above), inserting the CertificateRequest by the server in between the Certificate and ServerHelloDone messages, and the client starting off with sending its Certificate and after sending its key material in the ClientKeyExchange message, sends the CertificateVerify message which contains a signature of the previous handshake messages using the client certificate’s private key. The server, upon receipt, verifies using the client’s public key and begins the heavy compute for the master key before both finish out the handshake in like fashion to the basic handshake. Resumed Handshake Figure 3 shows the abbreviated handshake that allows the performance gains of not requiring the recomputing of keys. The steps passed over from the full handshake are greyed out. It’s after step 5 that ordinarily both server and client would be working hard to compute the master key, and as this step is eliminated, bulk encryption of the application messages is far less costly than the full handshake. The resumed session works by the client submitting the existing session ID from previous connections in the ClientHello and the server responding with same session ID (if the ID is different, a full handshake is initiated) in the ServerHello and off they go. Profile Context As with many things, context is everything. There are two SSL profiles on the LTM, clientssl and serverssl. The clientssl profile is for acting as the SSL server, and the serverssl profile is for acting as the SSL client. Not sure why it worked out that way, but there you go. So if you will be offloading SSL for your applications, you’ll need a clientssl profile. If you will be offloading SSL to make decisions/optimizations/inspects, but still require secured transport to your servers, you’ll need a clientssl and a serverssl profile. Figure 4 details the context. Conclusion Hopefully this background on the handshake process and the profile context is beneficial to the profile options we’ll cover in this series. For a deeper dive into the handshakes (and more on TLS), you can check out RFC 2246 and this presentation on SSL and TLS cryptography. Next up, we’ll take a look at Certificates.
Two-Factor Authentication With Google Authenticator And APM
Introduction Two-factor authentication (TFA) has been around for many years and the concept far pre-dates computers. The application of a keyed padlock and a combination lock to secure a single point would technically qualify as two-factor authentication: “something you have,” a key, and “something you know,” a combination. Until the past few years, two-factor authentication in its electronic form has been reserved for high security environments: government, banks, large companies, etc. The most common method for implementing a second authentication factor has been to issue every employee a disconnected time-based one-time password hard token. The term “disconnected” refers to the absence of a connection between the token and a central authentication server. A “hard token” implies that the device is purpose-built for authentication and serves no other purpose. A soft or “software” token on the other hand has other uses beyond providing an authentication mechanism. In the context of this article we will refer to mobile devices as a soft tokens. This fits our definition as the device an be used to make phone calls, check email, surf the Internet, all in addition to providing a time-based one-time password. A time-based one-time password (TOTP) is a single use code for authenticating a user. It can be used by itself or to supplement another authentication method. It fits the definition of “something you have” as it cannot be easily duplicated and reused elsewhere. This differs from a username and password combination, which is “something you know,” but could be easily duplicated by someone else. The TOTP uses a shared secret and the current time to calculate a code, which is displayed for the user and regenerated at regular intervals. Because the token and the authentication server are disconnected from each other, the clocks of each must be perfectly in sync. This is accomplished by using Network Time Protocol (NTP) to synchronize the clocks of each device with the correct time of central time servers. Using Google Authenticator as a soft token application makes sense from many angles. It is low cost due to the proliferation of smart phones and is available from the “app store” free of charge on all major platforms. It uses an open standard (defined by RFC 4226), which means that it is well-tested, understood, secure. Calculation as you will later see is well-documented and relatively easy to implement in your language of choice (iRules in our case). This process is explained in the next section. This Tech Tip is a follow-up to Two-Factor Authentication With Google Authenticator And LDAP. The first article in this series highlighted two-factor authentication with Google Authenticator and LDAP on an LTM. In this follow-up, we will be covering implementation of this solution with Access Policy Manager (APM). APM allows for far more granular control of network resources via access policies. Access policies are rule sets, which are intuitively displayed in the UI as flow charts. After creation, an access policy is applied to a virtual server to provide security, authentication services, client inspection, policy enforcement, etc. This article highlights not only a two-factor authentication solution, but also the usage of iRules within APM policies. By combining the extensibility of iRules with the APM’s access policies, we are able to create virtually any functionality we might need. Note: A 10-user fully-featured APM license is included with every LTM license. You do not need to purchase an additional module to use this feature if you have less than 10 users. Calculating The Google Authenticator TOTP The Google Authenticator TOTP is calculated by generating an HMAC-SHA1 token, which uses a 10-byte base32-encoded shared secret as a key and Unix time (epoch) divided into a 30 second interval as inputs. The resulting 80-byte token is converted to a 40-character hexadecimal string, the least significant (last) hex digit is then used to calculate a 0-15 offset. The offset is then used to read the next 8 hex digits from the offset. The resulting 8 hex digits are then AND’d with 0x7FFFFFFF (2,147,483,647), then the modulo of the resultant integer and 1,000,000 is calculated, which produces the correct code for that 30 seconds period. Base32 encoding and decoding were covered in my previous Tech Tip titled Base32 Encoding And Decoding With iRules . The Tech Tip details the process for decoding a user’s base32-encoded key to binary as well as converting a binary key to base32. The HMAC-SHA256 token calculation iRule was originally submitted by Nat to the Codeshare on DevCentral. The iRule was slightly modified to support the SHA-1 algorithm, but is otherwise taken directly from the pseudocode outlined in RFC 2104. These two pieces of code contribute the bulk of the processing of the Google Authenticator code. The rest is done with simple bitwise and arithmetic functions. Triggering iRules From An APM Access Policy Our previously published Google Authenticator iRule combined the functionality of Google Authenticator token verification with LDAP authentication. It was written for a standalone LTM system without the leverage of APM’s Visual Policy Editor. The issue with combining these two authentication factors in a single iRule is that their functionality is not mutually exclusive or easily separable. We can greatly reduce the complexity of our iRule by isolating functionality for Google Authenticator token verification and moving the directory server authentication to the APM access policy. APM iRules differ from those that we typically develop for LTM. iRules assigned to LTM virtual server are triggered by events that occur during connection or payload handling. Many of these events still apply to an LTM virtual server with an APM policy, but do not have perspective into the access policy. This is where we enter the realm of APM iRules. APM iRules are applied to a virtual server exactly like any other iRule, but are triggered by custom iRule event agent IDs within the access policy. When the access policy reaches an iRule event, it will trigger the ACCESS_POLICY_AGENT_EVENT iRule event. Within the iRule we can execute the ACCESS::policy agent_id command to return the iRule event ID that triggered the event. We can then match on this ID string prior to executing any additional code. Within the iRule we can get and set APM session variables with the ACCESS::session command, which will serve as our conduit for transferring variables to and from our access policy. A visual walkthrough of this paragraph is shown below. iRule Trigger Process Create an iRule Event in the Visual Policy Editor Specify a Name for the object and an ID for the Custom iRule Event Agent Create an iRule with the ID referenced and assign it to the virtual server 1: when ACCESS_POLICY_AGENT_EVENT { 2: if { [ACCESS::policy agent_id] eq "ga_code_verify" } { 3: # get APM session variables 4: set username [ACCESS::session data get session.logon.last.username] 5: 6: ### Google Authenticator token verification (code omitted for brevity) ### 7: 8: # set APM session variables 9: ACCESS::session data set session.custom.ga_result $ga_result 10: } 11: } Add branch rules to the iRule Event which read the custom session variable and handle the result Google Authenticator Two-Factor Authentication Process Two-Factor Authentication Access Policy Overview Rather than walking through the entire process of configuring the access policy from scratch, we’ll look at the policy (available for download at the bottom of this Tech Tip) and discuss the flow. The policy has been simplified by creating macros for the redundant portions of the authentication process: Google Authenticator token verification and the two-factor authentication processes for LDAP and Active Directory. The “Google Auth verification” macro consists of an iRule event and 5 branch rules. The number of branch rules could be reduced to just two: success and failure. This would however limit our diagnostic capabilities should we hit a snag during our deployment, so we added logging for all of the potential failure scenarios. Remember that these logs are sent to APM reporting (Web UI: Access Policy > Reports) not /var/log/ltm. APM reporting is designed to provide per-session logging in the user interface without requiring grepping of the log files. The LDAP and Active Directory macros contain the directory server authentication and query mechanisms. Directory server queries are used to retrieve user information from the directory server. In this case we can store our Google Authenticator key (shared secret) in a schema attribute to remove a dependency from our BIG-IP. We do however offer the ability to store the key in a data group as well. The main portion of the access policy is far simpler and easier to read by using macros. When the user first enters our virtual server we look at the Landing URI they are requesting. A first time request will be sent to the “normal” logon page. The user will then input their credentials along with the one-time password provided by the Google Authenticator token. If the user’s credentials and one-time password match, they are allowed access. If they fail the authentication process, we increment a counter via a table in our iRule and redirect them back to an “error” logon page. The “error” logon page notifies them that their credentials are invalid. The notification makes no reference as to which of the two factors they failed. If the user exceeds the allowed number of failures for a specified period of time, their session will be terminated and they will be unable to login for a short period of time. An authenticated user would be allowed access to secured resources for the duration of their session. Deploying Google Authenticator Token Verification This solution requires three components (one optional) for deployment: Sample access policy Google Authenticator token verification iRule Google Authenticator token generation iRule (optional) The process for deploying this solution has been divided into four sections: Configuring a AAA server Login to the Web UI of your APM From the side panel select Access Policy > AAA Servers > Active Directory, then the + next to the text to create a new AD server Within the AD creation form you’ll need to provide a Name, Domain Controller, Domain Name, Admin Username, and Admin Password When you have completed the form click Finished Copy the iRule to BIG-IP and configure options Download a copy of the Google Authenticator Token Verification iRule for APM from the DevCentral CodeShare (hint: this is much easier if you “edit” the wiki page to display the source without the line numbers and formatting) Navigate to Local Traffic > iRules > iRule List and click the + symbol Name the iRule '”google_auth_verify_apm,” then copy and paste the iRule from the CodeShare into the Definition field At the top of the iRule there are a few options that need to be defined: lockout_attempts - number of attempts a user is allowed to make prior to being locked out temporarily (default: 3 attempts) lockout_period - duration of lockout period (default: 30 seconds) ga_code_form_field - name of HTML form field used in the APM logon page, this field is define in the "Logon Page" access policy object (default: ga_code_attempt) ga_key_storage - key storage method for users' Google Authenticator shared keys, valid options include: datagroup, ldap, or ad (default: datagroup) ga_key_ldap_attr - name of LDAP schema attribute containing users' key ga_key_ad_attr - name of Active Directory schema attribute containing users' key ga_key_dg - data group containing user := key mappings Click Finished when you’ve configured the iRule options to your liking Import sample access policy From the Web UI, select Access Policy > Access Profiles > Access Profiles List In the upper right corner, click Import Download the sample policy for Two-Factor Authentication With Google Authenticator And APM and extract the .conf from ZIP archive Fill in the New Profile Name with a name of your choosing, then select Choose File, navigate to the extracted sample policy and Open Click Import to complete the import policy The sample policy’s AAA servers will likely not work in your environment, from the Access Policy List, click Edit next to the imported policy When the Visual Policy Editor opens, expand the macro (LDAP or Active Directory auth) that describe your environment Click the AD Auth object, select the AD server from the drop-down that was defined earlier in the AAA Servers step, then click Save Repeat this process for the AD Query object Assign sample policy and iRule to a virtual server From the Web UI, select Local Traffic > Virtual Servers > Virtual Server List, then the create button (+) In the New Virtual Server form, fill in the Name, Destination address, Service Port (should be HTTPS/443), next select an HTTP profile and anSSL Profile (Client). Next you’ll add a SNAT Profile if needed, an Access Profile, and finally the token verification iRule Depending on your deployment you may want to add a pool or other network connectivity resources Finally click Finished At this point you should have a function virtual server that is serving your access policy. You’ll now need to add some tokens for your users. This process is another section on its own and is listed below. Generating Software Tokens For Users In addition to the Google Authenticator Token Verification iRule for APM we also wrote a Google Authenticator Soft Token Generator iRule that will generate soft tokens for your users. The iRule can be added directly to an HTTP virtual server without a a pool and accessed directly to create tokens. There are a few available fields in the generator: account, pre-defined secret, and a QR code option. The “account” field defines how to label the soft token within the user’s mobile device and can be useful if the user has multiple soft token on the same device (I have 3 and need to label them to keep them straight). A 10-byte string can be used as a pre-defined secret for conversion to a base32-encoded key. We will advise you against using a pre-defined key because a key known to the user is something they know (as opposed to something they have) and could be potentially regenerate out-of-band thereby nullifying the benefits of two-factor authentication. Lastly, there is an option to generate a QR code by sending an HTTPS request to Google and returning the QR code as an image. While this is convenient, this could be seen as insecure since it may wind up in Google’s logs somewhere. You’ll have to decide if that is a risk you’re willing to take for the convenience it provides. Once the token has been generated, it will need to be added to a data group on the BIG-IP: Navigate to Local Traffic > iRules > Data Group Lists Select Create from the upper right-hand corner if the data group does not yet exist. If it exists, just select it from the list. Name the data group “google_auth_keys” (data group name can be changed in the beginning section of the iRule) The type of data group will be String Type the “username” into the String field and paste the “Google Authenticator key” into the Value field Click Add and the username/key pair should appear in the list as such: user := ONSWG4TFOQYTEMZU Click Finished when all your username/key pairs have been added. Your user can scan the QR code or type it into their device manually. After they scan the QR code, the account name should appear along with the TOTP for the account. The image below is how the soft token appears in the Google Authenticator iPhone application: Once again, do not let the user leave with a copy of the plain text key. Knowing their key value will negate the value of having the token in the first place. Once the key has been added to the BIG-IP, the user’s device, and they’ve tested their access, destroy any reference to the key outside the BIG-IPs data group.If you’re worried about having the keys in plain text on the BIG-IP, they can be encrypted with AES or stored off-box in LDAP and only queried via secure connection. This is beyond the scope of this article, but doable with iRules. Code Google Authenticator Token Verification iRule for APM – Documentation and code for the iRule used in this Tech Tip Google Authenticator Soft Token Generator iRule – iRule for generating soft tokens for users Sample Access Policy: Two-Factor Authentication With Google Authenticator And APM – APM access policy Reference Materials RFC 4226 - HOTP: An HMAC-Based One-Time Password Algorithm RFC 2104 - HMAC: Keyed-Hashing for Message Authentication RFC 4648 - The Base16, Base32, and Base64 Data Encodings SOL3122: Configuring the BIG-IP system to use an NTP server using the Configuration utility – Information on configuring time servers Configuration Guide for BIG-IP Access Policy Manager – The “big book” on APM configurations Configuring Authentication Using AAA Servers – Official F5 documentation for configuring AAA servers for APM Troubleshooting AAA Configurations – Extra help if you hit a snag configuring your AAA serverThe BIG-IP Application Security Manager Part 1: What is the ASM?
tl;dr - BIG-IP Application Security Manager (ASM) is a layer 7 web application firewall (WAF) available on F5's BIG-IP platforms. Introduction This article series was written a while back, but we are re-introducing it as a part of our Security Month on DevCentral. I hope you enjoy all the features of this very powerful module on the BIG-IP! This is the first of a 10-part series on the BIG-IP ASM. This module is a very powerful and effective tool for defending your applications and your peace of mind, but what is it really? And, how do you configure it correctly and efficiently? How can you take advantage of all the features it has to offer? Well, the purpose of this article series is to answer these fundamental questions. So, join me as we dive into this really cool technology called the BIG-IP ASM! The Basics The BIG-IP ASM is a Layer 7 ICSA-certified Web Application Firewall (WAF) that provides application security in traditional, virtual, and private cloud environments. It is built on TMOS...the universal product platform shared by all F5 BIG-IP products. It can run on any of the F5 Application Delivery Platforms...BIG-IP Virtual Edition, BIG-IP 2000 -> 11050, and all the VIPRION blades. It protects your applications from a myriad of network attacks including the OWASP Top 10 most critical web application security risks It is able to adapt to constantly-changing applications in very dynamic network environments It can run standalone or integrated with other modules like BIG-IP LTM, BIG-IP DNS, BIG-IP APM, etc Why A Layer 7 Firewall? Traditional network firewalls (Layer 3-4) do a great job preventing outsiders from accessing internal networks. But, these firewalls offer little to no support in the protection of application layer traffic. As David Holmes points out in his article series on F5 firewalls, threat vectors today are being introduced at all layers of the network. For example, the Slowloris and HTTP Flood attacks are Layer 7 attacks...a traditional network firewall would never stop these attacks. But, nonetheless, your application would still go down if/when it gets hit by one of these. So, it's important to defend your network with more than just a traditional Layer 3-4 firewall. That's where the ASM comes in... Some Key Features The ASM comes pre-loaded with over 2,200 attack signatures. These signatures form the foundation for the intelligence used to allow or block network traffic. If these 2,200+ signatures don't quite do the job for you, never fear...you can also build your own user-defined signatures. And, as we all know, network threats are always changing so the ASM is configured to download updated attack signatures on a regular basis. Also, the ASM offers several different policy building features. Policy building can be difficult and time consuming, especially for sites that have a large number of pages. For example, DevCentral has over 55,000 pages...who wants to hand-write the policy for that?!? No one has that kind of time. Instead, you can let the system automatically build your policy based on what it learns from your application traffic, you can manually build a policy based on what you know about your traffic, or you can use external security scanning tools (WhiteHat Sentinel, QualysGuard, IBM AppScan, Cenzic Hailstorm, etc) to build your policy. In addition, the ASM comes configured with pre-built policies for several popular applications (SharePoint, Exchange, Oracle Portal, Oracle Application, Lotus Domino, etc). Did you know? The BIG-IP ASM was the first WAF to integrate with a scanner. WhiteHat approached all the WAFs and asked about the concept of building a security policy around known vulnerabilities in the apps. All the other WAFs said "no"...F5 said "of course!" and thus began the first WAF-scanner integration. The ASM also utilizes Geolocation and IP address intelligence to allow for more sophisticated and targeted defense measures. You can allow/block users from specific locations around the world, and you can block IP addresses that have built a bad reputation on other sites around the Internet. If they were doing bad things on some other site, why let them access yours? The ASM is also built for Payment Card Industry Data Security Standard (PCI DSS) compliance. In fact, you can generate a real-time PCI compliance report at the click of a button! The ASM also comes loaded with the DataGuard feature that automatically blocks sensitive data (Credit Card numbers, SSN, etc) from being displayed in a browser. In addition to the PCI reports, you can generate on-demand charts and graphs that show just about every detail of traffic statistics that you need. The following screenshot is a representative sample of some real traffic that I pulled off a site that uses the ASM. Pretty powerful stuff! I could go on for days here...and I know you probably want me to, but I'll wrap it up for this first article. I hope you can see the value of the ASM both as a technical solution in the defense of your network and also a critical asset in the long-term strategic vision of your company. So, if you already have an ASM and want to know more about it or if you don't have one yet and want to see what you're missing, come on back for the next article where I will talk about the cool features of policy building. What is the BIG-IP ASM? Policy Building The Importance of File Types, Parameters, and URLs Attack Signatures XML Security IP Address Intelligence and Whitelisting Geolocation Data Guard Username and Session Awareness Tracking Event Logging
iRules Event Order
iRules is an event driven language. This has been discussed before, but to recap briefly, here’s what “Event Driven” means in iRules terms: iRules code is written inside event blocks. Those event blocks translate to times within the life-cycle of a connection to your LTM. By putting your code inside a given event block you are ensuring that it executes at a particular point in that transaction. I.E. HTTP_REQUEST code is executed once a request has been received, not before, so you’re safe to look for HTTP header info. SERVER_CONNECTED however isn’t fired until all the client side processing has been done and a load balancing decision is made, but before the actual data is sent to the chosen system. In this way we ensure granularity in the control of when and how your code is executed to allow you the absolute most control possible. It also allows for things to be highly efficient as we only have to execute the needed code each time, not the entire script. So now that we know what “Event Driven” means and how to use events to execute code precisely where we want to within the context of a connection, that leaves two burning questions. What events can I choose from? That is answered handily by the “Events” page in the iRules wiki. The other is: When does each event fire? I.E – what’s the overall order of events for a given connection? This has been something that’s a little harder to nail down as it takes a little bit of disclaimer work since not all events fire for every connection because some are based on given profiles, not to mention iRules is constantly changing. Keeping that in mind, though, I’ve put together a list of events in the order that they execute, checked it twice…then sent it off for PD approval (hey, I’m not an idiot). The below list has gotten the stamp of approval and I’m quite happy to finally get a documented order online as there have been many requests for this. Events are processed in a linear fashion so all CLIENT_ACCEPTED events in all iRules finish processing before the first HTTP_REQUEST event can fire. The linear order of this list is representative of that. Each event will not fire until all events above it have completed. Also, all events within one line, separated by slashes (/) execute at effectively the same time as far as the context of a connection is concerned. Please note that some of the events below are only executed under certain circumstances. For instance the AUTH_RESULT event only occurs if an AUTH command (such as AUTH::authenticate) completes to return results. iRules Event Order: RULE_INIT This is a global iRule event. It occurs once when the iRule is loaded into memory and does not continue to be processed for each subsequent request. Client Request Events - These events occur between the time the client connects to the LTM and the time the LTM makes a load balancing decision. At this point it has finished client data processing and is ready to connect to the chosen server but has not yet sent the data. These events are executed in a client-side context, meaning they behave as if you've used the clientside command with each of them. This means that local_addr type commands behave with the client in mind. This is where you have the opportunity to change the information a user is sending in before it makes it to the server for processing. URI re-writing, authentication and encryption offloading or inspection, server impersonation (acting like you’re a server to dig deeper into the transaction) – it all happens here. CLIENT_ACCEPTED CLIENTSSL_HANDSHAKE CLIENTSSL_CLIENTCERT HTTP_REQUEST / CACHE_REQUEST / RTSP_REQUEST / SIP_REQUEST / HTTP_CLASS_FAILED / HTTP_CLASS_SELECTED STREAM_MATCHED CACHE_UPDATE CLIENT_DATA / RTSP_REQUEST_DATA / HTTP_REQUEST_DATA – Only occur when collected data arrives AUTH_RESULT / AUTH_WANTCREDENTIAL – Only occur when authentication commands return LB_SELECTED / LB_FAILED / PERSIST_DOWN Server Request Events - These events take place after client request processing has finished, a destination has been chosen by the LTM, and the connection to the server is initiated. They happen before the client request is actually sent to the server. This is the end of the request process, which is followed by the first Server Response event. These events are executed in a server-side context. Much like the opposite of the above client-side events, these behave as if you’ve used the serverside command with each of them. SERVER_CONNECTED SERVER_SSL_HANDSHAKE HTTP_REQUEST_SEND / SIP_REQUEST_SEND Server Response Events - These events are triggered after the request has been sent to the server, the server has processed the request and the LTM receives a response from the server. These events are where you can access content generated by the server before it gets sent back to the client. Scrubbing out credit card information, server response manipulation, etc. – this is the place for it. CACHE_RESPONSE HTTP_RESPONSE / RTSP_RESPONSE / SIP_RESPONSE STREAM_MATCHED HTTP_RESPONSE_CONTINUE HTTP_RESPONSE_DATA / SERVER_DATA / RTSP_RESPONSE_DATA – Only occur when collected data arrives Disconnect Events - These are the events that represent the termination of a connection after all processing is completed. SERVER_CLOSED CLIENT_CLOSED This list is representative of iRules as they sit today. Keep in mind that the iRules language is continually evolving and changing, which may impact this list as well. I’ll do my best to keep it updated, because I think it’s a useful resource. Get the Flash Player to see this player. 20090331-iRulesEventOrder.mp3SSL Profiles Part 2: Certificates
This is part 2 in a series of tech tips on the F5 BIG-IP LTM SSL profiles. SSL Overview and Handshake SSL Certificates Certificate Chain Implementation Cipher Suites SSL Options SSL Renegotiation Server Name Indication Client Authentication Server Authentication All the "Little" Options In part 1, we covered the basics of the TLS handshakes and the context of the client and server ssl profiles. This time we’ll take a look at certficates. What is an SSL Certificate? The certificate is nothing more than a document containing the public key the client will use to compute key material and information about expiration, common and distinguished names, contact information, etc. A certificate can be modified until it is signed. This can be done to itself, which would be a self-signed certificate (all root certificates are self-signed) or a certificate can be signed by a certificate authority (CA). The certificate below in Figure 1 might look familiar. I created this certificate from a private certificate authority I set up when looking at HTTP Strict Transport Security a couple months back. That begs another question: What is a certificate authority? SSL Certificate Authorities The CA is one component within the larger public key infrastructure (PKI). CA’s serve as a trusted 3rd party between server and client, issuing (and revoking) the certificates. The server and optionally the client (owners) request a certificate that is signed by the CA. Both client and server then host the CA’s root and/or intermediate certificates. As shown above, you can be your own CA, but this increases the management burden as you now need to distribute the root/intermediate certificates to your clients in order to gain their trust of your certificates. By using a commercial CA, chances are good their certificates are already in your client trusted stores and thus your certificates will be trusted by the clients. In a corporate network, however, you might want to secure your traffic without forking over the cash for dozens (hundreds?) of certificates. In this case, an internal CA makes a lot of sense, and can be managed somewhat painlessly with active directory or the like. Figure 2 shows the testco CA as installed in my firefox browser. So any certificates I sign with the testco CA will be trusted by my firefox browser, eliminating all the extra clicking I’d need to do for self-signed certificates. Intermediate CAs and the Certificate Chain Best practices with PKI involve creating a number of subordinate CAs. With the testco CA I created, I installed this root certificate into my trust store and I signed the certificate I used for www.testco.com with that CA, and all is well. However, most of the time certificates are signed by Leaf CAs, or subordinate CAs that are created specifically for the purpose of creating certificates for servers, systems, etc. If you reference Figure 1, you’ll notice the issuer section where it informs the client of the certificate signer. In the event this is not the root CA for my www.testco.com, the authentication will fail, because the issuer is not trusted. These trust relationships can chain so that there are multiple levels of trust down from the root certificate to a depth of 10 (openSSL). For example, take the certificate chain in Figure 3. When the client receives the certificate from www.testco.com, it will have a signer (issuer) of Testco Dev CA. My browser doesn’t trust this CA, so it must then validate its signer, which is the Testco CA (root). My browser does trust this CA, so all is good. Now, if I added this intermediate CA to my trust store, validation would stop at that level and would not need to climb to the root CA. This is how most commercial providers work. You get the intermediate CAs from most publishers when you install your system OS. When you connect to an SSL-enabled site, the certificate arrives at the client with it’s signer, and then the certificate chain is climbed until (if) it arrives at a level of trust. In addition to the usefulness for the ssl profiles, this information is quite handy if you will be installing 3rd party certificates (read: not self-signed) for GTM (Chapter 12 in the Implementations Guide) as certificate depth plays a big role in configuration. Finally, IBM has a great graphic on the chain of trust certificate/signature verification process. Types of Certificates Remember from part 1 where I said that you couldn’t host multiple domains on a single IP without the TLS SNI option? Well, that’s not entirely true. It is true of standard SSL certificates, but certificates have changed over the years to workaround some of these limitations. There are several options when considering certificates. Domain Validated – no company background checking, just a simple comparison to the domain whois information before issuing. $ Organizationally Validated – company background is vetted, site ip/name is validated. $$ Extended Validation – industry standard certificate guidelines. This will turn the browser locator bar green and publish company name as well. Introduced in 2007. $$$ Unified Communications – this certificate takes advantage of the Subject Alternative Name field, so you can secure multiple (specific) domain names on one certificate. Microsoft Exchange is a popular application requiring a UC Certificate, as it supports several names owa.site.com, autodiscover.site.com, cas1.site.com, etc. $$$ Wildcard Certificate – this certificate supports any number of subdomains based on *.site.com, where your subdomain would replace the *. It doesn’t, however, support site.com, so for those lazy users (me) who hate typing the leading www. before hitting enter, the wildcard certificate will not cover that scenario. $$$ Wildcard Plus – This is a combination UCC/Wildcard Certificate in that it will protect at the site.com, *.site.com, and several specified lower-subdomain levels as well. Most modern browsers support the above options, but there are still some questions on the compatibility with the wildcard plus certificates, and some mobile devices have issues with wildcard certificates in general. Make sure you thoroughly vet out your userbase before deciding on a solution. Certificate Formats There are several ways the X.509 certificate structure is packaged. Different platforms require different formats. The LTM uses PEM format. Most of the commercial CAs issue certificates in PEM format. If you are using an internal Windows CA, most likely the certificate, the format is PKCS#7/#12, and prior to version 10.1, needed to be converted to PEM prior to import. The formats used are: PEM – base64 encoded ASCII file with BEGIN CERTIFICATE and END CERTIFICATE statements and can contain the private key DER – binary form of the certificate PKCS#7 – also a base64 encoded ASCII file, though with BEGIN PKCS7 and END PKCS7 statements. Can not contain the private key. PKCS#12 – binary form of the certificate, any intermediates, and the private key. Converting is fairly easy and can be done at the cli of the LTM with the openssl tool. DER to PEM openssl x509 -inform der -in <certname>.der -out <certname>.pem PKCS#7 to PEM openssl pkcs7 -print_certs -in <certname>.p7b -out <certname>.pem PKCS#12 to PEM openssl pkcs12 -in <certname>.pfx -out <certname>.pem -nodes Conclusion There is so much more depth to certificates that we could cover, but hopefully this overview has been informative and provides the foundation necessary for part 3, where we’ll start diving into the profiles themselves.SSL Profiles Part 6: SSL Renegotiation
This is the sixth article in a series of Tech Tips that highlight SSL Profiles on the BIG-IP LTM. SSL Overview and Handshake SSL Certificates Certificate Chain Implementation Cipher Suites SSL Options SSL Renegotiation Server Name Indication Client Authentication Server Authentication All the "Little" Options This article will discuss SSL renegotiation, some OpenSSL features, some of the attack vectors against SSL renegotiation, and then how the BIG-IP is configured to handle this feature. What Is SSL Renegotiation? Before we get into the details of SSL renegotiation, let me start by outlining a quick scenario. Let's say a user visits an online shopping site that is SSL encrypted. Initially, the user shops around anonymously, but after some time on the site, the user decides to log in and make a purchase. The user will need to authenticate to the site before making the purchase, so the SSL connection will need to be adjusted to allow the authentication. Ideally, all the information the user collected as an anonymous visitor will be maintained and protected after the status change to an authenticated customer. This basic (yet frequent) scenario outlines the need for SSL renegotiation. The figure below shows a representation of this scenario and shows that a new SSL session must be established in order to authenticate the user. This new session completes the full handshake, but it does it using the security of the already-established SSL connection. SSL renegotiation messages (including types of ciphers and encryption keys) are encrypted and then sent over the existing SSL connection. This feature is nice because it can create a secure SSL session based on the fact that a secure connection is already established. SSL renegotiation is useful in several situations where an ordinary SSL session is already established. Here are a few examples: Client authentication is required A different set of encryption and decryption keys are needed A different set of encryption and hashing algorithms are used The client or the server can request renegotiation at any time. For the client to request renegotiation, the client sends a "Client Hello" message in the already-established encrypted channel and the server responds with a "Server Hello" and then the negotiation follows the normal handshake process. The server can initiate the renegotiation by sending the client a Hello Request message. When the client receives the request, the client sends the "Client Hello" message and the handshake process takes place. One quick note of clarification: the client and server can also complete a session resumption vice a session renegotiation. A session resumption basically resumes a previous session (using a previous session ID), and it saves the client and server the computing work of generating new encryption keys. Renegotiation is a process by which the full handshake process takes place over an already existing SSL connection. A Fly In The Ointment... Life would be much easier if the bad guys weren't out there doing their thing, but I guess it would also be less interesting. Nonetheless, some pretty smart guys were working with SSL renegotiation back in the old days (circa 2009) and found out that they could exploit a vulnerability in its design. The Common Vulnerabilities and Exposures (CVE) database outlines the details behind this SSL renegotiation vulnerability in CVE-2009-3555. You can read the details for yourself, but here's what the CVE basically says: TLS and SSLv3 do not properly associate renegotiation handshakes with an existing connection, and this allows attackers to insert data into existing sessions by sending an unauthenticated request that is processed retroactively by a server in a post-renegotiation context related to a "plaintext injection" attack. Essentially, this means that bad guys can hijack the SSL session and start using your "secure" communications on your behalf. Houston, we have a problem. Fortunately, the good folks at the Internet Engineering Task Force (IETF) found out about this problem, and they responded with a little magic of their own. It's outlined in Request for Comments (RFC) 5746. Here's what they had to say: "Secure Socket Layer (SSL) and Transport Layer Security (TLS) renegotiation are vulnerable to an attack in which the attacker forms a TLS connection with the target server, injects content of his choice, and then splices in a new TLS connection from a client. The server treats the client's initial TLS handshake as a renegotiation and thus believes that the initial data transmitted by the attacker is from the same entity as the subsequent client data. This specification defines a TLS extension to cryptographically tie renegotiations to the TLS connections they are being performed over, thus preventing this attack." Well, take that bad guys!! A Few Notes About OpenSSL Now that we have a basic understanding of RFC 5746, let's spend some time on OpenSSL and how it relates to F5's BIG-IP. After all, how can you have an article on SSL and not talk about OpenSSL? This stuff is free (Apache style) and it's awesome! The BIG-IP supports the popular OpenSSL toolkit, and it even has a built-in OpenSSL utility. It's important to understand how OpenSSL handles the behavior of clients and servers regarding the feature of SSL renegotiation. OpenSSL 0.9.8m and later always attempts to use secure renegotiation as described in RFC 5746. On the BIG-IP side of the house, versions prior to 10.2.3 do not support this RFC. However, beginning in version 10.2.3 and 11.x, the BIG-IP SSL profiles do support it. So, pause for a few minutes from reading this article and upgrade your BIG-IP! Patching When describing SSL implementations, systems that support secure renegotiation (per RFC 5746) are referred to as "patched" and systems that do not support secure renegotiation are referred to as "unpatched." If a client and server are both patched, connections and renegotiation are always permitted by OpenSSL implementations. If a server is patched but the client is unpatched, the initial connection will succeed but client renegotiation will be denied by the server with a no_renegotiation warning alert if TLS v1.0 is used or a fatal handshake_failure alert if SSL v3.0 is used. If the patched server attempts to renegotiate with the unpatched client, a fatal handshake_failure alert is sent. This is because the server code may be unaware of the unpatched nature of the client. Here's what happens if a client is patched but the server is unpatched. If the option "SSL_OP_LEGACY_SERVER_CONNECT" or "SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION" is set then initial connections as well as all renegotiations between patched clients and unpatched servers will succeed. However, if neither option is set then initial connections to unpatched servers will fail. (note: the option "SSL_OP_LEGACY_SERVER_CONNECT" is currently set by default, but as more servers become patched, this option will not be set by default in future versions of OpenSSL). Renegotiation Attacks Speaking of highly broken...let's spend a little time on SSL renegotiation attacks before we dive into the BIG-IP configurations. Here are two fairly well known attacks that are targeted at the SSL renegotiation feature. And, guess what? I'm starting with the..."Man in the Middle" (sung to Michael Jackson's hit song) Man In The Middle Since we discussed RFC 5746 earlier, why not go over the details of what it fixed? As we've discussed, SSL allows both servers and clients to initiate a complete renegotiation of the encryption parameters used for SSL connections. However, the design of the initial handshake and the renegotiation process had a gap that could allow an attacker to send a “Client Hello” and insert content into a client’s SSL session and then intercept secure communications between the server and the client. The following illustration shows how a bad guy could exploit the Man in the Middle vulnerability. In this example, the client sends a "Client Hello" to start an SSL session with his bank's server. The bad guy temporarily blocks the "Client Hello" and then creates an SSL connection of his own with the server. After the SSL session is created between the bad guy and the bank server, the bad guy asks for a money transfer. The bank server needs to authenticate the user, so it requests a renegotiation by sending a "Hello Request" to the bad guy...which is exactly what he wanted. This is where the bad guy sends the client's initial "Client Hello" to the server. The client thinks he is beginning a new SSL session, and the server thinks an SSL renegotiation has just taken place. But, nonetheless, all parties are happy with everything...especially the bad guy! See, now you know why you should be using a "patched" system! Denial of Service Last year, the IETF posted a paper that outlines a Denial of Service (DoS) attack against a server using the SSL renegotiation feature. The DoS attack is based on the fact that an SSL handshake requires up to 10 times more processing power on the server than on the client. Therein lies the problem...and the ability to exploit it! When SSL renegotiation is enabled on the server, a user is allowed to send a renegotiation request any time he wants...and this request initiates a new handshake. Since it takes much fewer resources for a client to perform a handshake than a server, the client can request multiple handshakes per second and cause a DoS on the server side SSL interface. Therefore, if a malicious user requests multiple renegotiation requests it will exhaust the server’s resources and not allow any other user to establish a connection. This attack is different than a Distributed Denial of Service (DDoS) as it does not require a large amounts of network volume to exhaust the network connection. Instead, it exhausts the server resources from a single host requiring only a single TCP/IP socket. A single server can perform between 150-300 handshakes per second while a single client can request up to 1,000 handshakes per second. By the way, Openssl doesn't consider this DoS exploit an actual vulnerability (which is why they haven't done anything about it in their latest releases). Their response is that this exploit is a way of DoS'ing a server by requesting lots of expensive crypto operations. Any app that allows an operation like SSL renegotiation to an untrusted host is subject to resource exhaustion. They would say the correct answer is to restrict hosts if this is an issue. Note also that if the OS firewall is not enabled, any OS is subject to a DoS through resource exhaustion, even if it's just TCP port exhaustion. For more information on a great SSL renegotiation DoS countermeasure, see this DevCentral article. David Holmes and Jason Rahm teamed up to talk about the DoS vulnerability, and then they wrote an iRule that elegantly defeats the attack...really cool and useful stuff!! In addition, here's a quick video clip that talks about the same issue...F5 knocks it out of the park with this iRule stuff! F5 Security Vignette: SSL Renegotiation BIG-IP Configuration Now that we've talked through this SSL renegotiation thing, let's finish up with the features of the BIG-IP and how it handles SSL renegotiation. The following screenshot shows the different options for SSL renegotiation on the BIG-IP. You can find this screen by navigating to Local Traffic > Profiles > SSL > Client | Server. Notice that you can either enable or disable SSL renegotiation altogether. By default, it is enabled. Renegotiation controls (on a per-connection basis) how the BIG-IP responds to mid-stream SSL reconnection requests. When enabled, the system processes mid-stream SSL renegotiation requests. When disabled, the system terminates the connection, or ignores the request, depending on system configuration. The Renegotiate Period setting specifies the number of seconds from the initial connect time that the system renegotiates an SSL session. The options are "Specify" (in seconds) and "Indefinite" with "Indefinite" being the default. The "Indefinite" setting means that you never want the system to force an SSL renegotiation. The system will renegotiate the session after the specified period of time...that's why the "Indefinite" setting never forces a renegotiation. For example, setting the renegotiate period to 3600 seconds triggers session renegotiation at least once an hour. The Renegotiate Size setting forces the BIG-IP to renegotiate an SSL session after a specified number of megabytes of application data have been transmitted over the secure channel. The values for this setting are "Indefinite" and "Specify" (in megabytes) with "Indefinite" being the default. This setting follows the same premise as the Renegotiate Period but it uses data size to determine when it will force a renegotiation vice a period of time. The Renegotiate Max Record Delay setting forces the BIG-IP to terminate an SSL session after receiving the specified maximum number of SSL records. The number of records are counted while the BIG-IP system waits for the client to initiate a renegotiation. If the BIG-IP system receives more than the maximum number of SSL records, it closes the connection. The values for this setting are "Indefinite" and "Specify" (number of records). The default setting is "Specify" 10 records. Secure Renegotiation is a fairly new feature in the BIG-IP (not available prior to v10.2.3). This setting handles the RFC 5746 problem, and it allows the user to specify the method of secure renegotiation for SSL connections. The values for this setting are "Request," "Require," and "Require Strict" with "Require" being the default value for the Client-side SSL profile. The default value for the Server-side SSL profile depends on the BIG-IP version: in v10.2.3 and v10.2.4, the default value for the Server-side SSL profile is "Require" and the default value in v11.x is "Require Strict." The "Request" value specifies that the system simply requests secure renegotiation of SSL connections. The "Require" value specifies that the system requires secure renegotiation of SSL connections. In this mode, the system permits initial SSL handshakes from clients, but terminates renegotiations from unpatched clients. The "Require Strict" value specifies that the system requires strict secure renegotiation of SSL connections. In this mode, the system does not accept new SSL connections from unpatched clients. Within the context of the Server-side SSL profile, there is no behavioral difference between "Require" and "Require Strict." In either mode, initial SSL connections from the BIG-IP to unpatched servers will fail. Conclusion Well, I think that about does it for SSL Renegotiation. Come back for more great SSL discussion in our next article that will feature Server Name Indication (SNI). As always, if you have any questions (about SSL, iRules, or any other F5 technology), feel free to comment here or contact the DevCentral team directly. See you soon!SSL Profiles Part 5: SSL Options
Several months ago (ok, maybe lots and lots of months ago), Jason Rahmwrote a great series of Tech Tips that cover the BIG-IP LTM SSL profiles. SSL Overview and Handshake SSL Certificates Certificate Chain Implementation Cipher Suites SSL Options SSL Renegotiation Server Name Indication Client Authentication Server Authentication All the "Little" Options I'd like to take the baton and run a little further with the work he started. This next SSL profile article will dive into the specifics of the SSL Options that are offered in the BIG-IP LTM. Why All The Options? The LTM provides options for both client-side SSL and server-side SSL. So, why is it necessary to offer all these options? As you know, Internet browsers, operating systems, encryption algorithms, etc. sometimes have a hard time with compatibility and bugs. What!?!? Well, this is certainly true for SSL implementation. The LTM allows the behavior of the SSL library to be changed by setting several options. In order to keep traffic flowing as smoothly and efficiently as possible, the LTM is built with several OpenSSL-supported options that allow you to configure workarounds for defects and other unique settings. You can enable these workarounds and options as settings of an individual Client-side or Server-side SSL profile. This article will explore the details of what these options are and what they all mean. The following screenshot shows the location where you can enable or disable the various SSL options (navigate to Local Traffic > Profiles > SSL > Client | Server). The default value for the Options setting is Options List. Keeping this default value enables only one option: Don't insert empty fragments. As a reminder, when you enable the BIG-IP system to manage Client-side SSL traffic, the LTM terminates incoming SSL connections by decrypting the client request. The LTM then sends the request, in clear text, to a target server. Next, the LTM retrieves a clear-text response from the server and encrypts the request before sending the response back to the client. When you enable management of Server-side SSL traffic, the LTM re-encrypts a decrypted client request before sending it on to a target server. Now, let's check out the Client-side and Server-side options... Client-side Options The following is a complete list and description of the SSL Client-side options that the LTM offers. It's important for each admin to enable/disable these options based on their specific network needs. Netscape reuse cipher change bug workaround: This option handles a defect within Netscape-Enterprise Server 2.0.1. This defect only appears when connecting through SSLv2/v3 then reconnecting through SSLv3. If/when you connect this way, the cipher list changes. Initially, a connection is established with the RC4-MD5 cipher list. If the connection is resumed, it switches to the DES-CBC3-SHA cipher list. As a workaround, you can attempt to connect with a cipher list of DES-CBC-SHA:RC4-MD5 and so forth. Each new connection uses the RC4-MD5 cipher list, but any reconnection attempts use the DES-CBC-SHA cipher list. So when reconnecting, Netscape-Enterprise Server 2.0.1 always uses the first cipher in the cipher list. (Important note: as of OpenSSL 0.9.8q and 1.0.0c, this option has no effect) Microsoft big SSLv3 buffer: Some Microsoft applications (old versions of Internet Explorer) use SSLv3 packets that are greater than 18k+5 bytes. This is prohibited by the SSLv3 specification. The big SSLv3 buffer option enables a workaround for communicating with these older Microsoft applications. Microsoft IE SSLv2 RSA padding: Similar to the SSLv3 buffer, this option enables a workaround for communicating with older Microsoft IE versions that use non-standard RSA key padding. SSLeay 080 client DH bug workaround: This option enables a workaround for communicating with older SSLeay-based applications (version 0.8.0) that specify an incorrect Diffie-Hellman public key length. TLS D5 bug workaround: This option is a workaround for communicating with older TLSv1-enabled applications that specify an incorrect encrypted RSA key length. TLS block padding bug workaround: This option enables a workaround for communicating with older TLSv1-enabled applications that use incorrect block padding. No session resumption on renegotiation: This option specifies that, when the LTM performs renegotiation as an SSL server, it always starts a new session (e.g. session resumption requests are only accepted in the initial handshake). Single DH use: This option creates a new key when using ephemeral (temporary) Diffie-Hellman parameters. This option is necessary if you want to prevent small subgroup attacks when the Diffie-Hellman parameters were not generated using strong primes (i.e. when using DSA-parameters). Remember, the strength of the Diffie-Hellman key agreement protocol depends on the strength of the prime number used to generate the shared secret key. If strong primes were used, you don't have to generate a new Diffie-Hellman key during each handshake, but it's highly recommend that you do. You should enable the Single DH use option whenever ephemeral Diffie-Hellman parameters are used. Update note: The Single DH use can be effective when mitigating the Logjam vulnerability. See this article for more information. Ephemeral RSA: This option uses ephemeral (temporary) RSA keys during RSA operations (for more information on the RSA encryption algorithm, see the References section below). This is done when an RSA key can only be used for signature operations (more specifically under export ciphers with restricted RSA key length). By setting this option, the LTM always uses ephemeral RSA keys. This option breaks compatibility with the SSL/TLS specifications and can lead to interoperability problems with clients, so it's not recommended. Use it if you must, but if you can avoid it, it's recommended that you use ciphers with ephemeral Diffie-Hellman (EDH) key exchange instead. Cipher server preference: When the BIG-IP system chooses a cipher, this option uses the server's preferences instead of the client preferences. When this option is not set, the SSL server always follows the clients preferences. When this option is set, the SSLv3/TLSv1 server chooses by using its own preferences. For SSLv2, the server sends its list of preferences to the client, and the client always chooses the cipher. TLS rollback bug workaround: This option disables version rollback attack detection. During the client key exchange, the client must send the same information about acceptable SSL/TLS protocol levels as it sends during the first hello. Some clients violate this rule by adapting to the server's answer. For example, the client sends an SSLv2 hello and accepts up to SSLv3.1 (TLSv1), but the server only understands up to SSLv3. In this case, the client must still use the same SSLv3.1 (TLSv1) announcement. Some clients step down to SSLv3 with respect to the server's answer and violate the version rollback protection. No SSLv1 This options disallows the use of the SSLv1 protocol. No SSLv2 This options disallows the use of the SSLv2 protocol. No SSLv3 This options disallows the use of the SSLv3protocol. No TLSv1: This options disallows the use of the TLSv1 protocol. PKCS1 check 1: This debugging option deliberately manipulates the PKCS1 padding used by SSL clients in an attempt to detect SSL server vulnerabilities. The SSLv3 specifications require that a modified PKCS1 padding be used in the RSA encryption operation to facilitate detection of rollback attacks against SSLv3 capable browsers when using the compatibility mode. Microsoft clients do not check for the modified PKCS1 packets, so they are vulnerable to this type of attack. This option is not recommended for normal use. The system ignores this option for client-side SSL processing. PKCS1 check 2: This debugging option deliberately manipulates the PKCS1 padding used by SSL clients in an attempt to detect particular SSL server vulnerabilities. This option is not recommended for normal use. The system ignores this option for client-side SSL processing. Netscape CA DN bug workaround: This option handles a defect regarding system instability. The system crashes or hangs if the following conditions are met: 1) the system accepts a Netscape browser connection, 2) the system demands a client certificate, 3) the system has a non-self-signed CA that does not have its CA in Netscape, and 4) the browser has a certificate. This option is in place to ensure the system does not crash or hang. Netscape demo cipher change bug workaround: This option deliberately manipulates the SSL server session resumption behavior to mimic that of certain Netscape servers (see the Netscape reuse cipher change bug workaround description). This option is not recommended for normal use, and it is ignored for Server-side SSL processing. Don't insert empty fragments: This option disables a countermeasure against a SSL 3.0/TLS 1.0 protocol vulnerability affecting Cipher Block Chaining (CBC) ciphers. These ciphers cannot be handled by certain broken SSL implementations. This option has no effect for connections using other ciphers. This is the default value for the Enabled Options list (see screenshot above). Server-side Options The following is a complete list of the SSL Server-side Options: Microsoft session ID bug: This option handles the following problem with Microsoft session ID: When using SSLv2, if session-id reuse is performed, the session-id passed back in the server-finished message is different from the one decided upon. Netscape challenge bug workaround: This option handles the following Netscape challenge problem: When Netscape-Commerce v1.12 is using SSLv2, it accepts a 32-byte challenge but then appears to only use 16 bytes when generating the encryption keys. Using 16 bytes is acceptable per the encryption standard, but it should be allowed to use 32 bytes for generating the key. According to the SSLv3 specification, you should use 32 bytes for the challenge when operating in SSLv2/3 compatibility mode. But, since the 32 byte key generation breaks this server, 16 bytes is the recommended way to go. SSLRef2 reuse cert type bug workaround: This option handles the following SSL re-use certificate type problem: If R_SSL_reuse() is true, then the CERTIFICATE-TYPE, CERTIFICATE-LENGTH and CIPHER-SPECS-LENGTH fields should be 0. Some Netscape web servers do not implement this correctly. Microsoft big SSLv3 buffer: Some Microsoft applications (old versions of Internet Explorer) use SSLv3 packets that are greater than 18k+5 bytes. This is prohibited by the SSLv3 specification. The big SSLv3 buffer option enables a workaround for communicating with these older Microsoft applications. TLS block padding bug workaround: This option enables a workaround for communicating with older TLSv1-enabled applications that use incorrect block padding Passive close: This option either enables or disables the All Bugfixes Enabled option. Single DH use: This option creates a new key when using ephemeral (temporary) Diffie-Hellman parameters. This option is necessary if you want to prevent small subgroup attacks when the Diffie-Hellman parameters were not generated using strong primes (i.e. when using DSA-parameters). Remember, the strength of the Diffie-Hellman key agreement protocol depends on the strength of the prime number used to generate the shared secret key. If strong primes were used, you don't have to generate a new Diffie-Hellman key during each handshake, but it's highly recommend that you do. You should enable the Single DH use option whenever ephemeral Diffie-Hellman parameters are used. Update note:TheSingle DH usecan be effective when mitigating the Logjam vulnerability. Seethis articlefor more information. Cipher server preference: When the BIG-IP system chooses a cipher, this option uses the server's preferences instead of the client preferences. When this option is not set, the SSL server always follows the clients preferences. When this option is set, the SSLv3/TLSv1 server chooses by using its own preferences. For SSLv2, the server sends its list of preferences to the client, and the client always chooses the cipher. No SSLv1 This options disallows the use of the SSLv1 protocol. No SSLv2 This options disallows the use of the SSLv2 protocol. No SSLv3 This options disallows the use of the SSLv3protocol. No TLSv1: This options disallows the use of the TLSv1 protocol. PKCS1 check 1: This debugging option deliberately manipulates the PKCS1 padding used by SSL clients in an attempt to detect SSL server vulnerabilities. The SSLv3 specifications require that a modified PKCS1 padding be used in the RSA encryption operation to facilitate detection of rollback attacks against SSLv3 capable browsers when using the compatibility mode. Microsoft clients do not check for the modified PKCS1 packets, so they are vulnerable to this type of attack. This option is not recommended for normal use. The system ignores this option for client-side SSL processing. PKCS1 check 2: This debugging option deliberately manipulates the PKCS1 padding used by SSL clients in an attempt to detect particular SSL server vulnerabilities. This option is not recommended for normal use. The system ignores this option for client-side SSL processing. Don't insert empty fragments: This option disables a countermeasure against a SSL 3.0/TLS 1.0 protocol vulnerability affecting Cipher Block Chaining (CBC) ciphers. These ciphers cannot be handled by certain broken SSL implementations. This option has no effect for connections using other ciphers. This is the default value for the Enabled Options list (see screenshot above). Conclusion When configuring protocol versions, you must ensure that the protocol versions configured for the BIG-IP system match those of the systems peer. So, protocol versions specified in the Client-side SSL profile must match those of the client, and protocol versions specified in the Server-side SSL profile must match those of the server. Also, as stated earlier, be sure to test each option on your network before you fully implement any/all of them. But, once you know which options to employ, take full advantage of the LTM's ability to provide these great features! Well, that does it for SSL Options. The next article in this series will focus on SSL renegotiation and some of the attacks that are associated with it. References I used several sources when researching this article...here's a list of some that you might enjoy referencing: AskF5 SSL Profiles Document: http://support.f5.com/kb/en-us/products/big-ip_ltm/manuals/product/ltm_concepts_11_0_0/ltm_ssl_profiles.html?sr=29775670 OpenSSL SSL_CTX_set_options: http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html#DESCRIPTION SSL implementation bugs: http://www.dcs.ed.ac.uk/home/crypto/SSLeay/vendor-bugs.html Diffie Hellman encryption protocol: http://www.rsa.com/rsalabs/node.asp?id=2248 RSA encryption documents (to include PKCS #1): http://www.rsa.com/rsalabs/node.asp?id=2422 Cipher Block Chaining description: http://www.rsa.com/rsalabs/node.asp?id=2171 (updated May, 2015) Remediating Logjam: https://devcentral.f5.com/s/articles/remediating-logjam-an-irule-countermeasureSSL Profiles Part 3: Certificate Chain Implementation
This is part 3 in a series of articles covering the BIG-IP LTM SSL profiles. SSL Overview and Handshake SSL Certificates Certificate Chain Implementation Cipher Suites SSL Options SSL Renegotiation Server Name Indication Client Authentication Server Authentication All the "Little" Options Introduction Now that we have some foundational information in place, we’ll put some of the certificate knowledge into practice as we build our first SSL profile. Recall from part 2 the certificate chain and the layers of trust involved. For our configuration (see Figure 1), I’ve built a root CA with two layers of subordinate CAs prior to actually signing a certificate for test site devcentral.f5test.com. So after much openssl cli typing (or if you are lazy like me, using TinyCA2), I end up with four files that will assist in building out our first profile: Root Certificate (dcrootCA-cacert.pem) Sub CA 1 (dcsubCA1-cacert.pem) Sub CA 2 (dcsubCA2-cacert.pem) Server Certificate (dctest.p12) Importing Certificates & Constructing the Certificate Chain The goal here is to install the root certificate on the client, and then chain the two subordinate CA certificates with the root CA for use on the profile with the server certificate. First, we’ll import the server certificate as shown in Figures 2 and 3. Beginning in version 10.1, you can import a PKCS package that includes server/key so I exported from TinyCA2 that way to save me a step. Prior to 10.1, you’ll need PEM. Now that the server certificate is in place, I can upload the CA certificates and concatenate them into a certificate chain. [root@golgotha:Active] ssl.crt # cat dcsubCA1-cacert.pem dcsubCA2-cacert.pem dcrootCA-cacert.pem > /config/ssl/ssl.crt/dctestchain.crt Next, verify that the certificate chain establishes the trust relationships for the server certificate: [root@golgotha:Active] ssl.crt # openssl verify -CAfile dctestchain.crt devcentral.f5test.com.crt devcentral.f5test.com.crt: OK On the client side, my windows 7 pc doesn’t recognize pem format, so I convert from pem to crt and scp it from the LTM and install it into my trusted root certificate authorities store: [root@golgotha:Active] tmp # openssl x509 -in dcrootCA-cacert.pem -outform DER -out dcrootCA.crt A Beginning ClientSSL Profile There are plenty of settings in the profile that we’ll get to eventually, but for our first profile, we’re going to simply reference our certificate, key, and chain. This is shown in Figure 4. Built from the clientssl default profile, we’ll name it the common name of our server, devcentral.f5test.com, then match the appropriate certificate and key we imported, and finally, we’ll need to switch to the advanced configuration to get to the chain option, where we’ll select the dctestchain certificate. After saving the profile, apply it against a virtual server and create a host entry in your hosts file to test everything out. If the trust is correct, there will be no certificate warning, as is the case shown in Figure 5 below. If we make one change to the clientssl profile and disable the certificate chain, you can see that it breaks the trust relationship (Figure 6) Gotchas There are a couple solutions on MyF5that might impact your use of certificate chains Solution 7788 – SSL certificate chains and COMPAT ciphers do not include the chain certificates specified in the SSL profile Solution 8653 – A large number of certificates in a certificate chain may cause the SSL connection to close Conclusion Whether you are using a CA-provided chain or creating your own, we’ve taken the theory of certificate chains and configured a practical example of the trust relationships in building our first clientssl profile. In the next article in this series, we’ll take a look at ciphers.SSL Profiles Part 4: Cipher Suites
Introduction This is part 4 in a series of articles covering the BIG-IP LTM SSL profiles. SSL Overview and Handshake SSL Certificates Certificate Chain Implementation Cipher Suites SSL Options SSL Renegotiation Server Name Indication Client Authentication Server Authentication All the "Little" Options We’re working our way through the profile options, and this week, we’re taking a look at the SSL ciphers. What is a Cipher Suite? A cipher suite is a set of ciphers used in the privacy, authentication, and integrity of data passed between a server and client in an SSL session. Any given session uses one cipher, which is negotiated in the handshake. The components of the cipher are Key Exchange Algorithm (RSA or DH) – symmetric (same key for encryption/decryption) or asymmetric (shared public key for encryption, protected private key for decryption) Authentication Algorithm (RSA or DSS. Note that with RSA, Key Exchange and Authentication are combined) – Used for authenticating the server and/or client. X.509 certificates in the case of SSL. Encryption Algorithm (DES, 3DES, AES, RC4) – Used to encrypt the message payload Message Authentication Code (MAC) Digest Algorithm (MD5, SHA-1) – Used for message integrity So in looking at the ciphers on my v10.2 box: [root@golgotha:LICENSE EXPIRED] config # tmm --clientciphers 'DEFAULT' ID SUITE BITS PROT METHOD CIPHER MAC KEYX 0: 5 RC4-SHA 128 SSL3 Native RC4 SHA RSA 1: 5 RC4-SHA 128 TLS1 Native RC4 SHA RSA 2: 47 AES128-SHA 128 SSL3 Native AES SHA RSA 3: 47 AES128-SHA 128 TLS1 Native AES SHA RSA 4: 47 AES128-SHA 128 DTLS1 Native AES SHA RSA 5: 53 AES256-SHA 256 SSL3 Native AES SHA RSA 6: 53 AES256-SHA 256 TLS1 Native AES SHA RSA 7: 53 AES256-SHA 256 DTLS1 Native AES SHA RSA 8: 10 DES-CBC3-SHA 192 SSL3 Native DES SHA RSA 9: 10 DES-CBC3-SHA 192 TLS1 Native DES SHA RSA 10: 10 DES-CBC3-SHA 192 DTLS1 Native DES SHA RSA You can see that for the AES256-SHA cipher, key exchange & authentication are RSA, encryption is AES, and the mac is SHA-1. Notice that all the MD5 ciphers are missing? Beginning in v10.2, all the MD5 ciphers are removed by default. You can still use them, but you’ll need to make some changes to your cipher list. Larger key lengths (256 versus 128) makes for more complicated math and is thus a) harder to crack and b) more CPU intensive. Thankfully, all BIG-IP platforms (with LTM VE the obvious exception) have hardware offloading of this processing. You’ll want to be careful in the ciphers you offer, however, as some are not fully offloaded. The list is provided in solution 6739, which is referenced below in the resources section. Setting the Cipher Options in the profile The Ciphers field in the SSL profile by default has a single word: DEFAULT. DEFAULT means different things in different versions. If you want to avoid surprises when upgrading, you might consider specifying your parameters. The table below shows the variances in *DEFAULT* behavior between versions v9.4.x – v10.0.1 DEFAULT !SSLv2:ALL:!ADH:@SPEED v10.1.x DEFAULT !SSLv2:ALL:!DH:!ADH:!EDH:@SPEED v10.2.x DEFAULT !SSLv2:ALL:!DH:!ADH:!EDH:!MD5:!EXPORT:!DES:@SPEED This shows the progression through versions. First, EDH ciphers were eliminated, then in v10.2, low strength and MD5 ciphers were eliminated. Also, notice that @SPEED keyword? That will order all the ciphers by speed. If you desire the order to be by strongest cipher instead, you can use the @STRENGTH keyword. As for the format of the list itself, the cipher strings should be separated by colons and can feature the accepted cipher strings (listed here) and these formatting options: “!” – these ciphers are permanently deleted from the list and cannot reappear in the list even if explicitly stated. “-“ - these ciphers are deleted from the list but can be re-added by later options “+” – these ciphers are moved to the end of the list. Examples So if you wanted to use the v10.2 default but order by strength instead of speed, you could use this string: [root@golgotha:LICENSE EXPIRED] config # tmm --clientciphers '!SSLv2:ALL:!DH:!ADH:!EDH:!MD5:!EXPORT:!DES:@STRENGTH' ID SUITE BITS PROT METHOD CIPHER MAC KEYX 0: 53 AES256-SHA 256 SSL3 Native AES SHA RSA 1: 53 AES256-SHA 256 TLS1 Native AES SHA RSA 2: 53 AES256-SHA 256 DTLS1 Native AES SHA RSA 3: 10 DES-CBC3-SHA 192 SSL3 Native DES SHA RSA 4: 10 DES-CBC3-SHA 192 TLS1 Native DES SHA RSA 5: 10 DES-CBC3-SHA 192 DTLS1 Native DES SHA RSA 6: 5 RC4-SHA 128 SSL3 Native RC4 SHA RSA 7: 5 RC4-SHA 128 TLS1 Native RC4 SHA RSA 8: 47 AES128-SHA 128 SSL3 Native AES SHA RSA 9: 47 AES128-SHA 128 TLS1 Native AES SHA RSA 10: 47 AES128-SHA 128 DTLS1 Native AES SHA RSA Limiting only the high security ciphers and preventing any of the SSLv2 ciphers and any ciphers without authentication or encryption, while ordering by strength: [root@golgotha:LICENSE EXPIRED] config # tmm --clientciphers 'TLSv1+HIGH:!SSLv2:!aNULL:!eNULL:@STRENGTH' ID SUITE BITS PROT METHOD CIPHER MAC KEYX 0: 53 AES256-SHA 256 TLS1 Native AES SHA RSA 1: 58 ADH-AES256-SHA 256 TLS1 Compat AES SHA ADH 2: 55 DH-RSA-AES256-SHA 256 TLS1 Compat AES SHA DH/RSA 3: 57 DHE-RSA-AES256-SHA 256 TLS1 Compat AES SHA EDH/RSA 4: 10 DES-CBC3-SHA 192 TLS1 Native DES SHA RSA 5: 27 ADH-DES-CBC3-SHA 192 TLS1 Compat DES SHA ADH 6: 16 DH-RSA-DES-CBC3-SHA 192 TLS1 Compat DES SHA DH/RSA 7: 22 DHE-RSA-DES-CBC3-SHA 192 TLS1 Compat DES SHA EDH/RSA Testing Once the cipher list is established,I can test from the command line utilizing the s_client option in the openssl command: [root@golgotha:Active] config # openssl s_client -cipher 'AES256-SHA' -connect 10.10.20.112:443 CONNECTED(00000003) depth=0 /C=US/ST=IL/L=test/O=test/OU=test/CN=test.testco.com verify error:num=18:self signed certificate verify return:1 depth=0 /C=US/ST=IL/L=test/O=test/OU=test/CN=test.testco.com verify return:1 --- Certificate chain 0 s:/C=US/ST=IL/L=test/O=test/OU=test/CN=test.testco.com i:/C=US/ST=IL/L=test/O=test/OU=test/CN=test.testco.com --- Server certificate -----BEGIN CERTIFICATE----- MIICNjCCAZ+gAwIBAgIBADANBgkqhkiG9w0BAQUFADBhMQswCQYDVQQGEwJVUzEL MAkGA1UECBMCSUwxDTALBgNVBAcTBHRlc3QxDTALBgNVBAoTBHRlc3QxDTALBgNV BAsTBHRlc3QxGDAWBgNVBAMTD3Rlc3QudGVzdGNvLmNvbTAeFw0xMDA5MjcxOTUx MTBaFw0xMTA5MjcxOTUxMTBaMGExCzAJBgNVBAYTAlVTMQswCQYDVQQIEwJJTDEN MAsGA1UEBxMEdGVzdDENMAsGA1UEChMEdGVzdDENMAsGA1UECxMEdGVzdDEYMBYG A1UEAxMPdGVzdC50ZXN0Y28uY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKB gQDgHNoyzfUUwchuLfUfj8cJKISY8v8LBQ8NhzK3sO4GSi9K/iHP4n6X2b4XsN3S 288py0H6w10kNXQBu9yCT0SZHlJl5aZ9BTxCupAwu356W4nc1YEzXb6YgIoPLdU7 S+rOIekjSVbij+vES42v7A91wlw8kTxSSfwv5NxhHgseIQIDAQABMA0GCSqGSIb3 DQEBBQUAA4GBALoT8R3Bz2ZSWGjnTAOT07W13aYdMO5lcyQ05uurL/X0SooN4jes 4a4+/pyqHw2owZzmTxUiRxLIAw49lLzhyme38egOIx6svwPl05KcpfHbaoXJEfKx PDGAOHGNxRmDuvMVNGGmdBtXmlRokEqzHAbJTHQZLOWQwuiCM8NcTIF3 -----END CERTIFICATE----- subject=/C=US/ST=IL/L=test/O=test/OU=test/CN=test.testco.com issuer=/C=US/ST=IL/L=test/O=test/OU=test/CN=test.testco.com --- No client certificate CA names sent --- SSL handshake has read 732 bytes and written 244 bytes --- New, TLSv1/SSLv3, Cipher is AES256-SHA Server public key is 1024 bit Compression: NONE Expansion: NONE SSL-Session: Protocol : TLSv1 Cipher : AES256-SHA Session-ID: 9ECE925CED90B4CF2EA2E8D2DD62FDCF40D8A1BF4E7A3A24588BC5A7AB21221B Session-ID-ctx: Master-Key: 55C17443918E9B8B0B15443C37DD4B3C6A7E8EDF6F2E77EA4CC3BD4E9E5682F7700DDCFDDBB3F10CD7E6B13FD60EB836 Key-Arg : None Start Time: 1292452103 Timeout : 300 (sec) Verify return code: 18 (self signed certificate) You can see that the cipher I selected from the client (the only one the client would accept) is utilized for the active session. Now, if I make a request utilizing an MD5 cipher, it errors out if (as in this case) the default v10.2 cipher list is in place: [root@golgotha:Active] config # openssl s_client -cipher 'RC4-MD5' -connect 10.10.20.112:443 CONNECTED(00000003) 20193:error:14077410:SSL routines:SSL23_GET_SERVER_HELLO:sslv3 alert handshake failure:s23_clnt.c:578: Important Resources I’ve drawn from several solutions over at MyF5, here’s the short list: Default Cipher Suites in version 9.2x – 9.4.x: Solution 8800 Default Cipher Suites in version 10.x: Solution 10262 Ciphers fully hardware accelerated: Solution 6739 Cipher SSL profile reference: Solution 8802 Cipher Strength reference: Solution 7815 MD5 Ciphers removed in version 10.2: Solution 11624 Conclusion There’s a lot going on with ciphers, and any one article can’t do them justice. I didn’t even approach the discussion of why certain ciphers are good/bad/ugly. A study on cryptography is out of scope, and I’m not an authority in that area any. That said, the SSL profiles are extremely flexible in allowing cipher configurations of your choice, per virtual if desired. In the next article, we’ll move another checkbox down the profile and take a look at the SSL options field.Accessing TCP Options from iRules
I’ve written several articles on the TCP profile and enjoy digging into TCP. It’s a beast, and I am constantly re-learning the inner workings. Still etched in my visual memory map, however, is the TCP header format, shown in Figure 1 below. Since 9.0 was released, TCP payload data (that which comes after the header) has been consumable in iRules via the TCP::payload and the port information has been available in the contextual commands TCP::local_port/TCP::remote_port and of course TCP::client_port/TCP::server_port. Options, however, have been inaccessible. But beginning with version 10.2.0-HF2, it is now possible to retrieve data from the options fields. Preparing the BIG-IP Prior to version 11.0, it was necessary to set a bigpipe database key with the option (or options) of interest: bigpipe db Rules.Tcpoption.settings [option, first|last], [option, first|last] In version 11.0 and forward, the DB keys are no more and you need to create a tcp profile with the these options defined, like so: ltm profile tcp tcp_opt { app-service none tcp-options "{option first|last} {option first|last}" } The option is an integer between 2 and 255, and the first/last setting indicates whether the system will retain the first or last instance of the specified option. Once that key is set, you’ll need to do a bigstart restart for it to take (warning: service impacting). Note also that the LTM only collects option data starting with the ACK of a connection. The initial SYN is ignored even if you select the first keyword. This is done to prevent a SYN flood attack (in keeping with SYN-cookies). A New iRules Command: TCP::option The TCP::option command has the following syntax: TCP::option get <option> v11 Additions/Changes: TCP::option set <option number> <value> <next|all> TCP::option noset <option number> Pretty simple, no? So now that you can access them, what fun can be had? Real World Scenario: Akamai In Akamai’s IPA and SXL product lines, they support client IP visibility by embedding a version number (one byte) and an IPv4 address (four bytes) as part of their overlay path feature in tcp option number 28. To access this data, we first set the database key: tmsh create ltm profile tcp tcp_opt tcp-options "{28 first}" Now, the iRule utilizing the TCP::option command: when CLIENT_ACCEPTED { set opt28 [TCP::option get 28] if { [string length $opt28] == 5 } { binary scan $opt28 cH8 ver addr if { $ver != 1 } { log local0. "Unsupported Akamai version: $ver" } else { scan $addr "%2x%2x%2x%2x" ip1 ip2 ip3 ip4 set optaddr "$ip1.$ip2.$ip3.$ip4" } } } when HTTP_REQUEST { if { [info exists optaddr] } { HTTP::header insert "X-Forwarded-For" $optaddr } } The Akamai version should be one, so we log if not. Otherwise, we take the address (stored in the variable addr in hex) and scan it to get the decimal equivalents to build the address for inserting in the X-Forwarded-For header. Cool, right? Also cool—along with the new TCP::option command , an extension was made to the IP::addr command to parse binary fields into a dotted decimal IP address. This extension is also available beginning in 10.2.0-HF2, but extended in 11.0. Here’s the syntax: IP::addr parse [-ipv4 | -ipv6 [swap]] <binary field> [<offset>] So for example, if you had an IPv6 address in option 28 with a 1 byte offset, you would parse that like: log local0. "IP::addr parse IPv6 output: [IP::addr parse -ipv6 [TCP::option get 28] 1]" ## Log Result ## May 27 21:51:34 ltm13 info tmm[27207]: Rule /Common/tcpopt_test <CLIENT_ACCEPTED>: IP::addr parse IPv6 output: 2601:1930:bd51:a3e0:20cd:a50b:1cc1:ad13 But in the context of our TCP option, we have 5-bytes of data with the first byte not mattering in the context of an address, so we get at the address with this: set optaddr [IP::addr parse -ipv4 [TCP::option get 28] 1] This cleans up the rule a bit: when CLIENT_ACCEPTED { set opt28 [TCP::option get 28] if { [string length $opt28] == 5 } { binary scan $opt c ver if { $ver != 1 } { log local0. "Unsupported Akamai version: $ver" } else { set optaddr [IP::addr parse -ipv4 $opt28 1] } } } when HTTP_REQUEST { if { [info exists optaddr] } { HTTP::header insert "X-Forwarded-For" $optaddr } } No need to store the address in the first binary scan and no need for the scan command at all so I eliminated those. Setting a forwarding header is not the only thing we can do with this data. It could also be shipped off to a logging server, or used as a snat address (assuming the server had either a default route to the BIG-IP, or specific routes for the customer destinations, which is doubtful). Logging is trivial, shown below with the log command. The HSL commands could be used in lieu of log if sending off-box to a log server. when CLIENT_ACCEPTED { set opt28 [TCP::option get 28] if { [string length $opt28] == 5 } { binary scan $opt c ver if { $ver != 1 } { log local0. "Unsupported Akamai version: $ver" } else { set optaddr [IP::addr parse -ipv4 $opt28 1] log local0. "Client IP extracted from Akamai TCP option is $optaddr" } } } If setting the provided IP as a snat address, you’ll want to make sure it’s a valid IP address before doing so. You can use the TCL catch command and IP::addr to perform this check as seen in the iRule below: when CLIENT_ACCEPTED { set addrs [list \ "192.168.1.1" \ "256.168.1.1" \ "192.256.1.1" \ "192.168.256.1" \ "192.168.1.256" \ ] foreach x $addrs { if { [catch {IP::addr $x mask 255.255.255.255}] } { log local0. "IP $x is invalid" } else { log local0. "IP $x is valid" } } } The output of this iRule: <CLIENT_ACCEPTED>: IP 192.168.1.1 is valid <CLIENT_ACCEPTED>: IP 256.168.1.1 is invalid <CLIENT_ACCEPTED>: IP 192.256.1.1 is invalid <CLIENT_ACCEPTED>: IP 192.168.256.1 is invalid <CLIENT_ACCEPTED>: IP 192.168.1.256 is invalid Adding this logic into a functional rule with snat: when CLIENT_ACCEPTED { set opt28 [TCP::option get 28] if { [string length $opt28] == 5 } { binary scan $opt c ver if { $ver != 1 } { log local0. "Unsupported Akamai version: $ver" } else { set optaddr [IP::addr parse -ipv4 $opt28 1] if { [catch {IP::addr $x mask 255.255.255.255}] } { log local0. "$optaddr is not a valid address" snat automap } else { log local0. "Akamai inserted Client IP is $optaddr. Setting as snat address." snat $optaddr } } } Alternative TCP Option Use Cases The Akamai solution shows an application implementation taking advantage of normally unused space in TCP headers. There are, however, defined uses for several option “kind” numbers. The list is available here: http://www.iana.org/assignments/tcp-parameters/tcp-parameters.xml. Some options that might be useful in troubleshooting efforts: Opkind 2 – Max Segment Size Opkind 3 – Window Scaling Opkind 5 – Selective Acknowledgements Opkind 8 – Timestamps Of course, with tcpdump you get all this plus the context of other header information and data, but hey, another tool in the toolbox, right? Addendum I've been working with F5 SE Leonardo Simon on on additional examples I wanted to share here that uses option 28 or 253 to extract an IPv6 address if the version is 34 and otherwise extracts an IPv4 address if the version is 1 or 2. Option 28 when CLIENT_ACCEPTED { set opt28 [TCP::option get 28] binary scan $opt28 c ver #log local0. "version: $ver" if { $ver == 34 } { set optaddr [IP::addr parse -ipv6 $opt28 1] log local0. "opt28 ipv6 address: $optaddr" } elseif { $ver == 1 || $ver == 2 } { set optaddr [IP::addr parse -ipv4 $opt28 1] log local0. "opt28 ipv4 address: $optaddr" } } Option 253 when CLIENT_ACCEPTED { set opt253 [TCP::option get 253] binary scan $opt253 c ver #log local0. "version: $ver" if { $ver == 34 } { set optaddr [IP::addr parse -ipv6 $opt253 1] log local0. "opt253 ipv6 address: $optaddr" } elseif { $ver == 1 || $ver == 2 } { set optaddr [IP::addr parse -ipv4 $opt253 1] log local0. "opt253 ipv4 address: $optaddr" } }
