diff --git a/.github/workflows/github_pages.yml b/.github/workflows/github_pages.yml new file mode 100644 index 00000000..2824c05f --- /dev/null +++ b/.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 + \ No newline at end of file diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 9bc21195..9e5722dd 100644 --- a/.github/workflows/pages.yml +++ b/.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: diff --git a/docs/_config.yml b/docs/_config.yml deleted file mode 100644 index 245d6aac..00000000 --- a/docs/_config.yml +++ /dev/null @@ -1,5 +0,0 @@ -title: Terraform AWS CA -description: Terraform module for serverless Certificate Authority on AWS -remote_theme: pages-themes/cayman@v0.2.0 -plugins: - - jekyll-remote-theme # add this line to the plugins list if you already have one \ No newline at end of file diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html deleted file mode 100644 index 4d1fa86f..00000000 --- a/docs/_layouts/default.html +++ /dev/null @@ -1,41 +0,0 @@ - - - - - - {% seo %} - - - - - - - {% include head-custom.html %} - - - - - - -
- {{ content }} - - -
- - \ No newline at end of file diff --git a/docs/assets/css/style.scss b/docs/assets/css/style.scss deleted file mode 100644 index b55fe890..00000000 --- a/docs/assets/css/style.scss +++ /dev/null @@ -1 +0,0 @@ -@import "{{ site.theme }}"; \ No newline at end of file diff --git a/docs/automation.md b/docs/automation.md index 03034ce1..b8c38a9b 100644 --- a/docs/automation.md +++ b/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: - +![Alt text](images/deployment-workflow.png?raw=true "GitHub Actions workflow") The principal steps are: diff --git a/docs/client-certificates.md b/docs/client-certificates.md index 8dabce97..23f67038 100644 --- a/docs/client-certificates.md +++ b/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 - +![Alt text](images/dynamodb-test-server-cert.png?raw=true "DynamoDB query") + * select the issued certificate by clicking on the link - + +![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)** diff --git a/docs/faq.md b/docs/faq.md index 393d3460..eaa9d612 100644 --- a/docs/faq.md +++ b/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? diff --git a/docs/getting-started.md b/docs/getting-started.md index 87a22f25..cce24cee 100644 --- a/docs/getting-started.md +++ b/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 - +![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 - +![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 - - - +![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 ``` - - +![Alt text](images/server-cert-1.png?raw=true "Client certificate") +![Alt text](images/server-cert-2.png?raw=true "Client certificate details") diff --git a/docs/images/crl.png b/docs/images/crl.png new file mode 100644 index 00000000..0c068b9c Binary files /dev/null and b/docs/images/crl.png differ diff --git a/docs/index.md b/docs/index.md index 684c1101..1a42d636 100644 --- a/docs/index.md +++ b/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") diff --git a/docs/locations.md b/docs/locations.md index ec43b582..c12d9259 100644 --- a/docs/locations.md +++ b/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 diff --git a/docs/options.md b/docs/options.md index fa86c266..24ced868 100644 --- a/docs/options.md +++ b/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* \ No newline at end of file +*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). \ No newline at end of file diff --git a/docs/revocation.md b/docs/revocation.md index 47ef584e..c5a2b452 100644 --- a/docs/revocation.md +++ b/docs/revocation.md @@ -1,5 +1,6 @@ -# 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 @@ -7,7 +8,7 @@ ## 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 diff --git a/docs/security.md b/docs/security.md index c1545f37..258e7c38 100644 --- a/docs/security.md +++ b/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). diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..521e3456 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,52 @@ +site_name: Serverless CA on AWS +repo_name: serverless-ca/terraform-aws-ca +repo_url: https://github.com/serverless-ca/terraform-aws-ca +edit_uri: edit/main/docs/ +use_directory_urls: true +theme: + name: material + icon: + logo: material/rocket-launch-outline + palette: + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/weather-night + name: Switch to system preference + - scheme: default + toggle: + icon: material/weather-sunny + name: Switch to dark mode + features: + - navigation.instant + - navigation.instant.progress + - navigation.tracking + - pymdownx.snippets + - navigation.footer + - toc.integrate + - navigation.top + - search.suggest + - search.highlight + - content.tabs.link + - content.code.annotation + - content.code.copy + language: en + +extra: + status: + new: Recently added + deprecated: Deprecated + +nav: + - Introduction: index.md + - Getting started: getting-started.md + - Automation: automation.md + - CA Certificate locations: locations.md + - Client certificates: client-certificates.md + - Configuration options: options.md + - FAQs: faq.md + - Revocation: revocation.md + - Security: security.md + - Terraform reference: reference.md + + \ No newline at end of file diff --git a/requirements-dev.txt b/requirements-dev.txt index d460bef0..95d6acc0 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -7,6 +7,7 @@ asn1crypto == 1.5.1 certvalidator == 0.11.1 prospector==1.10.3 bandit==1.7.5 +mkdocs-material==9.5.13 pytest==7.4.4 validators==0.22.0 requests==2.31.0