Skip to content
👋 Docs demonstrating mutual TLS configurations in various technologies
JavaScript Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/ISSUE_TEMPLATE
ci Fix basename in logo asset copy Sep 23, 2019
docs Fix accidentally commented line Oct 2, 2019
pages
src
test Merge pull request #44 from smallstep/doc-mysql Oct 1, 2019
webpack Use CDN-hosted logos in production mode Aug 26, 2019
.gitignore
.prettierrc Wire up basic local dev experience Aug 12, 2019
.travis.yml
LICENSE.txt Add appropriate licenses Aug 14, 2019
README.md Update README.md Oct 2, 2019
babel.config.js
jest.config.js
next.config.js
package.json
yarn.lock Match remark-parse version to the one in react-markdown (bundle size) Sep 3, 2019

README.md

Hello mTLS

This package contains documentation on how to configure a broad array of technologies to perform mutual TLS. It is part of the Hello mTLS project, designed to raise developer awareness about public key infrastructure as a potential solution to common security problems.

If you notice any outdated, missing, or errant docs, pull requests are strongly encouraged!

Contributing

Documentation for each technology lives in its corresponding directory in the docs/ folder.

To get rolling on local development, clone this repository and start the local dev server:

$ yarn install
$ yarn start

You will be able to preview all changes at http://localhost:3000.

Adding new technologies

If you are adding a new technology, your best bet is to refer to existing configurations in this repository, but here is a high-level breakdown of each directory's contents.

config.yaml

This file configures basic information like the technology name and external links to documentation.

logo.png

This is a 256 x 256px transparent PNG of the technology's logo. If missing, a standard placeholder will be used.

topics/

Several optional markdown files provide prose describing how to perform different aspects of mTLS using the technology:

  • server_auth.md — Server TLS authentication
  • client_auth.md — Client TLS authentication
  • client.md — Client requests using TLS
  • renewal.md — TLS cetificate renewal

Properties with corresponding names in the topics object in config.yaml also accept a links array for any relevant external resources.

If your documentation makes use of the name of a certificate's identity, its certificate filename, its private key filename, or the root certificate filename, please use these template tokens. They will be interpolated with the appropriate values at build time in different contexts:

  • {{ server_name }} — Name of the identity like server.internal.net
  • {{ server_cert }} — Filename of the server's certificate like server.crt
  • {{ server_key }} — Filename of the server's private key like server.key
  • {{ server_port }} — Port number that that the server binds in the server auth docs
  • {{ client_name }} — Name of the identity like clientuser
  • {{ client_cert }} — Filename of the client's certificate like client.crt
  • {{ client_key }} — Filename of the client's private key like client.key
  • {{ ca_cert }} — Filename of the root CA certificate like ca.crt

Do not use markdown headlines.

Testing changes

Run yarn test locally to test that your changes are valid before opening a pull request.

License

Code in this repository is licensed under Apache License, Version 2.0.

All documentation content is licensed under Creative Commons Attribution 4.0 International License.

Creative Commons License

Support

Please don't hesitate to reach out on our Gitter with any questions.

You can’t perform that action at this time.