Merge branch 'main' into chris/web-1977-bug-image-link-broken-on-core…

…-concepts-docs-page
smallstep · Aug 5, 2024 · 45d8bdb · 45d8bdb
2 parents c9b3458 + 84146e7
commit 45d8bdb
Show file tree

Hide file tree

Showing 11 changed files with 107 additions and 9 deletions.
diff --git a/manifest.json b/manifest.json
@@ -30,6 +30,10 @@
             {
               "title": "Smallstep API",
               "path": "/platform/smallstep-api.mdx"
+            },
+            {
+              "title": "Smallstep App",
+              "path": "/platform/smallstep-app.mdx"
             }
           ]
         },

diff --git a/platform/core-concepts.mdx b/platform/core-concepts.mdx
@@ -3,6 +3,7 @@ title: Core Concepts
 html_title: Smallstep Core Concepts
 description: High-level overview of the major components and concepts you’ll encounter while working with the Smallstep platform, and how they interact/relate with one another to protect your resources and provide strong assurance of device identity.
 ---
+
 ![Image: Device Identity Attestation Flow](https://smallstep-cms-images.s3.us-east-2.amazonaws.com/tpm_attestation_0de8c39a14.png)
 
 # Workflow Overview
@@ -39,7 +40,7 @@ A third party could verify possession of an Endorsement Key pair by encrypting a
 ## Smallstep app
 The Smallstep app is a desktop app that offers a uniform experience for device identity across macOS, Windows, and Linux. It is the foundation for Smallstep's high-assurance device identity attestation workflow, automating the issuance of certificates to devices and configuring the components that depend on these certificates. 
 
-The app is installed on individual company-managed devices and operates without administrative privileges. It only collects the device security context essential for your organisation's administrative policy configuration.
+The app is installed on individual company-managed devices and only collects the device security context essential for your organisation's administrative policy configuration.
 
 After proving its identity to the Smallstep Attestation CA, the app obtains a device identity certificate. This device certificate is then used to obtain short-lived client resources for accessing organisational resources such as Wi-Fi or VPN networks, ensuring that sensitive organisational resources are only accessible from trusted company-managed devices.
 

diff --git a/platform/smallstep-app.mdx b/platform/smallstep-app.mdx
@@ -0,0 +1,78 @@
+---
+title: The Smallstep App
+html_title: The Smallstep App
+description: This document specifies app download links, system requirements, runtime requirements, file permissions, and telemetry data collected for the Smallstep desktop app.
+---
+Smallstep ensures that access to financial data, code repositories, PII, and other sensitive resources is only possible from trusted, company-managed devices. 
+
+The Smallstep desktop app is central to that process. It offers a uniform experience for device identity across macOS, Windows, and Linux, and is the foundation for Smallstep's high-assurance device identity attestation workflow, automating the issuance of certificates to devices and configuring the components that depend on these certificates.
+
+Here's all the necessary info you need to install and use the app effectively and consciously:
+
+## Download
+
+| Platform  | Release  |
+|:--|:--|
+| macOS  | <a href='https://packages.smallstep.com/stable/darwin/Smallstep.dmg'>Latest Version</a>  |
+| Linux (Flatpak) | <a href='https://packages.smallstep.com/stable/flatpak/Smallstep.flatpakref'>Latest Version</a>  |
+| Linux (.deb) | <a href='https://packages.smallstep.com/stable/deb/smallstep-desktop.deb'>Latest Version</a>  |
+| Linux (.rpm) | <a href='https://packages.smallstep.com/stable/deb/smallstep-desktop.rpm'>Latest Version</a>  |
+| Windows  | <a href='https://packages.smallstep.com/stable/windows/Smallstep.exe'>Latest Version</a>  |
+
+Installers for macOS, Windows and Linux can be also be downloaded from [GitHub releases](https://github.com/smallstep/smallstep-desktop/releases). Releases are signed with, and can be verified, by cosign.
+
+## System Requirements
+
+### Windows
+
+- Windows 10 or later
+- Trusted Platform Module (TPM 2.0)
+
+### Linux
+
+- Flatpak, or Debian 12+, Ubuntu 22.04+, Fedora 38+
+- `systemd`-based service manager
+- Trusted Platform Module (TPM 2.0)
+- p11-kit
+- tpm-tss2
+
+### macOS
+
+- macOS 13 (Ventura) or later
+- Secure Enclave
+
+## Runtime Requirements
+
+All platforms require an internet connection for normal operation.
+
+### Windows
+
+- *Administrator privileges* - the Smallstep app requires privilege escalation to be able to communicate to the TPM
+
+### macOS
+
+- *Location permission* - to enable management of Wifi networks, the Smallstep app needs location permission
+- *Keychain access* - the Smallstep app uses the macOS keychain to store both keys and certificates it manages
+- *Network Extension entitlement* - the Smallstep app requests the *Network Extension* entitlement so that it can manage VPN connections
+
+### Linux
+
+- *TPM read/write permission* - the Smallstep app communicates to the TPM from user-space using `tpm-tss2`, and the running user must have read/write permissions to the TPM resource manager (typically `/dev/tpmrm0`)
+
+## File Access
+On all platforms, the Smallstep app creates and manages a directory on the filesystem in a well-known location for management of keys and certificates. However, it does not access any other file on a device except the one it creates. 
+
+- On macOS: `$HOME/Library/Application Support/Smallstep`
+- On Windows: `%LOCALAPPDATA%/Smallstep`
+- On Linux: `$XDG_RUNTIME_DIR/step-agent` and `$XDG_CONFIG_HOME/step-agent`
+
+## Telemetry
+
+The Smallstep app collects and reports some data from the host device as part of its normal operation. These are:
+
+- Device Identifiers from TPM-enabled platforms
+- Device/Computer Name
+- Device/Computer Hostname
+- Chipset Architecture
+- Operating System Version
+- WAN IP Address
diff --git a/step-cli/reference/README.mdx b/step-cli/reference/README.mdx
@@ -65,7 +65,7 @@ print the version
 
 ## Version
 
-Smallstep CLI/0.27.1 (linux/amd64)
+Smallstep CLI/0.27.2 (linux/amd64)
 
 ## Copyright
 

diff --git a/step-cli/reference/ca/certificate/README.mdx b/step-cli/reference/ca/certificate/README.mdx
@@ -149,7 +149,7 @@ but can accept a different configuration file using **--ca-config** flag.
 The path to the `file` containing the password to encrypt or decrypt the private key.
 
 **--console**
-Complete the flow while remaining inside the terminal
+Complete the flow while remaining inside the terminal.
 
 **--kms**=`uri`
 The `uri` to configure a Cloud KMS or an HSM.

diff --git a/step-cli/reference/ca/sign/README.mdx b/step-cli/reference/ca/sign/README.mdx
@@ -82,7 +82,7 @@ but can accept a different configuration file using **--ca-config** flag.
 The path to the `file` containing the password to encrypt or decrypt the private key.
 
 **--console**
-Complete the flow while remaining inside the terminal
+Complete the flow while remaining inside the terminal.
 
 **--kms**=`uri`
 The `uri` to configure a Cloud KMS or an HSM.

diff --git a/step-cli/reference/ssh/certificate/README.mdx b/step-cli/reference/ssh/certificate/README.mdx
@@ -18,7 +18,7 @@ step ssh certificate <key-id> <key-file>
 [--password-file=<file>] [--provisioner-password-file=<file>]
 [--add-user] [--not-before=<time|duration>] [--comment=<comment>]
 [--not-after=<time|duration>] [--token=<token>] [--issuer=<name>]
-[--no-password] [--insecure] [--force] [--x5c-cert=<file>]
+[--console] [--no-password] [--insecure] [--force] [--x5c-cert=<file>]
 [--x5c-key=<file>] [--k8ssa-token-path=<file>] [--no-agent]
 [--kty=<key-type>] [--curve=<curve>] [--size=<size>]
 [--ca-url=<uri>] [--root=<file>] [--context=<name>]
@@ -116,6 +116,9 @@ The `key=value` pair with template data variables. Use the **--set** flag multip
 **--set-file**=`file`
 The JSON `file` with the template data variables.
 
+**--console**
+Complete the flow while remaining inside the terminal.
+
 **--add-user**
 Create a user provisioner certificate used to create a new user.
 

diff --git a/step-cli/reference/ssh/config/README.mdx b/step-cli/reference/ssh/config/README.mdx
@@ -16,7 +16,7 @@ menu:
 step ssh config
 [--team=<name>] [--team-authority=<sub-domain>] [--host]
 [--set=<key=value>] [--set-file=<file>] [--dry-run] [--roots]
-[--federation] [--force] [--offline] [--ca-config=<file>]
+[--federation] [--console] [--force] [--offline] [--ca-config=<file>]
 [--ca-url=<uri>] [--root=<file>] [--context=<name>]
 [--authority=<name>] [--profile=<name>]
 ```
@@ -61,6 +61,9 @@ times to set multiple variables.
 **--set-file**=`file`
 The JSON `file` with the template data variables.
 
+**--console**
+Complete the flow while remaining inside the terminal.
+
 **--dry-run**
 Executes the command without changing any file.
 

diff --git a/step-cli/reference/ssh/hosts/README.mdx b/step-cli/reference/ssh/hosts/README.mdx
@@ -14,7 +14,7 @@ menu:
 
 ```raw
 step ssh hosts [--set=<key=value>] [--set-file=<file>]
-[--offline] [--ca-config=<file>] [--ca-url=<uri>] [--root=<file>]
+[--console] [--offline] [--ca-config=<file>] [--ca-url=<uri>] [--root=<file>]
 [--context=<name>]
 ```
 
@@ -34,6 +34,9 @@ The `key=value` pair with template data variables. Use the **--set** flag multip
 **--set-file**=`file`
 The JSON `file` with the template data variables.
 
+**--console**
+Complete the flow while remaining inside the terminal.
+
 **--offline**
 Creates a certificate without contacting the certificate authority. Offline mode
 uses the configuration, certificates, and keys created with **step ca init**,

diff --git a/step-cli/reference/ssh/login/README.mdx b/step-cli/reference/ssh/login/README.mdx
@@ -17,7 +17,7 @@ step ssh login [<identity>]
 [--token=<token>] [--provisioner=<name>] [--provisioner-password-file=<file>]
 [--principal=<string>] [--not-before=<time|duration>] [--not-after=<time|duration>]
 [--kty=<key-type>] [--curve=<curve>] [--size=<size>] [--comment=<comment>]
-[--set=<key=value>] [--set-file=<file>] [--force] [--insecure]
+[--set=<key=value>] [--set-file=<file>] [--console] [--force] [--insecure]
 [--offline] [--ca-config=<file>]
 [--ca-url=<uri>] [--root=<file>] [--context=<name>]
 ```
@@ -86,6 +86,9 @@ The `key=value` pair with template data variables. Use the **--set** flag multip
 **--set-file**=`file`
 The JSON `file` with the template data variables.
 
+**--console**
+Complete the flow while remaining inside the terminal.
+
 **-f**, **--force**
 Force the overwrite of files without asking.
 

diff --git a/step-cli/reference/ssh/proxycommand/README.mdx b/step-cli/reference/ssh/proxycommand/README.mdx
@@ -15,7 +15,7 @@ menu:
 ```raw
 step ssh proxycommand <user> <host> <port>
 [--provisioner=<name>] [--set=<key=value>] [--set-file=<file>]
-[--offline] [--ca-config=<file>]
+[--console] [--offline] [--ca-config=<file>]
 [--ca-url=<uri>] [--root=<file>] [--context=<name>]
 ```
 
@@ -54,6 +54,9 @@ The `key=value` pair with template data variables. Use the **--set** flag multip
 **--set-file**=`file`
 The JSON `file` with the template data variables.
 
+**--console**
+Complete the flow while remaining inside the terminal.
+
 **--offline**
 Creates a certificate without contacting the certificate authority. Offline mode
 uses the configuration, certificates, and keys created with **step ca init**,