[rs-commit] r139 - in /rs-manual/trunk/src/site: resources/images/big-picture.png xhtml5/architecture.xhtml5 xhtml5/index.xhtml5
rs-commit at redwax.eu
rs-commit at redwax.eu
Mon Nov 11 23:47:15 CET 2019
Author: minfrin at redwax.eu
Date: Mon Nov 11 23:47:14 2019
New Revision: 139
Log:
Add the architecture principles and diagrams.
Added:
rs-manual/trunk/src/site/resources/images/big-picture.png (with props)
rs-manual/trunk/src/site/xhtml5/architecture.xhtml5
Modified:
rs-manual/trunk/src/site/xhtml5/index.xhtml5
Added: rs-manual/trunk/src/site/resources/images/big-picture.png
==============================================================================
Binary file - no diff available.
Propchange: rs-manual/trunk/src/site/resources/images/big-picture.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: rs-manual/trunk/src/site/xhtml5/architecture.xhtml5
==============================================================================
--- rs-manual/trunk/src/site/xhtml5/architecture.xhtml5 (added)
+++ rs-manual/trunk/src/site/xhtml5/architecture.xhtml5 Mon Nov 11 23:47:14 2019
@@ -0,0 +1,258 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
+ <head>
+ <title>Architecture</title>
+ <meta name="description" content="The underlying architecture of the Redwax Server." />
+ <link rel="canonical" href="https://redwax.eu/rs/docs/latest/architecture.html" />
+ </head>
+ <body>
+
+ <section class="spotlight style2 orient-right content-align-left image-position-left" id="introduction">
+ <div class="content null">
+ <h2>Redwax Server Architecture</h2>
+ <p>
+ The Redwax Server has an underlying architecture that attempts to meet a series of
+ security objectives.
+ </p>
+ <p>
+ Patches must meet the following design goals in order to be accepted by the project.
+ </p>
+ </div>
+ <div class="image">
+ <img src="images/candles-red.jpg" alt="" />
+ </div>
+ </section>
+
+ <section class="wrapper style1 align-center inner"
+ id="rpm">
+ <header>
+ <h2>Architecture Principles</h2>
+ <p>
+ Redwax Server attempts to solve a set of underlying problems, and the following design rules
+ exist in an effort to achieve this.
+ </p>
+ </header>
+ <div class="content index align-left">
+
+ <section>
+ <header>
+ <h3>Roll All The Crypto</h3>
+ </header>
+ <div class="content none">
+ <p>
+ The Redwax Server must allow someone to build a certificate authority
+ without requiring anyone to roll their own crypto.
+ </p>
+ <p>
+ While some modules may offer more power and flexibility than other modules,
+ the most straightforward certificate deployment cases need to be covered
+ with simple code that is difficult to misconfigure.
+ </p>
+ </div>
+ </section>
+
+ <section>
+ <header>
+ <h3>Easy To Deploy</h3>
+ </header>
+ <div class="content none">
+ <p>
+ It must be possible for an administrator to build their certificate
+ authority in a reasonable amount of time, and without the need to
+ read an encyclopaedia or understand every nuance of certificate
+ deployment.
+ </p>
+ <p>
+ The Redwax Server is based on a set of modules for the Apache HTTP
+ server, which is itself widely deployed, widely understood and well
+ documented.
+ </p>
+ </div>
+ </section>
+
+ <section>
+ <header>
+ <h3>Heritage</h3>
+ </header>
+ <div class="content none">
+ <p>
+ The bones that make up Redwax Server need to be battle tested and proven.
+ </p>
+ <p>
+ Redwax Server consists of a series of modules for
+ <a href="https://httpd.apache.org">Apache HTTP server</a>, which at the
+ time of writing is over 20 years old. In this time the code has been
+ tested, verified and battle hardened.
+ </p>
+ </div>
+ </section>
+
+ <section>
+ <header>
+ <h3>Small Attack Surface</h3>
+ </header>
+ <div class="content none">
+ <p>
+ A certificate authority must expose only the code needed to make the
+ certificate authority work, and no more.
+ </p>
+ <p>
+ Both Apache HTTP server and Redwax Server consists of a series of modules
+ that provide required functionality, and functionality that is not
+ required can be physically removed from a running server.
+ </p>
+ <p>
+ Redwax Server offers alternative implementations at different levels of
+ security, such as the <a href="mod/mod_ca_simple.html">mod_ca_simple</a>
+ module offering a straightforward level of functionality, or the
+ <a href="mod/mod_ca_engine.html">mod_ca_engine</a> module offering an
+ elevated hardware based level of security. It must be possible to ensure
+ that non desired functionality be removable so that it cannot be enabled
+ by accident.
+ </p>
+ <p>
+ Redwax Server is written in C only. While hook implementations might choose
+ to call out to scripts or other languages, this is not required to implement
+ a complete certificate authority.
+ </p>
+ </div>
+ </section>
+
+ <section>
+ <header>
+ <h3>No Gaps</h3>
+ </header>
+ <div class="content none">
+ <p>
+ The code implementing a certificate authority needs to have no gaps in
+ functionality.
+ </p>
+ <p>
+ Many languages or bindings are general in nature, and leave gaps
+ open in funcionality. SQL allows for SQL injection attacks. Scripting
+ allows for misquoting, unescaped parameters and significant whitespace.
+ The people implementing a certificate authority using Redwax Server must
+ be able to take for granted that these gaps are closed.
+ </p>
+ <p>
+ The Apache HTTP server hook mechanism offers a well defined low level
+ interface between modules in the system. Modules share well defined
+ data structures between them such as DER encoded ASN.1, and all data
+ is properly wrapped and escaped before transfer between modules. All user
+ provided data is sanitised and properly escaped by the protocol modules
+ before passing the data through the Redwax Server.
+ </p>
+ </div>
+ </section>
+
+ <section>
+ <header>
+ <h3>No Side Effects</h3>
+ </header>
+ <div class="content none">
+ <p>
+ The code implementing a certificate authority needs to have no side
+ effects.
+ </p>
+ <p>
+ Many crypto implementations have default or fallback behaviour when a
+ particular functionality is not available or fails. In the case of Redwax
+ Server, each hook implementation must provide a single well defined
+ behaviour that either performs a discrete action, or fails that action.
+ For example a hook implementation that returns the time via a hardware
+ clock must by default fail if the hardware clock is unavailable.
+ </p>
+ <p>
+ Should failover behaviour be present, this should be there because the
+ behaviour has been explicitly chosen by the certificate authority, and
+ not through implicit behaviour of the code.
+ </p>
+ </div>
+ </section>
+
+ <section>
+ <header>
+ <h3>Crypto Library Agnostic</h3>
+ </header>
+ <div class="content none">
+ <p>
+ It must be possible for the crypto engine implementing a certificate
+ to be realistically swapped out for another one.
+ </p>
+ <p>
+ While the current implementation of Redwax Server depends on OpenSSL,
+ none of the hook interfaces published by
+ <a href="mod/mod_ca.html">mod_ca</a> may contain any crypto library
+ specific data structures, but instead rely on open formats such as
+ DER encoded ASN.1. <a href="mod/mod_ca.html">mod_ca</a> itself must
+ not be linked to any crypto library.
+ </p>
+ <p>
+ This ensures that it is possible in future to swap out a crypto
+ library with another library, or run multiple libraries concurrently.
+ </p>
+ </div>
+ </section>
+
+ </div>
+ </section>
+
+ <section class="wrapper style1 align-center inner"
+ id="debian">
+ <header>
+ <h2>Architecture In Pictures</h2>
+ <p>
+ Diagrams of the Redwax Server architecture.
+ </p>
+ <div class="image">
+ <img src="images/big-picture.png" alt="" style="width: 100%;" />
+ </div>
+ </header>
+ <div class="content index align-left">
+
+ <section>
+ <header>
+ <h3>The Big Picture</h3>
+ </header>
+ <div class="content none">
+ <p>
+ Modules in Redwax Server are divided into two types.
+ </p>
+ <p>
+ <a href="mod/mod_ca.html#frontend">Frontend modules</a> are implemented
+ as Apache HTTP server handlers, and each implements a specific cryptographic
+ protocol like SCEP or OCSP. Each handler receives an HTTP request and
+ generates an HTTP response in return.
+ </p>
+ <p>
+ At key points during the protocol handling, the frontend modules call
+ out to hooks that are expected to perform discrete tasks, such as signing
+ a certificate sign request, or verifying whether a certificate has been
+ revoked.
+ </p>
+ <p>
+ <a href="mod/mod_ca.html#backend">Backend modules</a> contain hook
+ implementations that are chosen by the administrator to build the
+ certificate authority that is required. These backend modules hook into
+ the frontend modules to fulfill the requested task. Some hook implementations
+ call other hooks, for example the simple certificate signing hook
+ implementation calls further hooks to provide the time of signing and the
+ serial number of the resulting certificate.
+ </p>
+ <p>
+ While a particular hook implementation might choose to call another hook
+ that does not mean all hook implementations of the same type have to call
+ the same hooks. A hook implementation that saves a certificate sign
+ request to disk may choose not to call the get time hook, or the make
+ serial hook, where it makes no sense for the application.
+ </p>
+ </div>
+ </section>
+
+ </div>
+ </section>
+
+ </body>
+</html>
+
Modified: rs-manual/trunk/src/site/xhtml5/index.xhtml5
==============================================================================
--- rs-manual/trunk/src/site/xhtml5/index.xhtml5 (original)
+++ rs-manual/trunk/src/site/xhtml5/index.xhtml5 Mon Nov 11 23:47:14 2019
@@ -54,6 +54,7 @@
<h2>Other Topics</h2>
<ul class="alt">
<li><a href="faq.html">Frequently Asked Questions</a></li>
+ <li><a href="architecture.html">Architecture Principles</a></li>
</ul>
</div>
<div class="image">
More information about the rs-commit
mailing list