Merge pull request #339 from smallstep/smallstep-app

added smallstep app docs

manifest.json

@@ -30,6 +30,10 @@
             {
               "title": "Smallstep API",
               "path": "/platform/smallstep-api.mdx"
+            },
+            {
+              "title": "Smallstep App",
+              "path": "/platform/smallstep-app.mdx"
             }
           ]
         },

platform/core-concepts.mdx

@@ -3,7 +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](/graphics/tpm-attestation.png)
+![Device Identity Attestation Flow](/graphics/tpm-attestation.png)
 
 # Workflow Overview
 
@@ -39,7 +39,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.
 

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