Use MKDocs (#63)

.github/workflows/github_pages.yml

@@ -0,0 +1,51 @@
+# Build and deploy Jekyll site to GitHub Pages
+name: Deploy GitHub Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+    paths:
+      - "**/*.md"
+      - "**/*.html"
+      - ".github/workflows/pages.yml"
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+# Deploy GitHub Pages using MKDocs  
+jobs:
+  deploy-pages:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.12
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material
+      - run: pip install mkdocs-material-extensions
+      - run: mkdocs gh-deploy --force -c -b gh-pages
+

.github/workflows/pages.yml

@@ -3,12 +3,12 @@ name: Deploy GitHub Pages
 
 on:
   # Runs on pushes targeting the default branch
-  push:
-    branches: ["main"]
-    paths:
-      - "**/*.md"
-      - "**/*.html"
-      - ".github/workflows/pages.yml"
+  # push:
+  #  branches: ["main"]
+  #  paths:
+  #    - "**/*.md"
+  #    - "**/*.html"
+  #    - ".github/workflows/pages.yml"
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:

docs/automation.md

@@ -1,13 +1,12 @@
 # Automation
-| [Home](index.md) | [Getting Started](getting-started.md) | [Client Certificates](client-certificates.md) | [CRL](revocation.md) | [CA Cert Locations](locations.md) | [Options](options.md) | [Automation](automation.md) | [Security](security.md) | [FAQ](faq.md) |  
 
 The serverless CA can be deployed and updated using a CI/CD pipeline.
 
 ## GitHub Actions example
 
-For examples using GitHub Actions see one of the [test GitHub Actions workflows](../.github/workflows/ecdsa_default.yml) within this repository, or the [Cloud CA deployment workflow](https://github.com/serverless-ca/cloud-ca/blob/main/.github/workflows/deploy.yml) shown below:
+For examples using GitHub Actions see one of the [test GitHub Actions workflows](https://github.com/serverless-ca/terraform-aws-ca/blob/main/.github/workflows/ecdsa_default.yml) within this repository, or the [Cloud CA deployment workflow](https://github.com/serverless-ca/cloud-ca/blob/main/.github/workflows/deploy.yml) shown below:
 
-<img src="images/deployment-workflow.png" width="600">
+![Alt text](images/deployment-workflow.png?raw=true "GitHub Actions workflow")
 
 The principal steps are:
 

docs/client-certificates.md

@@ -1,5 +1,4 @@
 # Client Certificates
-| [Home](index.md) | [Getting Started](getting-started.md) | [Client Certificates](client-certificates.md) | [CRL](revocation.md) | [CA Cert Locations](locations.md) | [Options](options.md) | [Automation](automation.md) | [Security](security.md) | [FAQ](faq.md) |  
 
 There are two methods available for requesting and issuing client certificates:
 * **Lambda** - certificates requested and issued by invoking a Lambda function
@@ -25,7 +24,7 @@ chmod 600 ~/certs/client-cert-key.pem
 * Client certificates for containers in Amazon EKS / ECS / Fargate 
 
 **Approach - Amazon ECS / EKS**
-* Create a Sidecar container based on [client-cert.py](../utils/server-cert.py)
+* Create a Sidecar container based on [client-cert.py](https://github.com/serverless-ca/terraform-aws-ca/blob/main/utils/client-cert.py)
 * Requires role with permissions to invoke the CA TLS Lambda function
 * Certificate, CA bundle and private key should be written to e.g. `/certs` with locked-down folder permissions
 * They can then be mounted into the application container
@@ -68,7 +67,7 @@ Only valid domains will be included in the Subject Alternative Name X.509 certif
 **Enable GitOps**  
 If you followed the [Getting Started](getting-started.md) guide, you'll already have enabled GitOps:
 * add a subdirectory to your repository with the same name as the value of the Terraform variable `env`, e.g. `dev`, `prd`
-add files and subdirectory following the [rsa-public-crl example](../examples/rsa-public-crl/README.md)
+add files and subdirectory following the [rsa-public-crl example](https://github.com/serverless-ca/terraform-aws-ca/blob/main/examples/rsa-public-crl/README.md)
 * change the value of Terraform variable `cert_info_files` to  `["tls", "revoked", "revoked-root-ca"]`
 * apply Terraform
 
@@ -105,9 +104,12 @@ python utils/server-csr.py
 * using the console, navigate to the CA DynamoDB table
 * select Explore table items
 * run a query, searching for the Common Name
-<img src="images/dynamodb-test-server-cert.png" width="300">
+![Alt text](images/dynamodb-test-server-cert.png?raw=true "DynamoDB query")
+
 * select the issued certificate by clicking on the link
-<img src="images/dynamodb-test-server-cert-details.png" width="300">
+
+![Alt text](images/dynamodb-test-server-cert-details.png?raw=true "DynamoDB item details")
+
 * copy the certificate value, this is double Base64 encoded when viewed in the console
 
 **Decoding DynamoDB certificate (Linux / MacOS)**

docs/faq.md

@@ -1,5 +1,4 @@
 # Frequently Asked Questions
-| [Home](index.md) | [Getting Started](getting-started.md) | [Client Certificates](client-certificates.md) | [CRL](revocation.md) | [CA Cert Locations](locations.md) | [Options](options.md) | [Automation](automation.md) | [Security](security.md) | [FAQ](faq.md) |  
 
 ### Can certificates only be used in AWS?
 No, certificates issued by the CA can be used anywhere.
@@ -25,7 +24,7 @@ It will also result in a Authority Information Access (AIA) extension being adde
 No, OSCP is not currently supported
 
 ### What algorithms can be used for the CAs?
-The following algorithms can be selected via Terraform [variables](../variables.tf):
+The following algorithms can be selected via Terraform [variables](https://github.com/serverless-ca/terraform-aws-ca/blob/main/variables.tf):
 `RSA_2048, RSA_3072, RSA_4096, ECC_NIST_P256, ECC_NIST_P384, ECC_NIST_P521`
 
 ### How are the CA private keys protected?

docs/getting-started.md

@@ -1,7 +1,5 @@
 # Getting Started
 
-| [Home](index.md) | [Getting Started](getting-started.md) | [Client Certificates](client-certificates.md) | [CRL](revocation.md) | [CA Cert Locations](locations.md) | [Options](options.md) | [Automation](automation.md) | [Security](security.md) | [FAQ](faq.md) |
-
 ## Objectives
 By the end of this tutorial you will have:
 * created a serverless CA in your own AWS account
@@ -34,14 +32,14 @@ terraform apply
 
 To initialise the CA, in the AWS console, select Step Furnctions, and execute the CA workflow
 
-<img src="images/step-function.png" width="300">
+![Alt text](images/step-function.png?raw=true "CA Step Function")
 
 Alternatively wait for the next scheduled run of the Step Function which may take up to 24 hours
 
 ## View CA certificates and CRLs
 CA certificates and CRLs are available in the 'external' S3 bucket created by Terraform
 
-<img src="images/external-s3.png" width="400">
+![Alt text](images/external-s3.png?raw=true "External S3 bucket")
 
 * download the Root CA and issuing CA
 * import and trust both CA certificates
@@ -75,14 +73,14 @@ python utils/client-cert.py
 ## View client certificate
 View the client certificate `serverless-cert.crt` with your operating system cert viewer
 
-<img src="images/trusted-cert.png" width="300">
-<img src="images/cert-details.png" width="300">
-<img src="images/cert-chain.png" width="300">
+![Alt text](images/trusted-cert.png?raw=true "Client certificate")
+![Alt text](images/cert-details.png?raw=true "Client certificate details")
+![Alt text](images/cert-chain.png?raw=true "Client certificate chain")
 
 ## Create and view server certificate
 Create a server certificate with Subject Alternative Names
 ```
 python utils/server-cert.py
 ```
-<img src="images/server-cert-1.png" width="300">
-<img src="images/server-cert-2.png" width="300">
+![Alt text](images/server-cert-1.png?raw=true "Client certificate")
+![Alt text](images/server-cert-2.png?raw=true "Client certificate details")

docs/index.md

@@ -1,12 +1,11 @@
 # Terraform module for Certificate Authority on AWS
-| [Getting Started](getting-started.md) | [Client Certificates](client-certificates.md) | [CRL](revocation.md) | [CA Cert Locations](locations.md) | [Options](options.md) | [Automation](automation.md) | [Security](security.md) | [FAQ](faq.md) |  
 
 * Serverless Certificate Authority typically $50 per year
 * [Equivalent cost using AWS Private CA around $10,000 per year](./faq.md#how-did-you-work-out-the-cost-comparison-with-aws-private-ca)
 * 100% serverless
 * CA private keys stored in [FIPS 140-2 level 3 certified hardware](https://aws.amazon.com/about-aws/whats-new/2023/05/aws-kms-hsm-fips-security-level-3)
 * Wide range of [configuration options](options.md)
-* Open source with [Apache 2.0 license](../LICENSE.md)
+* Open source with [Apache 2.0 license](https://github.com/serverless-ca/terraform-aws-ca/blob/main/LICENSE.md)
 
 ![Alt text](images/ca-architecture-options.png?raw=true "CA architecture")
 

docs/locations.md

@@ -1,5 +1,4 @@
 # CRL and CA Cert Locations
-| [Home](index.md) | [Getting Started](getting-started.md) | [Client Certificates](client-certificates.md) | [CRL](revocation.md) | [CA Cert Locations](locations.md) | [Options](options.md) | [Automation](automation.md) | [Security](security.md) | [FAQ](faq.md) |  
 
 In all cases, CRLs and CA certificates are published to the `external` S3 bucket, which is not directly accessible from the public Internet.
 
@@ -9,14 +8,14 @@ If you choose to publish CRLs and CA certificates:
 * Authority Information Access (AIA) extension added to issued certificates with CA certificate location
 * CRL Distribution Point (CDP) extension added to issued certificates with CRL location
 * CRLs are published to CloudFront
-* For details on how to revoke a certificate, see [CRL](crl.md)
+* For details on how to revoke a certificate, see [Revocation](revocation.md)
 * File names are constructed using the `project_name` and `environment` Terraform variables
 
-See [CRL](crl.md) for details of how to enable public CRLs and CA certs.
+See [Revocation](revocation.md) for details of how to enable public CRLs and CA certs.
 
 ## Example locations
-* locations below for an [example deployment](../examples/rsa-public-crl) in the [terraform-aws-ca](https://github.com/q-solution/terraform-aws-ca) repository.
-* infrastructure deployed by a [GitHub Actions test workflow](../.github/workflows/rsa_public_crl.yml) in the [terraform-aws-ca](https://github.com/q-solution/terraform-aws-ca) repository.
+* locations below for an [example deployment](https://github.com/serverless-ca/terraform-aws-ca/blob/main/examples/rsa-public-crl/README.md) in the [terraform-aws-ca](https://github.com/q-solution/terraform-aws-ca) repository.
+* infrastructure deployed by a [GitHub Actions test workflow](https://github.com/serverless-ca/terraform-aws-ca/blob/main/.github/workflows/rsa_public_crl.yml) in the [terraform-aws-ca](https://github.com/q-solution/terraform-aws-ca) repository.
 * `project_name` is `serverless` and `environment` is either `dev` (not deployed, for illustration only) or `prod` (deployed)
 * environment suffix automatically omitted for `prod` or `prd` environment
 

docs/options.md

@@ -1,26 +1,25 @@
 # Configuration Options
-| [Home](index.md) | [Getting Started](getting-started.md) | [Client Certificates](client-certificates.md) | [CRL](revocation.md) | [CA Cert Locations](locations.md) | [Options](options.md) | [Automation](automation.md) | [Security](security.md) | [FAQ](faq.md) |  
 
-The serverless CA is highly configurable by adjusting values of Terraform variables in [variables.tf](../variables.tf). Principal configuration options:
+The serverless CA is highly configurable by adjusting values of Terraform variables in [variables.tf](https://github.com/serverless-ca/terraform-aws-ca/blob/main/variables.tf). Principal configuration options:
 
 
 ## Revocation and GitOps
 By default, certificate revocation and GitOps are disabled. If you followed the [Getting Started](./getting-started.md) guide you'll already have enabled GitOps:
 * add a subdirectory to your repository with the same name as the value of the Terraform variable `env`, e.g. `dev`, `prd`
-add files and subdirectory following [the rsa-public-crl example](../examples/rsa-public-crl/README.md)
+add files and subdirectory following [the rsa-public-crl example](https://github.com/serverless-ca/terraform-aws-ca/blob/main/examples/rsa-public-crl/README.md)
 * change the value of Terraform variable `cert_info_files` to  `["tls", "revoked", "revoked-root-ca"]`
 * apply Terraform
 * you can now revoke a certificate as described in [Revocation](revocation.md)
 
 ## Public CRL and CA certs
 
-See details in [CRL](revocation.md) and [CA Cert Locations](locations.md).
+See details in [Revocation](revocation.md) and [CA Cert Locations](locations.md).
 
 *Default setting: not enabled*
 
 ## CA key algorithms
 
-The following algorithms can be selected via Terraform [variables](../variables.tf):
+The following algorithms can be selected via Terraform [variables](https://github.com/serverless-ca/terraform-aws-ca/blob/main/variables.tf):
 `RSA_2048, RSA_3072, RSA_4096, ECC_NIST_P256, ECC_NIST_P384, ECC_NIST_P521`
 
 *Default setting: `ECC_NIST_P384` (Root CA), `ECC_NIST_P256` (Issuing CA)*
@@ -29,4 +28,7 @@ The following algorithms can be selected via Terraform [variables](../variables.
 
 CloudWatch log subscription filters can be used to send log events to a central S3 log bucket, from which they can be forwarded to a SIEM.
 
-*Default setting: not enabled*
+*Default setting: not enabled*
+
+### CRL lifetime and CRL publication frequency
+The default setting for CRL lifetime of 1 day should be appropriate for most use cases. However, the Issuing CA CRL lifetime, Root CA CRL lifetime, and publication frequency can be adjusted as detailed in [Revocation](revocation.md#crl-lifetime).

docs/revocation.md

@@ -1,13 +1,14 @@
-# Revocation
-| [Home](index.md) | [Getting Started](getting-started.md) | [Client Certificates](client-certificates.md) | [CRL](revocation.md) | [CA Cert Locations](locations.md) | [Options](options.md) | [Automation](automation.md) | [Security](security.md) | [FAQ](faq.md) |  
+# Certificate Revocation
+
+![Alt text](images/crl.png?raw=true "Certificate Revocation List")
 
 * Certificates can be revoked using a Certificate Revocation List (CRL)
 * Online Certificate Status Protocol (OCSP) is not supported
 
 ## CRL publication
 CRLs are published to `external` S3 bucket, not directly accessible from public Internet
 
-To publish publicly, set `public_crl` to `true` and provide `hosted_zone_id` and `hosted_zone_name` in [Terraform variables](../variables.tf).
+To publish publicly, set `public_crl` to `true` and provide `hosted_zone_id` and `hosted_zone_name` in [Terraform variables](https://github.com/serverless-ca/terraform-aws-ca/blob/main/variables.tf).
 
 Applying Terraform will result in:
 * CRLs published to a public URL via CloudFront
@@ -21,7 +22,7 @@ CRL locations are detailed in [CA Cert Locations](locations.md)
 ## Enable certificate revocation
 CRLs are always published, however the ability to revoke a certificate needs to be enabled. If you followed the [Getting Started](getting-started.md) guide, you'll already have done this:
 * add a subdirectory to your repository with the same name as the value of the Terraform variable `env`, e.g. `dev`, `prd`
-add files and subdirectory following the [rsa-public-crl example](../examples/rsa-public-crl/README.md)
+add files and subdirectory following the [rsa-public-crl example](https://github.com/serverless-ca/terraform-aws-ca/blob/main/examples/rsa-public-crl/README.md)
 * change the value of Terraform variable `cert_info_files` to  `["tls", "revoked", "revoked-root-ca"]`
 * apply Terraform
 

docs/security.md

@@ -1,5 +1,4 @@
 # Security
-| [Home](index.md) | [Getting Started](getting-started.md) | [Client Certificates](client-certificates.md) | [CRL](revocation.md) | [CA Cert Locations](locations.md) | [Options](options.md) | [Automation](automation.md) | [Security](security.md) | [FAQ](faq.md) |  
 
 It's very important to implement your certificate authority (CA) in a secure way:
 
@@ -26,4 +25,4 @@ The security of any CA is dependent on the protection of CA private keys. AWS KM
 
 Secure operation of AWS services such as KMS rely on AWS upholding its side of the [AWS Shared Responsibility Model](https://aws.amazon.com/compliance/shared-responsibility-model/).
 
-The above information is provided to assist you in assuring the security of your CA. However, the authors accept no responsibility for your CA being implemented and operated in a secure manner, in according with the [License](../LICENSE.md).
+The above information is provided to assist you in assuring the security of your CA. However, the authors accept no responsibility for your CA being implemented and operated in a secure manner, in according with the [License](https://github.com/serverless-ca/terraform-aws-ca/blob/main/LICENSE.md).