Skip to content
This repository has been archived by the owner on Nov 8, 2022. It is now read-only.

Commit

Permalink
Address comments in review
Browse files Browse the repository at this point in the history
  • Loading branch information
@marcin-ol
marcin-ol committed Jun 12, 2017
1 parent b1b8610 commit 92361be
Showing 1 changed file with 60 additions and 60 deletions.
120 changes: 60 additions & 60 deletions docs/SETUP_TLS_CERTIFICATES.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,17 +4,17 @@

- [Setting up TLS certificates for secure plugin communication in Snap](#setting-up-tls-certificates-for-secure-plugin-communication-in-snap)
- [Overview](#overview)
- [Remarks](#remarks)
- [Disclaimer](#disclaimer)
- [Obtaining self-signed certificates](#obtaining-self-signed-certificates)
- [Remarks](#remarks-1)
- [Notes](#notes)
- [Procedure](#procedure)
- [Obtaining legitimate certificate from a public CA Let's Encrypt](#obtaining-legitimate-certificate-from-a-public-ca-lets-encrypt)
- [Obtaining legitimate certificate from a public CA: Let's Encrypt](#obtaining-legitimate-certificate-from-a-public-ca-lets-encrypt)
- [Prerequisites](#prerequisites)
- [Remarks](#remarks-2)
- [Notes](#notes-1)
- [Procedure](#procedure-1)
- [Installing certificates in system (Ubuntu, CentOS)](#installing-certificates-in-system-ubuntu-centos)
- [Installing root certificate in Ubuntu](#installing-root-certificate-in-ubuntu)
- [Installing root certificate in Centos](#installing-root-certificate-in-centos)
- [Installing root certificate in CentOS](#installing-root-certificate-in-centos)
- [Testing TLS-secured plugin communication in local setup](#testing-tls-secured-plugin-communication-in-local-setup)
- [Starting a telemetry workflow:](#starting-a-telemetry-workflow)

Expand All @@ -25,90 +25,90 @@

This document provides instructions on how to obtain certficates to evaluate TLS-secured plugin communication in Snap.

Following routines are described:
- obtaining self-signed certificates for evaluation in local test environment,
- obtaining legitimate certificate from a certain CA authority,
- installing root certificate in OS for validating endpoints' certificates,
- starting telemetry workflow with secured plugin communication.
The following routines are described:
- Obtaining self-signed certificates for evaluation in local test environment
- Obtaining legitimate certificate from a public CA: Let's Encrypt
- Installing root certificate in OS for validating endpoints' certificates
- Starting telemetry workflow with secured plugin communication.

### Remarks
- This document can't be considered a definite guide to obtaining certificates. It aims only as guiding user in acquiring a certificate.
- This guide doesn't indicate how to handle certificate revocation as that service is not yet supported in Snap.
- Every organization has to review its requirements prior to obtaining certificates or setting up any secure communication scheme.
### Disclaimer
- This document is not intended to be a definite guide to obtaining certificates. It aims only as a guide for user to understand how Snap works with certificates. Each organization has to review its own requirements prior to obtaining certificates or setting up any secure communication scheme
- Note that this guide doesn't cover how to handle certificate revocation, as that service is not supported yet in Snap. While it is not on our roadmap yet, you are more than welcome to influence the solution by [posting a feature request](https://github.com/intelsdi-x/snap/issues).

## Obtaining self-signed certificates

This section describes how to obtain certificates signed by a local CA.

In the course of this guide user will establish a local CA, becoming able to establish local chains of trust. Thus the user will be able to generate certificates for Snap plugins and Snap daemon (`snapteld`) that all share common trust root.
In the course of this guide user will establish a local CA, becoming able to establish local chains of trust. Thus the user will be able to generate certificates for Snap plugins and Snap daemon (`snapteld`) that share a common trust root.

### Remarks
### Notes

- CA private key needs to be protected, possibly on a dedicated machine or media.
- Obtained certificates won't be valid outside local setup.
- CA private key should be protected, possibly on a dedicated machine or media
- Obtained certificates won't be valid outside local setup

### Procedure

1. Install tool [certstrap](https://github.com/square/certstrap) for generating test certificates. Further steps will assume that `certstrap` is available under `$PATH` location.
1. Install [certstrap](https://github.com/square/certstrap) for generating test certificates. Further steps will assume that `certstrap` is available under `$PATH` location.
1. Generate root CA certificate:
```
certstrap init --cn "snaptest-ca" --o "snaptest" --ou "ca" --key-bits 2048 --years 1 --passphrase '<ca-secure-passphrase>'
```
Relevant files:
* `./out/snaptest-ca.key` - CA's private key, encrypted with `<ca-secure-passphrase>`; needs to be protected from unauthorized access,
* `./out/snaptest-ca.crt` - CA's public certificate, (a certificate root).
* `./out/snaptest-ca.key` - CA's private key, encrypted with `<ca-secure-passphrase>`; needs to be protected from unauthorized access
* `./out/snaptest-ca.crt` - CA's public certificate, (a certificate root)
1. Generate server certificate and key to use by plugins:
```
certstrap request-cert --cn "snaptest-srv" --ip "127.0.0.1" --domain "localhost" --passphrase '' --key-bits 2048 --o "snaptest" --ou "server"
certstrap sign "snaptest-srv" --CA "snaptest-ca" --passphrase '<ca-secure-passphrase>' --years 1
```
This will produce a private key certificate file necessary to establish secure TLS channel on server. Server's private key file should not be passphrase-protected (or each plugin would have to ask for passphrase on start).
These steps will produce a private key certificate file necessary to establish secure TLS channel on server. Server's private key file should not be passphrase-protected (or each plugin would have to ask for passphrase on start), thus the first step specifies empty passphrase expliclitly.
Note that the second step (signing a private key) passes `<ca-secure-passphrase>` to access CA's private key.
Relevant files:
* `./out/snaptest-srv.key` - server's private key,
* `./out/snaptest-srv.crt` - server's public certificate.
1. Generate client certificate and key to use by framework:
* `./out/snaptest-srv.key` - server's private key
* `./out/snaptest-srv.crt` - server's public certificate
1. Generate client certificate and key to be used by framework:
```
certstrap request-cert --cn "snaptest-cli" --ip "127.0.0.1" --domain "localhost" --passphrase '' --key-bits 2048 --o "snaptest" --ou "client"
certstrap sign "snaptest-cli" --CA "snaptest-ca" --passphrase '<ca-secure-passphrase>' --years 1
```
This will produce a private key certificate file necessary to securely connect to plugins. Client's private key file should not be passphrase-protected.
This will produce a private key certificate file necessary to securely connect to plugins. Client's private key file should not be passphrase-protected, thus the first step specifies empty passphrase explicitly. Note that the second step (signing a private key) passes `<ca-secure-passphrase>` to access CA's private key.
Relevant files:
* `./out/snaptest-cli.key` - client's private key,
* `./out/snaptest-cli.crt` - client's public certificate.
* `./out/snaptest-cli.key` - client's private key
* `./out/snaptest-cli.crt` - client's public certificate

Files that need to be given at plugin startup:
* `snaptest-ca.crt` - CA's certificate,
* `snaptest-srv.key` - server's private key file,
* `snaptest-srv.crt` - server's certificate file.
* `snaptest-ca.crt` - CA's certificate
* `snaptest-srv.key` - server's private key file
* `snaptest-srv.crt` - server's certificate file

Files that need to be given at `snapteld` startup:
* `snaptest-ca.crt` - CA's certificate,
* `snaptest-cli.key` - framework's private key file,
* `snaptest-cli.crt` - framework's certificate file.
* `snaptest-ca.crt` - CA's certificate
* `snaptest-cli.key` - framework's private key file
* `snaptest-cli.crt` - framework's certificate file

## Obtaining legitimate certificate from a public CA Let's Encrypt
## Obtaining legitimate certificate from a public CA: Let's Encrypt

This section describes how to obtain a certificate from CA authority. Example will be based on [Let's encrypt](https://letsencrypt.org/) public CA service.

In general, obtaining a TLS certificate involves:
* on customer side: issuing request to CA authority, specifying domain name and contact information,
* on CA side: validating the customer's title to the requested domain.
* On customer side: issuing request to CA authority, specifying domain name and contact information
* On CA side: validating the customer's title to the requested domain

This guide will show how to obtain certificate for sample domains.

### Prerequisites

There's no way around registering a physical domain. In this walkthrough we'll assume that domains `frodo.buthey.net` and `bilbo.buthey.net` were registered and they're mapped to actual machines (VM or physical).
There's no way around the need to register a domain name to use this example. In this walkthrough we'll assume that domains `frodo.buthey.net` and `bilbo.buthey.net` were registered and their DNS records map to actual machines (VM or physical).

### Remarks
### Notes

At the moment there's no way to use domain-bound certificates directly in Snap. That's a subject of ongoing research and design. As soon as this situation changes, this document will be updated.
At the moment there's no way to use domain-bound certificates directly in Snap. That's a subject of ongoing implementation, and should be addressed by intelsdi-x/snap-plugin-lib-go#85. As soon as implementation is complete, this document will be updated.

### Procedure

1. Connect via SSH to a machine mapped to the domain `frodo.buthey.net`.
1. Make sure that machine has WWW ports open for listening: `80` and `443`.
1. Install [certbot](https://certbot.eff.org/), as directed by Let's encrypt instructions.
1. Connect via SSH to a machine mapped to the domain `frodo.buthey.net`
1. Make sure that machine has WWW ports open for listening: `80` and `443`
1. Install [certbot](https://certbot.eff.org/), as directed by Let's encrypt instructions:
On Ubuntu:
```
sudo add-apt-repository ppa:certbot/certbot
Expand All @@ -129,17 +129,17 @@ At the moment there's no way to use domain-bound certificates directly in Snap.

```
Resulting files:
* `frodo.buthey.net-privkey.pem` - private key file for domain `frodo.`,
* `frodo.buthey.net-cert.pem` - certificate file for domain `frodo.`,
* `frodo.buthey.net-chain.pem` - a certificate chain representing Let's encrypt CA (a certificate root).
* `frodo.buthey.net-privkey.pem` - private key file for domain `frodo.`
* `frodo.buthey.net-cert.pem` - certificate file for domain `frodo.`
* `frodo.buthey.net-chain.pem` - a certificate chain representing Let's encrypt CA (a certificate root)
## Installing certificates in system (Ubuntu, CentOS)
This guide shows how to install root CA certificates in system. Having root CA certificates installed in system reduces complexity of TLS setup.
### Installing root certificate in Ubuntu
1. Obtain a certificate root file (e.g. `snaptest-CA.crt` from the guides in this document).
1. Obtain a certificate root file (e.g. `snaptest-CA.crt` from the guides in this document)
1. Install the certificate in the system:
```
sudo cp snaptest-ca.crt /usr/local/share/ca-certificates/
Expand All @@ -156,9 +156,9 @@ This guide shows how to install root CA certificates in system. Having root CA c
173 added, 0 removed; done.
```
### Installing root certificate in Centos
### Installing root certificate in CentOS
1. Obtain a certificate root file (e.g. `snaptest-ca.crt` from the guides in this document).
1. Obtain a certificate root file (e.g. `snaptest-ca.crt` from the guides in this document)
1. Install the certificate tooling and certificate in the system:
```
yum install ca-certificates
Expand All @@ -170,35 +170,35 @@ This guide shows how to install root CA certificates in system. Having root CA c
## Testing TLS-secured plugin communication in local setup
We'll assume the following files are all available:
* `snaptest-ca.crt` - certificate root - installed in system,
* `snaptest-srv.key` - server's private key file,
* `snaptest-srv.crt` - server's certificate file,
* `snaptest-cli.key` - framework's private key file,
* `snaptest-cli.crt` - framework's certificate file.
* `snaptest-ca.crt` - certificate root - installed in system
* `snaptest-srv.key` - server's private key file
* `snaptest-srv.crt` - server's certificate file
* `snaptest-cli.key` - framework's private key file
* `snaptest-cli.crt` - framework's certificate file
### Starting a telemetry workflow:
1. Start new shell session and execute `snapteld` with certificate and key generated for client:
1. Start a new shell session and execute `snapteld` with certificate and key generated for client:
```
snapteld -t 0 -l 1 --tls-cert=/tmp/snaptest-cli.crt --tls-key=/tmp/snaptest-cli.key
```
1. Load a plugin
Start new shell session and load plugin built with [snap-plugin-lib-go](https://github.com/intelsdi-x/snap-plugin-lib-go), e.g. `snap-plugin-collector-rand` from `snap-plugin-lib-go` examples:
Start a new shell session and load plugin built with [snap-plugin-lib-go](https://github.com/intelsdi-x/snap-plugin-lib-go), e.g. `snap-plugin-collector-rand` from `snap-plugin-lib-go` examples:
```
snaptel plugin load --plugin-cert=/tmp/snaptest-srv.crt --plugin-key=/tmp/snaptest-srv.key snap-plugin-collector-rand
```
1. Start a sample task and watch the output:
1. Create a sample task and watch the output:
```
snaptel task create -t sample-task.json

snaptel task watch 167384ad-7643-43ef-930a-18455f5307a0
snaptel task watch <task_id>
```
Sample output:
```
snaptel task create -t task0.json
snaptel task create -t sample-task.json
Task created
ID: 167384ad-7643-43ef-930a-18455f5307a0
Name: Task-167384ad-7643-43ef-930a-18455f5307a0
Expand All @@ -216,7 +216,7 @@ We'll assume the following files are all available:
{
"max-failures": 10,
"schedule": {
"interval": "3s",
"interval": "3s", `
"type": "simple"
},
"version": 1,
Expand Down

0 comments on commit 92361be

Please sign in to comment.