Changes

doc/configuration-ssh.md

@@ -1,3 +1,77 @@
 # Engity's Bifröst SSH configuration
 
-⚠️ Work in progress.
+Defines the whole behavior of the SSH protocol (implemented by Bifröst) by itself.
+
+## Properties
+
+1. **`addresses`**: Array&lt;[Net Address](data-type.md#net-address)&gt; = `[ ":22" ]`<a id="addresses"></a><br>
+   To which address the service will bind and listen to.
+
+2. **`keys`**: [Keys](#keys)<br>
+   See [below](#keys).
+
+3. **`idleTimeout`**: [Duration](data-type.md#duration) = `10m` <a id="idleTimeout"></a><br>
+   For how long a connection can be idle before it will forcibly be closed. The client can send keep alive packages to extend the idle time. `0` means that the connection will never time out.
+
+4. **`maxTimeout`**: [Duration](data-type.md#duration) = `0` <a id="maxTimeout"></a><br>
+   The maximum duration a connection can be connected before it will be forcibly be closed, regardless if there are actions or not. `0` means that the connection will never time out.
+
+5. **`maxAuthTries`**: `uint8` = `6` <a id="maxAuthTries"></a><br>
+   How much different authentication methods a client can use before the connection will be rejected.
+
+6. **`maxConnections`**: `uint32` = `255` <a id="maxConnections"></a><br>
+   The maximum amount of parallel connections on this service. Each new connecting connection will be rejected.
+
+7. **`banner`**: [String Template](data-type.md#string-template)&lt;[Connection](data-type.md#context-connection)&gt; = `{{"/etc/ssh/sshd-banner" | file "optional" | default "Transcend with Engity's Bifröst\n\n" }}` <a id="banner"></a><br>
+   Banner which will be shown if the client connects to the server before the first even the validation of authorizations or similar happens.
+
+## Examples
+
+```yaml
+addresses: [ ":22" ]
+keys:
+  hostKeys: [ /etc/engity/bifroest/key ]
+  # ...
+idleTimeout: 10m
+maxTimeout: 0
+maxAuthTries: 6
+maxConnections: 255
+banner: "Yeah!"
+```
+
+## Keys
+
+### Properties
+
+1. **`hostKeys`**: Array&lt;[File Path](data-type.md#file-path)&gt; = `[ "<defaultLocation>" ]`<a id="hostKeys"></a><br>
+   Where to store the host keys at. If they do not exist, they will be created as Ed25519 key.
+
+   Default Locations:
+   * Linux: `/etc/engity/bifroest/key`
+   * Windows: `C:\ProgramData\Engity\Bifroest\key`
+
+2. **`rsaRestriction`**: [RSA Restriction](data-type.md#rsa-restriction) = `at-least-4096-bits` <a id="rsaRestriction"></a><br>
+   Restrict which RSA keys are allowed to be used.
+
+3. **`dsaRestriction`**: [DSA Restriction](data-type.md#dsa-restriction) = `none` <a id="dsaRestriction"></a><br>
+   Restrict which DSA keys are allowed to be used.
+
+4. **`ecdsaRestriction`**: [ECDSA Restriction](data-type.md#ecdsa-restriction) = `at-least-384-bits` <a id="ecdsaRestriction"></a><br>
+   Restrict which ECDSA keys are allowed to be used.
+
+5. **`ed25519Restriction`**: [ED25519 Restriction](data-type.md#ed25519-restriction) = `all` <a id="ed25519Restriction"></a><br>
+   Restrict which ED25519 keys are allowed to be used.
+
+6. **`rememberMeNotification`**: [String Template](data-type.md#string-template)&lt;[Authorization](data-type.md#context-authorization)&gt; = `If you return until {{.session.validUntil | format "dateTimeT"}} with the same public key ({{.key | fingerprint}}), you can seamlessly login again.\n\n` <a id="rememberMeNotification"></a><br>
+   Banner which will be shown if the connection was based on an authentication method (like OIDC) which does not have its own public key authentication. At this point the authentication was successful AND the client submitted at least one public key (as authentication try). This key will be used and this message will be shown to the client to inform, that this key will be used for the session from now on. As a result the original authentication will be skipped (like OIDC) as long it is not expired and the client presents the same public key.
+
+### Examples
+
+```yaml
+hostKeys: [ /etc/engity/bifroest/key ]
+rsaRestriction: at-least-4096-bits
+dsaRestriction: none
+ecdsaRestriction: at-least-384-bits
+ed25519Restriction: all
+rememberMeNotification: "If you return until {{.session.validUntil | format `dateTimeT`}} with the same public key ({{.key | fingerprint}}), you can seamlessly login again.\n\n"
+```

doc/configurations/demo.yaml

@@ -30,7 +30,7 @@ ssh:
         ## @enum[none, all, at-least-256-bits, at-least-384-bits, at-least-521-bits]
         ecdsaRestriction: at-least-384-bits
 
-        ## Restrict which ECDSA keys are allowed to be used.
+        ## Restrict which ED25519 keys are allowed to be used.
         ## @default
         ## @enum[none, all, at-least-256-bits]
         ed25519Restriction: all

doc/data-type.md

@@ -1,9 +1,57 @@
 # Data types used in Engity's Bifröst configuration
 
-## Flow Name
+## Context Authorization
+⚠️ Work in progress.
+
+## Context Connection
+⚠️ Work in progress.
+
+## DSA Restriction
+Can be one of:
+* `none`
+* `all`
+* `at-least-1024-bits`
+* `at-least-2048-bits`
+* `at-least-3072-bits`
+
+## Duration
+A duration of time of [Go flavor](https://pkg.go.dev/time#ParseDuration). Examples: `300ms`, `6s`, `5m`, `12h` or combined `12h5m6s300ms`.
+
+## ED25519 Restriction
+Can be one of:
+* `none`
+* `all`
+* `at-least-256-bits`
 
+## ECDSA Restriction
+Can be one of:
+* `none`
+* `all`
+* `at-least-256-bits`
+* `at-least-384-bits`
+* `at-least-521-bits`
+
+## Flow Name
 Identifies flows. It has to fulfill the regular expression `[a-z][a-z0-9]+`.
 
+## File Path
+A location of a file on the local file system. Like `/foo/bar`
+
+## Net Address
+Socket address in format `[<host>]:<port>`.
+
 ## Regex
+Regular expression of [Go flavor](https://pkg.go.dev/regexp). You can play around with it at [regex.com](https://regex101.com/r/fRdVOl/1).
+
+## RSA Restriction
+Can be one of:
+* `none`
+* `all`
+* `at-least-1024-bits`
+* `at-least-2048-bits`
+* `at-least-3072-bits`
+* `at-least-4096-bits`
 
+## String Template
+⚠️ Work in progress.