|
|
## Assumptions
|
|
|
1. communication between server and agent is encrypted
|
|
|
2. agent and server authenticate each other
|
|
|
3. the whole solution does not involve much manual intervention from the administrator (e.g. generation of certs for authentication should be automatic)
|
|
|
|
|
|
## Overview
|
|
|
|
|
|
Communication between server and agent are realized using gRPC protocol. gRPC protocol allows using certificates for authentication of both sides and encryption of transmitted messaged.
|
|
|
|
|
|
More details:
|
|
|
- https://grpc.io/docs/guides/auth/
|
|
|
- https://github.com/grpc/grpc-go/blob/master/Documentation/grpc-auth-support.md
|
|
|
- https://itnext.io/practical-guide-to-securing-grpc-connections-with-go-and-tls-part-1-f63058e9d6d1
|
|
|
- https://itnext.io/practical-guide-to-securing-grpc-connections-with-go-and-tls-part-2-994ef93b8ea9
|
|
|
- https://bbengfort.github.io/programmer/2017/03/03/secure-grpc.html
|
|
|
|
|
|
## Authentication
|
|
|
|
|
|
Server at first startup generates:
|
|
|
- server private key
|
|
|
- server certificate with public key
|
|
|
|
|
|
Server certificate is set to be able to sign other certificates. It will be used to sign agents' certificates.
|
|
|
Server certificate is delivered to agents so they can recognize and accept connections from the server.
|
|
|
|
|
|
When a new agent is being added to the server then an agent private key and agent certificate
|
|
|
are being generated by the server. Agent certificate is being signed by server private key.
|
|
|
Server stores agent's private key and certificate to use them to authenticate agent
|
|
|
during connecting to the agent. They are also delivered to agent so they can be used by the agent to present its identity. This way the server can recognize that the agent is well known and connection can be established.
|
|
|
|
|
|
## Encryption
|
|
|
|
|
|
Encryption is automatically established during preparing connection using gRPC with proper TLS configuration.
|
|
|
|
|
|
## Agent Keys Delivery
|
|
|
|
|
|
When a new agent is being added to the server then a private key and a certificate is being generated for this agent. They need to be delivered to the agent.
|
|
|
|
|
|
The procedure looks as follows:
|
|
|
1. Administator logs into agent machine and downloads agent installation script and starts it: `curl https:/stork/agent-install.sh | sudo bash`. Downloaded script contains a URL address of the server.
|
|
|
1. The script prompts admin for authentication against Stork server.
|
|
|
1. The script downloads proper deb or rpm package for current system and install it.
|
|
|
1. The script invokes agent in special mode to register local machine in Stork server using ReST API over secure HTTPS and using credentials provided by admin.
|
|
|
1. The server generates a private key and a certificate for the machine and its address. The address is put in `Common Name` and in `Subject Alternative Name` in the certificate. The server recognizes the machine using this address in the certificate.
|
|
|
1. Agent (still in this special mode) fetches generated private key and certificate and stores them in `/etc/stork` for further usage using ReST request and exits.
|
|
|
1. Administrator starts agent service (using systemctl enable and start).
|
|
|
1. From that moment gRPC connection from the server to the agent can be established. There are used mutual authentication and encryption.
|
|
|
|
|
|
```mermaid
|
|
|
sequenceDiagram
|
|
|
participant Admin
|
|
|
participant Script
|
|
|
participant Agent
|
|
|
participant Server
|
|
|
Admin->>Server: Download Agent install Scripts [HTTPS]
|
|
|
Admin->>Script: Invoke the Script, prompt for credentials from Admin
|
|
|
Script->>Server: Download RPM/deb and install it [HTTPS]
|
|
|
Script->>Agent: Register machine
|
|
|
Agent->>+Server: Register machine, generate private key and certificate
|
|
|
Server-->>-Agent: Generated key and cert
|
|
|
Note over Agent: Store key and cert
|
|
|
Note over Admin: Enable and start Agent service
|
|
|
|
|
|
``` |
|
|
\ No newline at end of file |