Merge pull request #177 from OpenVoxProject/background_ssl

Update background/ssl

Author: tuxmea

docs/background/index.markdown

@@ -5,19 +5,19 @@ toc: false
 ---
 
 
-This page collects information about foundational technologies and practices. These are not tied to any specific Puppet product, but we believe many of our users will either need to or want to be familiar with them.
-
+This page collects information about foundational technologies and practices.
+These are not tied to any specific OpenVox product, but we believe many of our users will either need to or want to be familiar with them.
 
 ## [SSL and Related Topics](./ssl/)
 
-Puppet relies on HTTPS to secure its communications and identify nodes. Using it effectively requires familiarity with concepts like certificates and public key cryptography, which can sometimes present a steep learning curve for new Puppet users.
+OpenVox relies on HTTPS to secure its communications and identify nodes.
+Using it effectively requires familiarity with concepts like certificates and public key cryptography, which can sometimes present a steep learning curve for new OpenVox users.
 
-This series of articles explains the foundations of Puppet's security model, which is also used by many other systems across the internet.
+This series of articles explains the foundations of OpenVox's security model, which is also used by many other systems across the internet.
 
 - [Index](./ssl/index.html)
 - [What is Public Key Cryptography?](./ssl/public_key.html)
 - [What are Certificates and PKI?](./ssl/certificates_pki.html)
 - [What is TLS/SSL?](./ssl/tls_ssl.html)
 - [What is HTTPS?](./ssl/https.html)
 - [Appendix: Anatomy of a Certificate](./ssl/cert_anatomy.html)
-

docs/background/ssl/cert_anatomy.markdown

@@ -3,7 +3,6 @@ layout: default
 title: "Background Reference: What is HTTPS?"
 ---
 
-
 [index]: ./index.html
 [tls_ssl]: ./tls_ssl.html
 [certificate_anatomy]: ./cert_anatomy.html
@@ -12,71 +11,69 @@ title: "Background Reference: What is HTTPS?"
 
 Since SSL is a relatively generic protocol, it is usually used to wrap a more specific protocol, like HTTP or SMTP.
 
-HTTPS is the standard HTTP protocol wrapped with SSL --- an SSL connection is established as described in the previous article, then the client sends normal HTTP requests to the server over the secure channel. When the server responds, it also uses the secure channel.
+HTTPS is the standard HTTP protocol wrapped with SSL --- an SSL connection is established as described in the previous article, then the client sends normal HTTP requests to the server over the secure channel.
+When the server responds, it also uses the secure channel.
 
 The entire HTTP protocol is wrapped, including headers; this means that even URLs, parameters, and POST data will be encrypted.
 
-HTTPS and Puppet
------
+## HTTPS and OpenVox
 
-Puppet uses HTTPS for all of its traffic; puppet agent nodes act as clients and request their catalogs from the puppet master server.
+OpenVox uses HTTPS for all of its traffic; OpenVox agent nodes act as clients and request their catalogs from the OpenVox server.
 
-Since Puppet uses HTTPS, it requires a certificate-based PKI, which in turn requires public key cryptography. (Hence the prior articles in this series.)
+Since OpenVox uses HTTPS, it requires a certificate-based PKI, which in turn requires public key cryptography. (Hence the prior articles in this series.)
 
 ### Client Authentication
 
-Most of Puppet's HTTP endpoints require client authentication, so the puppet master can ensure nodes are authorized before serving configuration catalogs.
+Most of OpenVox's HTTP endpoints require client authentication, so the OpenVox server can ensure nodes are authorized before serving configuration catalogs.
 
-This means that both puppet master servers and puppet agent nodes must have their own certificates.
+This means that both OpenVox servers and OpenVOx agent nodes must have their own certificates.
 
 However, certain endpoints can be used without client authentication, mostly so that new nodes can retrieve a copy of the CA certificate, submit CSRs, and retrieve their signed certificates.
 
-Ports
------
+### Ports
 
 Technically, any port can be used to serve HTTPS. On the web, the usual convention is port 443.
 
-Puppet usually uses port 8140 instead, since its traffic doesn't really resemble web traffic.
+OpenVox usually uses port 8140 instead, since its traffic doesn't really resemble web traffic.
 
-Persistence of SSL/Certificate Data in HTTPS Applications
------
+### Persistence of SSL/Certificate Data in HTTPS Applications
 
