CertCenter Developer Hub

Welcome to the new CertCenter developer hub. You'll find comprehensive guides and documentation to help you start working with CertCenter as quickly as possible, as well as support if you get stuck.

Let's jump right in!

Get Started Reference

mod_fauth: Installation & Configuration

Using file-based validation w/o using files may sound paradoxical and confusing, but actually, it is simpler than you think

This tutorial does not cover the advantages or pro and cons of mod_fauth. It's a real world installation, setup, and usage scenario (inspired by one of our European partner's implementation in its mass-hosting environment).

1. Easy installation

CertCenter's Apache module for automated, file-based, domain validation scenarios is available on GitHub (https://github.com/CertCenter/mod_fauth), and it runs under an MIT license.

All you need to do is download the source, get an authorization key for CertCenter's free key-value storage engine, and build the module with Apache's "apxs" and let Apache load it on its initialization. Let's start with the first step.

2. Getting the source

Okay, it's self-explanatory. However, there are different ways to get the source.

git clone https://github.com/CertCenter/mod_fauth.git
cd mod_fauth
mkdir mod_fauth
cd mod_fauth
curl -O 'https://raw.githubusercontent.com/CertCenter/mod_fauth/master/mod_fauth.c'

3. Key-value storage authorization

To use CertCenter's free key-value storage with mod_fauth, you need to ask your CertCenter Partner Manager or the support team for an AlwaysOnSSL KV-Storage Authorization-Key. The authorization key is a token which enables our key-value storage API to identify you uniquely. After you receive your key, apply it to the mod_fauth.c source.

//{..} Line 48:
#define DB_API_AUTH "#YOUR_AUHTORIZATION_KEY#"
#define DB_API_HOST "fauth-db.eu.certcenter.com"
#define DB_API_PORT "443"
//{..}

We recommend not to distribute the mod_fauth.c to your web server instances. Try to distribute appropriate .so files rather than the source code, which contains sensitive information. This also eliminates the requirement to apxs-build the source on all Apache instances.

4. Compiling the source and building the module

It's quite easy to compile the source code. After you've applied your individual authentication key to the source code, you can now use apxs (Apache extension tool) to build the Apache DSO. Make sure openssl-devel, httpd-devel (apxs), as well as gcc is available on your system.

apxs -c -i mod_fauth.c -I/usr/include/openssl -lssl

If everything works well, apxs will move mod_fauth.so to the respective module-directory (e.g., /usr/lib64/httpd/modules/). Apxs will also set the appropriate file permissions to 0755. Now that we have successfully built the DSO, we can pay attention to Apache's configurations.

5. Modifying Apache's configuration

Open your httpd.conf (/etc/httpd/conf/httpd.conf) and append a "LoadModule" directive to tell Apache to load the module while starting up.

// Tell Apache to load the mod_fauth module
LoadModule fauth_module modules/mod_fauth.so

After that, verify Apache's configuration:

service httpd configtest

If Apache gives you a "Syntax OK" message, you should restart the server:

service httpd graceful

6. Test if mod_fauth works properly

As a commercial hosting provider, you must be capable of delivering on promised functionality. That's why you should install mod_fauth in a sandbox (that's where you built the DSO) before using it in the productive environment. And, of course, you should test those functionalities. You just need to know an actual hostname that runs on your Apache to test mod_fauth.

Step 1: Put an example hash to the key value storage

curl -X POST 'https://fauth-db.eu.certcenter.com/#CommonName#' \
 -H 'x-api-key: #your-authorization-key#' \
 -H 'Content-Type: application/json' \
 -d '{"hash": "#ValidationHash#"}'
<?php
// {..}
//
// This is an excerpt from the examples provided
// by CertCenter's PHP Client Library:
//
// https://github.com/CertCenter/phpCertCenter
//
$KvStoreAuthorizationKey = "#your-authorization-key#";
$curl = curl_init("https://fauth-db.eu.certcenter.com/#CommonName#");
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, Array(
  "x-api-key: ".$KvStoreAuthorizationKey,
  "Content-type: application/json"
));
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode(Array(
  "hash"=> "#ValidationHash#",
)));
$r = json_decode(curl_exec($curl));
if($r->message!='success') {
  die("Couldn't write hash to key-value storage");
}
?>
package main

import (
  "fmt"
  certcenter "certcenter.com/go"
)

func main() {
  certcenter.Bearer = "AValidToken.oauth2.certcenter.com"
  certcenter.KvStoreAuthorizationKey = "#your-authorization-key#"
  res, err := certcenter.KvStore(&certcenter.KeyValueStoreRequest{
    Key: "#CommonName#",
    Value: "#ValidationHash#",
  }); if err!=nil {
    panic("..")
  }
}

Step 2: Test to retrieve the hash through your web server

On calling this URL, while "/.well-known/pki-validation/fileauth.htm" apparently does not exist in your web server's root directory, Apache recognizes that there could be a potential "404 Not Found" carried out to the client. That's where mod_fauth intercepts, identifies the URL pattern and asks the key-value storage if there is a hash filed for the respective host name.

curl 'http://#hostname#/.well-known/pki-validation/fileauth.txt'

It works?! You're awesome!

7. Final consideration

It may be useful to overwrite the settings of global mod_rewrite to prevent customers from setting or scripting it to change the behavior of requests to "/.well-known/globalsign/domain-validation/gstext.html" respectively "/.well-known/pki-validation/fileauth.txt." We highly recommend that the behavior of all URLs starting with "/.well-known/" not be changed. Of course, we could also change our module, but we don't want it to intercept too early. So, it's up to you to make sure that custom scripts or .htaccess settings won't prevent mod_fauth from working correctly. Here's one example of how you can configure Apache to turn off the RewriteEngine within the /.well-known directory:

<Location "/.well-known">
  RewriteEngine off
</Location>

That's all, folks!
Thanks for using our tutorials


mod_fauth: Installation & Configuration

Using file-based validation w/o using files may sound paradoxical and confusing, but actually, it is simpler than you think