HTTPS inspection

​

Overview

​

Core Mechanics (C++ Source Validation)

• Deep Scan (MITM): The connection evaluator determines if deepscan is enabled for the connection. If true, SafeSquid performs full Man-in-the-Middle interception by generating a forged, trusted certificate for the client using the defined Root CA, enabling inspection of the encrypted payload.
• Upstream Validation: SafeSquid builds an OpenSSL certificate store and verification parameters to validate the upstream origin server’s certificate against known CA authorities.
• Strict Error Handling: Handlers validate domain mismatches (block_domain_mismatch), missing certificates (block_no_cert), and maximum allowable OpenSSL error levels (max_error_level). Failures drop the connection to prevent MITM attacks from malicious servers.

​

Schema Fields

​

Global Fields

• Enabled (enabled): Master switch for HTTPS Inspection. Off: The policy engine returns NULL and the inspection engine never enables Deep Scan. On: policies apply only when RCSC setup succeeds.

​

Rule-Based Fields (Per Connection Tuning)

• Enabled (enabled): When disabled, this row is skipped. First matching enabled row wins for each CONNECT.
• Comment (comment): Operator note only; not used in SSL verification logs.
• Profiles (profiles): Connection must match at least one listed profile (Access Profiles engine). Leave blank for all connections. Negated tags ( !profile ) skip the row when that profile is present. The engine stops at the first matching row from the top.
• DeepScan (deepscan): When TRUE, the inspection engine returns TRUE and SafeSquid performs a client TLS handshake on CONNECT, decrypting HTTP for inspection. When FALSE, CONNECT is tunneled without decrypting; upstream SSL checks in this row are not applied to tunneled traffic. Use FALSE for non-HTTP TLS (Drive, Subversion, WinSCP, etc.).
• Block Access to Sites that do not have an SSL Certificate (block_no_cert): When TRUE (default), upstream validation blocks if the upstream presents no certificate. When FALSE, connections without a server certificate are allowed to continue (logged at DEBUG).
• Acceptable Errors in SSL Verification (block_err_level): Maximum OpenSSL verification error SafeSquid tolerates on the upstream certificate. Upstream validation blocks when error limits are exceeded. Level 0 is strictest — only a fully valid chain passes. Hostname and IP mismatch are also gated by Block domain mismatch separately.
• Block domain mismatch in the web-site SSL certificate (block_domain_mismatch): When TRUE (default), hostname or IP mismatch errors from OpenSSL block the connection. When FALSE, X509_V_ERR_HOSTNAME_MISMATCH and X509_V_ERR_IP_ADDRESS_MISMATCH are explicitly allowed even if they exceed the acceptable error level.
• Enabled (enabled): When disabled, this Setup row is skipped when the list is rebuilt on config reload. Note: rows are loaded into server_config_list but no runtime code in this tree reads that list (see ambiguities).
• Comment (comment): Operator note only; not referenced by SSL setup code.
• Proxy Host (proxy_server): Intended to match this SafeSquid instance (hostname from startup parameters) so the row applies on the correct node.
• Encrypted Password (enc_pwd): Encrypted passphrase for the RCSC private key, stored per Setup row. Runtime RCSC load uses the global activation password, not this field, in the current build.
• SSL Cache Store Size (ssl_cache_store_size): Intended cap for outbound SSL context/session cache entries ( CTXcacheOUT ). Stored on each server_config row but not applied by current cache code (cache sizing is internal to CTXcacheOUT ). Changing cache behaviour requires a restart when supported.
• appcontent (appcontent): No description provided.

​

How CONNECT is handled

1. On CONNECT, the inspection engine loads the first matching Inspection Policy row.
2. When Deep Scan is FALSE, CONNECT is forwarded as a tunnel without decrypting application data.
3. When Deep Scan is TRUE and RCSC is valid, SafeSquid completes a client-side TLS handshake and decrypts HTTP for filtering.
4. Before decrypting, the validation engine checks the upstream certificate (no cert, error level, domain mismatch rules).
5. Deep Scan only works when the tunneled protocol is HTTP; many non-HTTP TLS clients break when forced through inspection.

​

Inspection Policy fields

• DeepScan — TRUE enables client TLS handshake and HTTP inspection. FALSE tunnels HTTPS without decrypting.
• Block Access to Sites that do not have an SSL Certificate — When TRUE (default), block if upstream presents no certificate.
• Acceptable Errors in SSL Verification — Maximum OpenSSL verification error tolerated on the upstream chain. Level 0 is strictest. Hostname/IP mismatch is gated separately by Block domain mismatch.
• Block domain mismatch in the web-site SSL certificate — When TRUE (default), hostname or IP mismatch errors block. When FALSE, mismatch errors are allowed even if they exceed the acceptable error level.
• Profiles — First matching enabled row from the top applies. Blank matches all connections.

​

Code quirks — Setup subsection unused at runtime

​

Examples

​

Recommended practice

• Deploy RCSC to all managed clients before enabling Deep Scan broadly.
• Use DeepScan FALSE rows for protocols that are not HTTP-over-TLS.
• Use SSL Certs/Cache to upload corporate roots and refresh caches after certificate changes.
• Do not rely on Setup Encrypted Password for RCSC unlock — use activation passphrase.

​

How to verify

1. CONNECT to an HTTPS site; confirm filters (for example ClamAV) see decrypted content when DeepScan is TRUE.
2. Enable SSL log level for SSLcertSection:: and certificate validation lines.
3. Check Detailed logs for CONNECT handling and upstream certificate errors.
4. SSL Certs/Cache → Cache Refresh after RCSC or trusted-CA changes.