-Since the entire HTTP protocol passes through the secure channel established by the SSL connection, the HTTP server and client don't have any direct involvement with the connection or the certificates. Likewise, any application logic will be several levels removed from the SSL details.
+Since the entire HTTP protocol passes through the secure channel established by the SSL connection, the HTTP server and client don't have any direct involvement with the connection or the certificates.
+Likewise, any application logic will be several levels removed from the SSL details.
 
 In practice, though, other levels of an application will usually want access to some SSL-related information:
 
-* The client application usually wants to examine the certificate metadata after the connection is established, since the server's identity and permissions are relevant to application-level authorization decisions. (For example, a user could check the identity of a server before deciding whether to enter sensitive information into a web form.)
+* The client application usually wants to examine the certificate metadata after the connection is established, since the server's identity and permissions are relevant to application-level authorization decisions.
+(For example, a user could check the identity of a server before deciding whether to enter sensitive information into a web form.)
 * If client authentication is enabled, the server application will want to know whether the authentication succeeded, and will want to examine the results.
 
 Thus, most SSL implementations have some means to publish connection and certificate data, so it can be used by higher layers of the protocol stack.
 
-An example of this is Apache's `mod_ssl` module. If it's [configured with the `StdEnvVars` option](http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#envvars), it will publish extensive SSL and certificate information as environment variables with predictable names. These variables can then be used by Apache itself, or by any application being spawned and managed by another Apache module (e.g. `mod_cgi`, `mod_passenger`, or `mod_php`).
+An example of this is Apache's `mod_ssl` module. If it's [configured with the `StdEnvVars` option](http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#envvars),
+it will publish extensive SSL and certificate information as environment variables with predictable names.
+These variables can then be used by Apache itself, or by any application being spawned and managed by another Apache module (e.g. `mod_cgi`, `mod_passenger`, or `mod_php`).
 
-SSL Termination and Proxying
------
+### SSL Termination and Proxying
 
-Large server-side HTTPS applications often need to be split into multiple semi-independent components or services, in order to accommodate better resiliency or performance. SSL is often the first component to go; even in cases where most of the application runs as a single process, SSL is computationally expensive enough to be worth splitting out.
+Large server-side HTTPS applications often need to be split into multiple semi-independent components or services, in order to accommodate better resiliency or performance.
+SSL is often the first component to go; even in cases where most of the application runs as a single process, SSL is computationally expensive enough to be worth splitting out.
 
-A single component that handles SSL in a service-oriented-architecture is called an _SSL terminating proxy._ SSL proxies work under basically the same requirements as the SSL component of a purely local application stack --- they must validate certificates and provide a secure channel, and they may need to publish connection and certificate information for use by other components of the stack. They also introduce one additional requirement: the network between the proxy and the application server must be very secure, as sensitive information will be passing along it in cleartext.
+A single component that handles SSL in a service-oriented-architecture is called an _SSL terminating proxy_.
+SSL proxies work under basically the same requirements as the SSL component of a purely local application stack.
+They must validate certificates and provide a secure channel, and they may need to publish connection and certificate information for use by other components of the stack.
+They also introduce one additional requirement: the network between the proxy and the application server must be very secure, as sensitive information will be passing along it in cleartext.
 
 [ssl_terminating_proxy]: ./images/ssl_terminating_proxy.png
 
 ![A drawing of an SSL terminating proxy removing SSL and sending a second unencrypted HTTP request with certificate data embedded in the headers.][ssl_terminating_proxy]
 
-SSL terminating proxies work by handling the incoming connection, then sending a second unencrypted HTTP request to the real application server. When the proxy receives a reply, it will forward it to the client along the original secure connection.
+SSL terminating proxies work by handling the incoming connection, then sending a second unencrypted HTTP request to the real application server.
+When the proxy receives a reply, it will forward it to the client along the original secure connection.
 
 If the application needs any SSL or certificate data, the proxy can be configured to publish it by inserting the data into the HTTP headers of the request it sends to the backend application server.
 
-An example of this is a puppet master running with the Nginx + Unicorn stack:
-
-* Nginx terminates SSL, and inserts the SSL client authentication status and client certificate DN into the HTTP headers of a new request. It sends this request to the Unicorn workers.
-* A Unicorn worker receives the unencrypted request, and, according to the common gateway interface (CGI) standard, publishes all HTTP header information as CGI variables, including the SSL information inserted by Nginx. It uses the Rack interface to translate the HTTP request into a request to the puppet master application.
-* The puppet master application reads SSL information from pre-arranged environment variables, and uses its auth.conf configuration to decide whether to serve the request. If yes, it uses its own application logic to decide what the request should be. Any response passes back through the Unicorn worker and Nginx to make its way to the puppet agent client.
-
-
-End of Series
------
+## End of Series
 
-At this point, you should understand enough about the fundamentals to understand any documentation on this site about managing Puppet's certificates, CA, and HTTPS authorization tools.
+At this point, you should understand enough about the fundamentals to understand any documentation on this site about managing OpenVox's certificates, CA, and HTTPS authorization tools.
 
 For a little more practical depth, you may also want to see the [appendix on certificate anatomy.][certificate_anatomy]

docs/background/ssl/certificates_pki.markdown

@@ -7,14 +7,18 @@ toc: false
 [wiki_pki]: http://en.wikipedia.org/wiki/Public_key_infrastructure
 [wiki_tls]: http://en.wikipedia.org/wiki/Transport_Layer_Security
 
-Puppet's network communications and security are all based on HTTPS, which secures traffic using X.509 certificates. It includes its own CA tools to provide PKI functionality to the whole deployment, although an existing CA can also be used.
+OpenVox's network communications and security are all based on HTTPS, which secures traffic using X.509 certificates.
+It includes its own CA tools to provide PKI functionality to the whole deployment, although an existing CA can also be used.
 
-These tools and protocols can sometimes present a steep learning curve for new Puppet users. This series provides background knowledge about how SSL and certificates work, and is aimed at giving new Puppet users enough fluency with these concepts to read and understand the rest of the SSL documentation on this site.
+These tools and protocols can sometimes present a steep learning curve for new OpenVox users.
+This series provides background knowledge about how SSL and certificates work,
+and is aimed at giving new OpenVox users enough fluency with these concepts to read and understand the rest of the SSL documentation on this site.
 
-> **A note about depth:** This background information is vastly simplified and glosses over a great many implementation details; its goal is basic competency, not expertise. But if you're interested in learning more, it should provide enough context and vocabulary to research these topics in more depth. (The Wikipedia pages on [PKI][wiki_pki] and [TLS/SSL][wiki_tls] may be a good starting place; after that, we recommend hitting the library or your local technical book store.)
+> **A note about depth:** This background information is vastly simplified and glosses over a great many implementation details; its goal is basic competency, not expertise.
+> But if you're interested in learning more, it should provide enough context and vocabulary to research these topics in more depth.
+> (The Wikipedia pages on [PKI][wiki_pki] and [TLS/SSL][wiki_tls] may be a good starting place; after that, we recommend hitting the library or your local technical book store.)
 
-Table of Contents
------
+## Table of Contents
 
 We recommend reading these articles in order, as each one lays foundations for the next.
 
@@ -24,17 +28,19 @@ Public key crypto is a family of tools for encrypting and verifying information.
 
 [**What are Certificates and PKI?**](./certificates_pki.html)
 
-A PKI is a way to associate public keys with trusted information about their owners, using documents called certificates. This slightly longer article explains how that trust works, and what pieces have to come together before a certificate can exist.
+A PKI is a way to associate public keys with trusted information about their owners, using documents called certificates.
+This slightly longer article explains how that trust works, and what pieces have to come together before a certificate can exist.
 
 [**What is TLS/SSL?**](./tls_ssl.html)
 
-Certificates can be used to create secure _and_ authenticated channels of communication over a network. You've probably already used one of those channels today. This article explains this practical use for certificates, and the benefits it provides.
+Certificates can be used to create secure _and_ authenticated channels of communication over a network. You've probably already used one of those channels today.
+This article explains this practical use for certificates, and the benefits it provides.
 
 [**What is HTTPS?**](./https.html)
 
-HTTP is a useful protocol for building applications, and it can be tunneled over TLS/SSL. This article explains how that works. It also explains how other parts of an HTTP-based application can gain access to certificate information and use it to authorize participants.
+HTTP is a useful protocol for building applications, and it can be tunneled over TLS/SSL. This article explains how that works.
+It also explains how other parts of an HTTP-based application can gain access to certificate information and use it to authorize participants.
 
 [**Appendix: Anatomy of a Certificate**](./cert_anatomy.html)
 
 This page shows several example certificates and points out their most important features, in order to highlight the lessons covered in the previous articles.
-