Merge "Add documentation for validators"

docs/validators.rst

@@ -1,4 +1,119 @@
 Validators
 ==========
 
-TODO
+Currently validators can check three things: the CSR, the incoming connection,
+and the authentication. The resulting action can be only pass or fail.
+Validators are configured in the ``config.json`` file and each one comes with
+different options.
+
+Included validators
+-------------------
+
+The following validators are implemented at the moment:
+
+``common_name``
+    Verifies: CSR. Parameters: ``allowed_domains``, ``allowed_networks``.
+
+    Ensures that the CN matches one of names in ``allowed_domains`` or IP
+    ranges in ``allowed_networks``.
+
+``alternative_names``
+    Verifies: CSR. Parameters: ``allowed_domains``.
+
+    Ensures that names specified in the subject alternative names extension
+    match one of the names in ``allowed_domains``.
+
+``alternative_names_ip``
+    Verifies: CSR. Parameters: ``allowed_domains``, ``allowed_networks``.
+
+    Ensures that names specified in the subject alternative names extension
+    match one of the names in ``allowed_domains`` or IP ranges in
+    ``allowed_networks``.
+
+``blacklist_names``
+    Verifies: CSR. Parameters: ``allowed_domains``, ``allowed_networks``.
+
+    Ensures that the CN and subject alternative names do not contain anything
+    configured in the ``domains``.
+
+``server_group``
+    Verifies: Auth, CSR. Parameters: ``group_prefixes``.
+
+    Ensures the requester is authorised to get a certificate for a given
+    server. This is currently assuming specific server naming scheme which
+    looks like ``{prefix}-{name}.{domain}``. For example if the prefixes are
+    defined as ``{"Nova": "nv"}``, and the client authentication returns group
+    "Nova", then a request for ``nv-compute1.domain`` will succeed, but a
+    request for ``gl-api1.domain`` will fail.
+
+    Only CN is checked and if there are no dashes in the CN, validation
+    succeeds.
+
+    This is not a well designed validator and may not be safe to use! A better
+    version is on the TODO list.
+
+``extensions``
+    Verifies: CSR. Parameters: ``allowed_extensions``.
+
+    Ensures that only ``allowed_extensions`` are present in the request. The
+    names recognised by Anchor are:
+
+    policyConstraints, basicConstraints, subjectDirectoryAttributes,
+    deltaCRLIndicator, cRLDistributionPoints, issuingDistributionPoint,
+    nameConstraints, certificatePolicies, policyMappings,
+    privateKeyUsagePeriod, keyUsage, authorityKeyIdentifier,
+    subjectKeyIdentifier, certificateIssuer, subjectAltName, issuerAltName
+
+``key_usage``
+    Verifies: CSR. Parameters: ``allowed_usage``.
+
+    Ensures only ``allowed_usage`` is requested for the certificate. The names
+    recognised by Anchor are:
+
+    Digital Signature, Non Repudiation, Key Encipherment, Data Encipherment,
+    Key Agreement, Certificate Sign, CRL Sign, Encipher Only, Decipher Only,
+
+    as well as short versions:
+
+    digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment,
+    keyAgreement, keyCertSign, cRLSign, encipherOnly, decipherOnly
+
+``ca_status``
+    Verifies: CSR. Parameters: ``ca_requested``.
+
+    Ensures the request does/doesn't require the CA flag.
+
+    This is not a well designed validator and may not be safe to use! A better
+    version is on the TODO list.
+
+``source_cidrs``
+    Verifies: CSR. Parameters: ``cidrs``.
+
+    Ensures the request comes from one of the ranges in `cidrs`.
+
+Extension interface
+-------------------
+
+Custom validators can be used with Anchor without changing the application
+itself. All validators are exposed as Stevedore_ extensions. They're registered
+as entry points in namespace ``anchor.validators`` and each name points to a
+simple function which accepts the following keyword arguments:
+
+``csr`` : anchor.X509.signing_request.X509Csr
+    An object describing the submitted CSR.
+
+``auth_result`` : anchor.auth.results.AuthDetails
+    An object which contains authentication information like username and user
+    groups.
+
+``request`` : pecan.Request
+    The https request which delivered the CSR.
+
+``conf`` : dict
+    Dictionary describing the registration authority configuration.
+
+On successful return, the request is passed on to the next validator or signed
+if there are no remining ones. On validation failure an
+``anchor.validators.ValidationError``  exception must be raised.
+
+.. _Stevedore: http://docs.openstack.org/developer/stevedore/index.html