Merge pull request #25 from ST2Projects/tk/6/documentation

neo1908 · web-flow · commit 5bb6bfb097d7 · 2022-10-26T16:31:11.000+01:00
Update readme and add api-docs.yml
diff --git a/.goreleaser.yml b/.goreleaser.yml
@@ -19,7 +19,6 @@ archives:
       - samples
       - README.md
       - LICENSE
-      - install/Makefile
 checksum:
   name_template: 'checksums.txt'
 snapshot:
diff --git a/README.md b/README.md
@@ -2,7 +2,17 @@
 
 A simple to use and deploy SSH CA server.
 
-**This is a Work In Progress** - the project is in its early days. It is functional and I'm using it for my own hosts **but** you use it at your own risk
+**This is a Work In Progress** - the project is in its early days. It is functional, and I'm using it for my own hosts, **but** you use it at your own risk
+
+## Goals
+
+There are a couple of SSH CA servers out there - I have found them all difficult to use and have specific platform
+requirements. This projects aims to:
+
+- Be simple to use and deploy
+- Use sensible secure defaults
+
+I'm also using this project to learn go, so if you come across it and notice something dumb please let me know by opening an issue!
 
 ## Installation
 
@@ -17,12 +27,14 @@ mkdir /opt/sentinel
 # Copy archive into directory
 tar xvzf ssh-sentinel-server_$VERSION_$ARCH.tar.gz
 
-make install
+cp samples/config.json .
+cp samples/ssh-sentinel.service /etc/systemd/system/
+systemctl daemon-reload
 ```
 
-## Configuration
+### Configuration
 
-Configuration is defined in the `config.json`. Properties are explained below. All paths are relative to the `resources` directory
+Configuration is defined in the `config.json`. Properties are explained below. Full paths must be provided
 
 - `CAPrivateKey` - Name of the CA private key. The key must be unencrypted - a future enhancement will allow encrypted keys
 - `CAPublicKey` - Name of the CA public key.
@@ -32,14 +44,68 @@ Configuration is defined in the `config.json`. Properties are explained below. A
 - `db.password` - Password of the DB user
 - `db.connection` - Connection URL for the DB. For sqlite3 this is a file path
 - `db.dbName` - Name of the DB
+- `tls.local` - When set to `true` the server will generate a local TLS certificate. When `false` the server will generate a Let's Encrypt cert
+- `tls.certDir` - Directory in which the generated certificate will be generated
+- `tls.certDomains` - A list of domains to be included in the certificate.
+- `tls.certEmail` - Needed when generating a certificate with let's encrypt
+- `tls.dnsProvider` - Only `cloudflare` is supported at the moment. A future release will open up support for other providers
+- `tls.dnsAPIToken` - The zone API token from cloudflare
 
-## Goals
+### Generate a CA
 
-There are a couple of SSH CA servers out there - I have found them all difficult to use and have specific platform
-requirements. This projects aims to:
+You can generate a SSH CA with `ssh-keygen`. I suggest using ECDSA keys as they are smaller but this is not a requirement.
 
-- Be simple to use and deploy
-- Use sensible secure defaults
+```shell
+ssh-keygen -t ed25519 -f sentinel-ca -C sentinel-CA
+```
+
+**The key must not have a password** - this will be improved in a future release
+
+### Adding users
+
+Once you have the service installed you'll need to add some users. I hope to improve this process later but for now you can do it via the `admin` command
+
+```shell
+./ssh-sentinel-server admin -h
+Create / delete users
+
+Usage:
+  ssh-sentinel-server admin [flags]
+
+Flags:
+  -c, --config string        Config file
+  -C, --create               If set a new user will be created
+  -h, --help                 help for admin
+  -n, --name string          User's name
+  -P, --principals strings   A list of principals for the user
+  -U, --username string      Username
+```
+
+So to add a user
+
+```shell
+./ssh-sentinel-server admin -c config.json -C -n test -P test1 test2 -U test
+```
+
+Not that the username is the user associated with this service. The principals list the allowed usernames on the server you will ssh to.
+
+## Usage
+
+Here are some high level usage details
+
+### Clients
+
+The server stands up as a restful HTTP/S service. You can post requests via curl ( see [api docs](./api-docs.yaml) for the API ) or you can use the [CLI client](https://github.com/ST2Projects/ssh-sentinel-client)
+
+### Servers
+
+Servers require some configuration to use the CA. In short:
+
+- Copy the CA **public key** to the server and save it in `/etc/ssh/ca.pub`
+- Edit `/etc/ssh/sshd_config` and add `TrustedUserCAKeys /etc/ssh/ca.pub`
+- Restart SSHD `service sshd restart`
+
+The easiest way to do this across an estate is with ansible. I will publish a role on ansible-galaxy to do this but you can create your own if required / desired
 
 ## Releases
 
diff --git a/api-docs.yaml b/api-docs.yaml
@@ -0,0 +1,113 @@
+swagger: "2.0"
+info:
+  title: SSH-Sentinel
+  description: Sentinel API
+  version: 1.0.0
+host: localhost:443
+consumes:
+  - application/json
+produces:
+  - application/json
+  - text/plain
+schemes:
+  - https
+basePath: /
+
+definitions:
+  KeySignRequest:
+    type: object
+    description: A signing request
+    properties:
+      username:
+        type: string
+        example: testUser-1
+        description: The client username ( with the service )
+      api_key:
+        type: string
+        pattern: [a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}
+        example: c7ce5f4a-ae6b-4232-a458-62855d0b9f29
+        description: The API Key provided by the service at registration
+      principals:
+        type: array
+        description: A list of usernames to be included with the certificate. Usernames are with the target services
+      key:
+        type: string
+        description: The public key to sign
+  KeySignResponse:
+    type: object
+    description: A signing response
+    properties:
+      success:
+        type: boolean
+        description: Indicates if the the request was a success
+        example: false
+      message:
+        type: string
+        description: Any message / info returned by the server ( e.g. an error message )
+        example: "Authentication failure"
+      signedKey:
+        type: string
+        description: The signed key / certificate
+      notBefore:
+        type: integer
+        description: UNIX Epoch of the certificate start time
+        example: 1666793056
+      notAfter:
+        type: integer
+        description: UNIX Epoch of the certificate end time
+        example: 1666793056
+  Pong:
+    type: string
+  CAPubKey:
+    type: string
+
+
+
+paths:
+  /ping:
+    get:
+      summary: A Ping test
+      produces:
+        - text/plain
+      security: []
+      responses:
+        200:
+          description: A successful response
+          schema:
+            $ref: "#/definitions/Pong"
+          headers:
+            content-type:
+              type: string
+              x-example: text/plain; charset=utf-8
+  /ssh:
+    post:
+      summary: Performs signing
+      produces:
+        - application/json
+      security: []
+      parameters:
+        - name: Request body
+          in: body
+          required: true
+          schema:
+            $ref: "#/definitions/KeySignRequest"
+      responses:
+        200:
+          description: Successful request
+          schema:
+            $ref: "#/definitions/KeySignResponse"
+        401:
+          description: Unauthorized
+          schema:
+            $ref: "#/definitions/KeySignResponse"
+  /capubkey:
+    get:
+      summary: Get the current CA public key
+      produces:
+        - text/plain
+      security: []
+      responses:
+        200:
+          description: A successful response
+          schema:
+            $ref: "#/definitions/CAPubKey"
diff --git a/install/Makefile b/install/Makefile
