[squid-users] clarifying Features/SslPeekAndSplice on wiki + fake CONNECT

[Marcus Kool]

The ssl-bump peek/splice/bump feature is now maturing and many are using it but
there are still some issues with the wiki page that I like to clarify.
wiki: http://wiki.squid-cache.org/Features/SslPeekAndSplice

section "processing steps"

Can action "none" be removed from step 1?

Step 1.  what is "CONNECT info" ?  In the introduction one speaks
of "HTTP CONNECT" which has a FQDN.  But the fake CONNECT sent to
a URL rewriter has only an IP address.

Why is the fake CONNECT that is sent to the URL rewriter done
at step 1 where only the IP and not the FQDN is available?
It seems to make more sense to do this in step 2 when the SNI/FQDN is available
and a proper fake HTTP CONNECT can be sent to helpers.  The helpers need to get
the FQDN in the same way they get the FQDN in non-interception mode.
And as a bonus the value of the parameter %ssl::>sni in url_rewrite_extras
will become useful (i.e. not the '-').

In section "Peek at SNI and Bump" it is stated that SNI is obtained in step 1.
This contradicts the text at step 1 and 2.

squid.conf.documented has this:
#       acl aclname at_step step
#         # match against the current step during ssl_bump evaluation [fast]
#         # Never matches and should not be used outside the ssl_bump context.
#         #
#         # At each SslBump step, Squid evaluates ssl_bump directives to find
#         # the *next* bumping action (e.g., peek or splice). Valid SslBump step
#         # values and the corresponding ssl_bump evaluation moments are:
#         #   SslBump1: After getting TCP-level and HTTP CONNECT info.
#         #   SslBump2: After getting SSL Client Hello info.
#         #   SslBump3: After getting SSL Server Hello info.
Emphasis on "*next* bumping action".
Should the wiki be reworded and use "next bumping action"?

Section "Actions"

item peek: Receive client SNI (step1), or server certificate (step2)  ...
This contradicts the explanation of the processing steps.
item stare: likewise.

I suggest to remove the "Deprecated actions" or use a BOLD warning not to use them.

Section "Mimicking SSL client Hello properties when staring"
The section has "The information in this section is incomplete and somewhat stale."
Is there any information to update this section ?

section "Examples"

I usually write explicit rules like this:
# TLS/SSL bumping definitions
acl tls_s1_ip_connect   at_step SslBump1
acl tls_s2_client_hello at_step SslBump2
acl tls_s3_server_hello at_step SslBump3
# do not touch servers where ssl-bump breaks HSTS
acl tls_allowed_hsts ssl::server_name .akamaihd.net
# prevent bumping some allowed servers with self-signed certificates
acl tls_allowed_selfsigned ssl::server_name .nic.es .example.local
# prevent bumping of sites where client software fails when bumped
acl tls_allowed_software ssl::server_name .dropbox.com .googledrive.com drive.google.com
# do not bump internal servers
acl tls_server_is_ours ssl::server_name foo.example.com
# do not touch servers of a bank
acl tls_server_is_bank ssl::server_name .santander.com.br
acl tls_server_is_bank ssl::server_name .santander.com
acl tls_server_is_bank ssl::server_name .santandernet.com.br
acl tls_to_splice any-of tls_allowed_hsts tls_allowed_selfsigned tls_server_is_bank tls_server_is_ours tls_allowed_software
# TLS/SSL bumping steps
ssl_bump peek   tls_s1_ip_connect   all                 # peek a client connecting at IP level
ssl_bump splice tls_s2_client_hello tls_to_splice       # splice some: do not bump/interfere
ssl_bump stare  tls_s2_client_hello all                 # connect to the server and stare(peek) at its TLS/SSL properties
ssl_bump bump   tls_s3_server_hello all                 # bump if we can (tls_s2_client_hello/stare succeeded)

The above rules follow the steps of the wiki page but
the examples on the wiki have optimised rules and sometimes
there are messages on the mailing list that rules can be optimized
to save CPU cycles.

The last 4 lines of the example can be optimized into
ssl_bump peek   tls_s1_ip_connect   all
ssl_bump splice tls_s2_client_hello tls_to_splice
ssl_bump stare  all
ssl_bump bump   all

I prefer not to optimize since reading the rules is
easier and one understands better what happens at each step.
However, if a significant number of CPU cycles are saved, I suggest to
include an example like above and rules of thumb on how to optimize and the
final optimized results so that a less experienced reader understands
the optimizations.

The examples in "Avoid bumping banking traffic" :
I can image what used (but not defined) serverIsBank acl looks like:
    acl serverIsBank  ssl::server_name .santander.com
but have no idea what the acl haveServerName looks like.
What is intended here?

Marcus