SSL Inspector
| File:SSLInspector 128x128.png SSL Inspector |
|
About SSL Inspector
The SSL Inspector is a special application that allows other Untangle applications that process HTTP traffic to also process encrypted HTTPS traffic and applications that process SMTP to also process SMTP over SSL. It does this by performing man-in-the-middle decryption and encryption of SSL traffic, passing the unencrypted traffic through the Untangle server for inspection by other applications and services.
When a client makes an HTTPS request, the Inspector first initiates a secure SSL connection with the external server on behalf of the client. While this session is being established, the inspector captures information about the server SSL certificate. Once the server session is active, the Inspector uses the details from the server certificate to create a new certificate that will be used to encrypt the session between the inspector and the client. This certificate is generated or loaded on the fly, and is created using the same subject details contained in the actual server certificate. The certificate is then signed by the internal CA on the Untangle server, and is used to establish a secure connection between the inspector and the client. Creating the certificate this way is necessary to eliminate security warnings on the client, but it does require a few extra steps to properly configure the client computers and devices on your network. See the SSL Certificates section below for details.
SSL Certificates
SSL Certificates serve two primary purposes. They allow traffic between the client and server to be encrypted, and they allow the client to validate the authenticity of the server. There are two main ways the client checks the authenticity of the server certificate. The first is by validating the server certificate to ensure it has been issued or signed by a known and trusted third party certificate authority. Once that trust has been established, the client checks the server name portion of the target URL to ensure it matches the server name registered in the certificate presented by the server. If either of these checks fail, the client will typically display a warning, indicating that the security of the connection may be compromised.
When the Untangle server is initially installed, a default Certificate Authority is created automatically and used to sign the man-in-the-middle certificates created by the SSL Inspector. To view or make changes to the internal Certificate Authority, check out Certificates tab of the Config/Administration page.
Config > Administration > Certificates
Client Configuration
For the client authenticity checks to be successful, the client must be configured to trust the root certificate used by the Untangle server to sign the man-in-the-middle certificates described above. To configure clients, you must first use the Download Root Certificate button located on the Configuration tab of SSL Inspector Settings page to download the root certificate. You must then install this certificate in correct the location on the client.
Another way to download the root certificate is to simply access a special URL using the IP address of the Untangle server:
http://0.0.0.0/cert
Simply replace 0.0.0.0 with the IP address of your Untangle server. This method is especially useful when using mobile devices. For example, accessing this URL on an iPad or iPhone will download and display the certificate, and provide an option to install and trust the certificate directly on the device.
Below are basic instructions for installing the root certificate on some common client platforms. If yours is not listed, or you have any difficulty, consult the reference material for the target platform for further information.
Internet Explorer or Google Chrome on Microsoft Windows
- Log into the Untangle server running SSL Inspector.
- Go to Settings/Configuration and download the certificate using the "Download Root Certificate" button.
- Copy the root_authority.crt you just downloaded to the Windows client computer.
- From a command prompt, or from Start/Run, run the command "certmgr.msc".
- Open the "Trusted Root Certification Authorities" tree in the panel on the left.
- Right click on "Certificates" and select All Tasks --> Import.
- Proceed with the Certificate Import Wizard, selecting the the root_authority.crt file.
Firefox on Microsoft Windows
- Log into the Untangle server running SSL Inspector.
- Go to Settings/Configuration and download the certificate using the "Download Root Certificate" button.
- Copy the root_authority.crt you just downloaded to the Windows client computer.
- Launch Firefox
- From the Tools menu, go to Options -> Advanced -> Encryption -> View Certificates -> Authorities (**On version 41+ of Firefox ** From the Tools menu, go to Options -> Advanced -> View Certificates)
- Click the Import button and select the root_authority.crt file.
- Enable the "Trust this CA to identify websites" checkbox and click the OK button.
Opera on Microsoft Windows
- Log into the Untangle server running SSL Inspector.
- Go to Settings/Configuration and download the certificate using the "Download Root Certificate" button.
- Copy the root_authority.crt you just downloaded to the Windows client computer.
- Launch Opera
- From the Tools menu, go to Preferences -> Advanced -> Security and click Manage Certificates
- Select the Authorities tab, click Import, and select the root_authority.crt file.
- Click Install and click OK when asked if you are sure you want to trust the certificate.
Group Policy Distribution
If you have a fully deployed and implemented Active Directory infrastructure, you can leverage the Group Policy model to distribute the Untangle root certificate to all of your client computers. This is way outside our own area of expertise, so we can't provide much help or assistance, but we have compiled links to some TechNet articles with instructions for several common versions of Windows Server.
Settings
This section describes the different settings and configuration options available for SSL Inspector.
Configuration
Download Root Certificate
As described above, client computers and devices on your network need to be configured to trust the root certificate of the Untangle server. Clicking this button will allow you to download the root certificate. Once downloaded, you need to install it in the Trusted Authorities certificate store on your client computers and devices. Note that this is the same root certificate that can be downloaded from the Config > Administration > Certificates page. The download link is included on the SSL Inspector Configuration page for convenience.
Download Root Certificate Installer
Click this button to download a Windows installer that will automatically and properly install the root certificate for most popular web browsers that are installed and detected on the computer.
Block Invalid Traffic
When processing a new HTTPS session, the first thing the inspector does is analyze the initial client request to see if it contains a valid SSL negotiation message. If not, by default the session will be ignored and the traffic will flow directly between the client and server with no inspection performed. By enabling this checkbox, you can change the default behavior and effectively block any port 443 traffic that does not contain a valid HTTPS signature.
Enable SMTPS Traffic Processing
This option is enabled by default, and allows the SSL Inspector to work cooperatively with the other applications that act on SMTP mail traffic. When enabled, port 25 mail sessions that use STARTTLS will be decrypted inbound, allowing the clear traffic to pass through all other applications, and the re-encrypted again before passing outbound to the destination mail server.
Trust All Server Certificates
Normally, when establishing an SSL connection with an external server, the inspector will authenticate the server certificate against a standard list of trusted certificate authorities. If this trust cannot be established, the inspector will end the session. By enabling this checkbox, you can force the inspector to blindly trust all external server certificates.
Please note that we DO NOT recommend running with this option enabled, as it exposes all HTTPS traffic to significant security risks.
The standard list of trusted certificates used by Untangle is generated from the standard ca-certificates package. It includes, among others, certificate authorities used by Mozilla's browsers. Please note that Untangle can neither confirm nor deny whether the certificate authorities whose certificates are included in this list have in any way been audited for trustworthiness or RFC 3647 compliance. Full responsibility to assess them belongs to the local system administrator.
Upload Trusted Certificate
The inspector emulates a web browser when it makes outbound connections to external web servers. Just like a web browser, it must verify the authenticity of the server certificate before it will trust the connection and allow traffic to flow freely. As mentioned above, the inspector uses a standard list of known certificate authorities to validate server certificates. However, it's also possible you have servers in your network that use certificates that can't be authenticated this way. Perhaps you have your own certificate authority, or use self-signed certificates. Whatever the reason, you can use section of the configuration page to upload additional certificates that you want the inspector to trust.
Rules
The Rules tab allows you to specify explicit rules to Inspect or Ignore HTTPS traffic that crosses the Untangle. By default, many common HTTPS sites (google, youtube, yahoo, etc) are inspected, but not all HTTPS. This provides a safe default which provides HTTPS inspection on those sites without interfering with other HTTPS communications. It can easily be configured to inspect all HTTPS by enabling the "Inspect All Traffic" rule.
The Rules documentation describes how rules work and how they are configured. SSL Inspector uses rules to determine if it should inspect or ignore traffic for the specific session.
In addition to all the common rule types, there are three that are unique to the SSL Inspector, and these can be very useful for ignoring traffic that you don't want to inspect, or that isn't compatible with the SSL Inspector.
HTTPS: SNI Hostname
Most web browsers and many client applications include the destination hostname in the initial packet of an HTTPS session. The mechanism used is called the Server Name Indication, or the SNI extension to the TLS protocol. The main purpose is to allow a single web server to host multiple secure web sites. By analyzing the SNI hostname in the client request, the server can decide which SSL certificate to use for encrypting the session. This extension is necessary because the encryption must be established long before the server ever sees the HTTP request, and by then it would be too late to use a different certificate.
Creating ignore rules based on the SNI hostname is an effective way to have the SSL Inspector ignore incompatible traffic. A prime example is the default rule for Microsoft Update. The Microsoft Update client checks the server certificate to ensure it was signed by a specific authority. Since it doesn't trust the Root Aurthority the SSL Inspector uses to generate certificates on-the-fly, Microsoft Update will fail with an error. The default rule allows this traffic to be detected and ignored, allowing Microsoft Update to work properly.
HTTPS: Certificate Subject and HTTPS: Certificate Issuer
These two rule conditions are useful when dealing with client applications that don't use SNI, and aren't compatible with SSL Inspectory. An excellent example is the Dropbox client utility for which there is also a default rule. Like Microsoft Update, the Dropbox client will reject SSL certificates that it doesn't explicitly trust.
Using either of these rule conditions, you can match traffic on any portion of the Subject or Issuer Distinguished Name (DN) included in the server certificate. In both cases, the information in the match string includes the standard information fields commonly stored within the SSL certificates, such as CN (common name), C (country), ST (state), L (locality), O (organization), and OU (organizational unit). Each of these are appended to the match string and separated by commas. Note that not all fields are required in all certificates, and some certificates may have others not listed. The order they occur in the match string is also not guaranteed.
The Subject DN generally includes information about the company to which the certificate was issued. Here is an example Certificate Subject:
CN=*.dropbox.com, O="Dropbox, Inc.", L=San Francisco, ST=California, C=US
The Issuer DN generally includes information about the company that issued and authenticated the certificate. Here is an example Certificate Issuer:
CN=Thawte SSL CA, O="Thawte, Inc.", C=US
Rule Actions
- Inspect: Causes the traffic which matched the rule to be decrypted and passed along to other applications and service for further inspection, classification, and possible action.
- Ignore: Causes the traffic which matched the rule to be ignored the SSL Inspector.
Reports
The Reports tab provides a view of all reports and events for all traffic handled by HTTPS Inspector.
Reports
This applications reports can be accessed via the Reports tab at the top or the Reports tab within the settings. All pre-defined reports will be listed along with any custom reports that have been created.
Reports can be searched and further defined using the time selectors and the Conditions window at the bottom of the page. The data used in the report can be obtained on the Current Data window on the right.
Pre-defined report queries: {{#section:All_Reports|'SSL Inspector'}}
The tables queried to render these reports:
Status
The status of the session that generated the event.
- INSPECTED means the session was fully processed by the inspector, and all traffic was passed through all the other applications and services.
- IGNORED means the session was not or could not be inspected, so the traffic was completely ignored and not analyzed by any applications or services.
- BLOCKED means the traffic was blocked because it did not contain a valid HTTPS request, and the Block Invalid Traffic option was enabled.
- UNTRUSTED means the traffic was blocked because the server certificate could not be authenticated.
- ABANDONED means the connection failed because an an underlying SSL connection problem. Usually that the client abandoned the connection because the certificate was not trusted.
Detail
Extra details about the session, with the exact content dependent on the event status.
For INSPECTED and UNTRUSTED sessions, this field will include the SNI hostname extracted from the initial message sent from the client to the server. If the SNI information is not available, the server IP address will be used instead.
For BLOCKED or IGNORED sessions, this field will contain the description of the rule that matched and was applied to the session.
For ABANDONED sessions, detail will usually record information about the error that caused inspection to fail. For SSL exceptions, this will include Client or Server to indicate the session endpoint for which traffic was being processed. It will also include Encrypt or Decrypt to indicate the state of traffic inspection when the exception occurred. If available, the SSL error message will also be included. The following table lists the most common error messages and detailed information about each one.
| unexpected_message | An inappropriate message was received. This alert is always fatal and should never be observed in communication between proper implementations. |
| bad_record_mac | This alert is returned if a record is received with an incorrect MAC. This alert also MUST be returned if an alert is sent because a TLSCiphertext decrypted in an invalid way: either it wasn't an even multiple of the block length, or its padding values, when checked, weren't correct. This message is always fatal and should never be observed in communication between proper implementations (except when messages were corrupted in the network). |
| decryption_failed | This alert was used in some earlier versions of TLS, and may have permitted certain attacks against the CBC mode [CBCATT]. It MUST NOT be sent by compliant implementations. |
| record_overflow | A TLSCiphertext record was received that had a length more than 2^14+2048 bytes, or a record decrypted to a TLSCompressed record with more than 2^14+1024 bytes. This message is always fatal and should never be observed in communication between proper implementations (except when messages were corrupted in the network). |
| decompression_failure | The decompression function received improper input (e.g., data that would expand to excessive length). This message is always fatal and should never be observed in communication between proper implementations. |
| handshake_failure | Reception of a handshake_failure alert message indicates that the sender was unable to negotiate an acceptable set of security parameters given the options available. This is a fatal error. |
| no_certificate | This alert was used in SSLv3 but not any version of TLS. It MUST NOT be sent by compliant implementations. |
| bad_certificate | A certificate was corrupt, contained signatures that did not verify correctly, etc. |
| unsupported_certificate | A certificate was of an unsupported type. |
| certificate_revoked | A certificate was revoked by its signer. |
| certificate_expired | A certificate has expired or is not currently valid. |
| certificate_unknown | Some other (unspecified) issue arose in processing the certificate, rendering it unacceptable. |
| illegal_parameter | A field in the handshake was out of range or inconsistent with other fields. This message is always fatal. |
| unknown_ca | A valid certificate chain or partial chain was received, but the certificate was not accepted because the CA certificate could not be located or couldn't be matched with a known, trusted CA. This message is always fatal. |
| access_denied | A valid certificate was received, but when access control was applied, the sender decided not to proceed with negotiation. This message is always fatal. |
| decode_error | A message could not be decoded because some field was out of the specified range or the length of the message was incorrect. This message is always fatal and should never be observed in communication between proper implementations (except when messages were corrupted in the network). |
| decrypt_error | A handshake cryptographic operation failed, including being unable to correctly verify a signature or validate a Finished message. This message is always fatal. |
| export_restriction | This alert was used in some earlier versions of TLS. It MUST NOT be sent by compliant implementations. |
| protocol_version | The protocol version the client has attempted to negotiate is recognized but not supported. (For example, old protocol versions might be avoided for security reasons.) This message is always fatal. |
| insufficient_security | Returned instead of handshake_failure when a negotiation has failed specifically because the server requires ciphers more secure than those supported by the client. This message is always fatal. |
| internal_error | An internal error unrelated to the peer or the correctness of the protocol (such as a memory allocation failure) makes it impossible to continue. This message is always fatal. |
| user_canceled | This handshake is being canceled for some reason unrelated to a protocol failure. If the user cancels an operation after the handshake is complete, just closing the connection by sending a close_notify is more appropriate. This alert should be followed by a close_notify. This message is generally a warning. |
| no_renegotiation | Sent by the client in response to a hello request or by the server in response to a client hello after initial handshaking. Either of these would normally lead to renegotiation; when that is not appropriate, the recipient should respond with this alert. At that point, the original requester can decide whether to proceed with the connection. One case where this would be appropriate is where a server has spawned a process to satisfy a request; the process might receive security parameters (key length, authentication, etc.) at startup, and it might be difficult to communicate changes to these parameters after that point. This message is always a warning. |
| unsupported_extension | sent by clients that receive an extended server hello containing an extension that they did not put in the corresponding client hello. This message is always fatal. |
SSL Inspector FAQs
Does SSL Inspector work with Captive Portal?
Yes, SSL Inspector will decrypt HTTPS request to HTTP which will then be handled just like normal HTTP request by Captive Portal. If the client is captured and not authenticated they will be redirected to a login page.
SSL Inspector does not seem to be working with google and Chrome. Why?
Newer Chrome versions use a custom protocol call QUIC to communicate with google. Adding a Firewall Rule or Filter Rule to block port 443 UDP will block QUIC and force chrome to use regular HTTPS which will be handled normally.
