Clean up CRIME security doc [ci skip]

1 files changed, 41 insertions, 37 deletions

diff --git a/doc/security/crime_vulnerability.md b/doc/security/crime_vulnerability.md
index d716bff85a5..94ba5d1375d 100644
--- a/doc/security/crime_vulnerability.md
+++ b/doc/security/crime_vulnerability.md
@@ -1,59 +1,63 @@
 # How we manage the TLS protocol CRIME vulnerability
 
-> CRIME ("Compression Ratio Info-leak Made Easy") is a security exploit against 
-secret web cookies over connections using the HTTPS and SPDY protocols that also 
-use data compression.[1][2] When used to recover the content of secret 
-authentication cookies, it allows an attacker to perform session hijacking on an 
+> CRIME ("Compression Ratio Info-leak Made Easy") is a security exploit against
+secret web cookies over connections using the HTTPS and SPDY protocols that also
+use data compression. When used to recover the content of secret
+authentication cookies, it allows an attacker to perform session hijacking on an
 authenticated web session, allowing the launching of further attacks.
 ([CRIME](https://en.wikipedia.org/w/index.php?title=CRIME&oldid=692423806))
 
 ### Description
 
-The TLS Protocol CRIME Vulnerability affects compression over HTTPS therefore 
-it warns against using SSL Compression, take gzip for example, or SPDY which 
-optionally uses compression as well. 
+The TLS Protocol CRIME Vulnerability affects compression over HTTPS, therefore
+it warns against using SSL Compression (for example gzip) or SPDY which
+optionally uses compression as well.
 
-GitLab support both gzip and SPDY and manages the CRIME vulnerability by 
-deactivating gzip when https is enabled and not activating the compression
-feature on SDPY.
+GitLab supports both gzip and [SPDY][ngx-spdy] and mitigates the CRIME
+vulnerability by deactivating gzip when HTTPS is enabled. You can see the
+sources of the files in question:
 
-Take a look at our configuration file for NGINX if you'd like to explore how the 
-conditions are setup for gzip deactivation on this link: 
-[GitLab NGINX File](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-cookbooks/gitlab/templates/default/nginx-gitlab-http.conf.erb).
-
-For SPDY you can also watch how its implmented on NGINX at [GitLab NGINX File](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-cookbooks/gitlab/templates/default/nginx-gitlab-http.conf.erb)
-but take into consideration the NGINX documentation on its default state here: 
-[Module ngx_http_spdy_module](http://nginx.org/en/docs/http/ngx_http_spdy_module.html).
+* [Source installation NGINX file][source-nginx]
+* [Omnibus installation NGINX file][omnibus-nginx]
 
+Although SPDY is enabled in Omnibus installations, CRIME relies on compression
+(the 'C') and the default compression level in NGINX's SPDY module is 0
+(no compression).
 
 ### Nessus
 
-The Nessus scanner reports a possible CRIME vunerability for GitLab similar to the 
-following format:
-
-	Description
+The Nessus scanner, [reports a possible CRIME vulnerability][nessus] in GitLab
+similar to the following format:
 
-	This remote service has one of two configurations that are known to be required for the CRIME attack:
-	SSL/TLS compression is enabled.
-	TLS advertises the SPDY protocol earlier than version 4.
+```
+Description
 
-	...
+This remote service has one of two configurations that are known to be required for the CRIME attack:
+SSL/TLS compression is enabled.
+TLS advertises the SPDY protocol earlier than version 4.
 
-	Output
+...
 
-	The following configuration indicates that the remote service may be vulnerable to the CRIME attack:
-	SPDY support earlier than version 4 is advertised.
+Output
 
-*[This](http://www.tenable.com/plugins/index.php?view=single&id=62565) is a complete description from Nessus.*
+The following configuration indicates that the remote service may be vulnerable to the CRIME attack:
+SPDY support earlier than version 4 is advertised.
+```
 
-From the report above its important to note that Nessus is only checkng if TLS
-advertises the SPDY protocol earlier than version 4, it does not perform an 
-attack nor does it check if compression is enabled. With just this approach it 
+From the report above it is important to note that Nessus is only checking if
+TLS advertises the SPDY protocol earlier than version 4, it does not perform an
+attack nor does it check if compression is enabled. With just this approach, it
 cannot tell that SPDY's compression is disabled and not subject to the CRIME
-vulnerbility.
+vulnerability.
+
+### References
 
+* Nginx ["Module ngx_http_spdy_module"][ngx-spdy]
+* Tenable Network Security, Inc. ["Transport Layer Security (TLS) Protocol CRIME Vulnerability"][nessus]
+* Wikipedia contributors, ["CRIME"][wiki-crime] Wikipedia, The Free Encyclopedia
 
-### Reference
-* Nginx. "Module ngx_http_spdy_module", Fri. 18 Dec.
-* Tenable Network Security, Inc. "Transport Layer Security (TLS) Protocol CRIME Vulnerability", Web. 15 Dec.
-* Wikipedia contributors. "CRIME." Wikipedia, The Free Encyclopedia. Wikipedia, The Free Encyclopedia, 25 Nov. 2015. Web. 15 Dec. 2015.
\ No newline at end of file
+[source-nginx]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/support/nginx/gitlab-ssl
+[omnibus-nginx]: https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-cookbooks/gitlab/templates/default/nginx-gitlab-http.conf.erb
+[ngx-spdy]: http://nginx.org/en/docs/http/ngx_http_spdy_module.html
+[nessus]: https://www.tenable.com/plugins/index.php?view=single&id=62565
+[wiki-crime]: https://en.wikipedia.org/wiki/CRIME