diff --git a/manifest.json b/manifest.json index 013949ae..1900247b 100644 --- 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 index 39bfdc94..7f0a3f2c 100644 --- a/platform/core-concepts.mdx +++ b/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. diff --git a/platform/smallstep-app.mdx b/platform/smallstep-app.mdx new file mode 100644 index 00000000..ce3c6164 --- /dev/null +++ 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 | Latest Version | +| Linux (Flatpak) | Latest Version | +| Linux (.deb) | Latest Version | +| Linux (.rpm) | Latest Version | +| Windows | Latest Version | + +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