From 4da3dca47746b9c6257f3d6b15d90ff70fc9fc80 Mon Sep 17 00:00:00 2001 From: Linda-Ikechukwu Date: Mon, 24 Jun 2024 11:36:12 +0200 Subject: [PATCH 1/6] adding core concepts page --- graphics/tpm-attestation.png | Bin 0 -> 20338 bytes manifest.json | 8 ++- platform/README.mdx | 103 ++++++++++++++++++++--------------- platform/core-concepts.mdx | 94 ++++++++++++++++++++++++++++++++ 4 files changed, 158 insertions(+), 47 deletions(-) create mode 100644 graphics/tpm-attestation.png create mode 100644 platform/core-concepts.mdx diff --git a/graphics/tpm-attestation.png b/graphics/tpm-attestation.png new file mode 100644 index 0000000000000000000000000000000000000000..6a3c4f4f142762c02cd151a9cd65903d6fc56443 GIT binary patch literal 20338 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 BK3xC+ literal 0 HcmV?d00001 diff --git a/manifest.json b/manifest.json index ba196d2c..02a3cb37 100644 --- a/manifest.json +++ b/manifest.json @@ -17,12 +17,16 @@ "title": "Platform" }, { - "title": "Smallstep Overview", + "title": "About Smallstep", "routes": [ { - "title": "About Smallstep", + "title": "Overview", "path": "/platform/README.mdx" }, + { + "title": "Core Concepts", + "path": "/platform/core-concepts.mdx" + }, { "title": "Smallstep API", "path": "/platform/smallstep-api.mdx" diff --git a/platform/README.mdx b/platform/README.mdx index bb4515d0..d6976e8f 100644 --- a/platform/README.mdx +++ b/platform/README.mdx @@ -4,15 +4,20 @@ html_title: What is Smallstep? description: Smallstep is a centralised comprehensive internal PKI toolchain, providing IT/Security/DevOps engineers with everything they need to automate the deployment, and management (renewal, revocation and monitoring) of certificates for a broad range of contexts, use cases and environments. --- -Certificates are a fundamental part of any non-trivial architecture, as they are the strongest possible way to encrypt communications, authenticate users and devices, protect data integrity, and ensure compliance with security standards. +Certificates are a fundamental part of any non-trivial architecture. They provide the strongest possible way to authenticate users and devices, encrypt communications, protect data integrity, and ensure compliance with security standards. -Smallstep is a centralised comprehensive internal PKI toolchain, providing IT/Security/DevOps engineers with everything they need to automate the deployment, and management (renewal, revocation and monitoring) of certificates for a broad range of contexts, use cases and environments. +Smallstep is a comprehensive device identity solution for securely identifying company-owned or company-managed devices using high-assurance ***cryptographically attested device identity*** certificates. + +As networks and resources become increasingly distributed — with SaaS moving sensitive resources off private networks and BYOD policies introducing personal devices — threats to data confidentiality grow more aggressive. Organizations are seeking more secure methods to ensure that only authorized users on authorized devices can access sensitive resources. Provisioning trusted devices with device-attested client certificates for accessing critical resources within your organisation is the most effective way to achieve this. + +Smallstep provides the means to use the strongest possible assurance of device identity to ensure that only trusted company-approved devices can enroll for client certificates to access sensitive organisational resources. This procedure is facilitated through the [ACME device attestation enrolment](https://smallstep.com/blog/managed-device-attestation/), effectively protecting your organisation from data breaches caused by credential compromise or phishing. + +With Smallstep, IT/Security/Network Engineers can assign certificates to devices and configure the things that rely on those certificates correctly without needing to know much about PKI. -We offer robust integration solutions for securing network connections to various resources like servers, databases, internal web applications, Kubernetes clusters, GitHub Actions, VPNs, VMs, Wi-Fi, managed devices, and more. With Smallstep, your PKI can serve as a unified foundation for certificate-driven security for all your devices, people, and workloads.
- 💡 If you’d like to dive deeper into certificates and PKI, see these articles from our blog: + 💡 Regardless, if you want to dive deeper into PKI, see some literature from our blog:
+# Why Cryptographic Attested Device Identity? +Many existing solutions provide some flavor of 'device identity' where the device self-reports a unique ID for itself, or the identity is tied to a credential. -# What can you use Smallstep for? -## Enterprise IT +But can such device identity be trusted if an independent infallible entity does not attest to it? Does a credential still significantly identify a device if it can be moved between devices? In such scenarios, we make critical assumptions that our devices and services report information is trustworthy. -Smallstep can be used to establish high-assurance device identities and restrict access by devices, ensuring that sensitive resources are only accessible from trusted company-managed devices. When combined with user identities, device identities bound to hardware can offer the strongest possible security guarantees. +Claiming device identity should be as substantiated as declaring one's citizenship. Just as one must provide a passport, attested and signed by their nation's government to prove their citizenship, a device should also offer some form of attestation to establish its identity. -Device Identity helps your organisation: +Take the SCEP enrolment process ubiquitously employed by MDM platforms. -- [Protect against credential theft based attacks](https://smallstep.com/blog/road-to-phishing-resistant-authentication/). -- Meet regulatory requirements and industry standards such as GDPR, HIPAA, and PCI DSS. -- Enforce non-repudiation, so you can seamlessly verify and attribute every action. +The Simple Certificate Enrollment Protocol (SCEP) [[**RFC**](https://en.wikipedia.org/wiki/RFC_(identifier)) [**8894**](https://datatracker.ietf.org/doc/html/rfc8894)] simplifies the process of issuing certificates to devices and 'verifying their identity' on a network. The process starts with an employee initiating enrollment through authentication with an MDM agent or link. The employee's device then receives a SCEP payload. This payload contains enrollment instructions, a SCEP server URL, and a challenge password, which the device then uses to obtain a certificate from the organisation's Certificate Authority (CA). -After devices have been securely enrolled and identified, Smallstep takes care of automatically deploying client certificates to company devices for accessing each of your most important resources, such as: +The problem is, in this process, the device does not provide strong evidence about itself when making a request. It's hard to verify that the device belongs to a said organisation or is a known device, because there is no known identity set up for the device the first time it identifies itself. Additionally, SCEP is secured with a password, making it vulnerable to phishing—if a scammer obtains a user's credentials, they could enroll an unauthorised device. Similarly, an attacker who gains access to a configuration profile could use SCEP to obtain a certificate and impersonate the user. -- Wi-Fi (for 802.1x EAP-TLS WPA-Enterprise) -- VPN Servers -- Zero Trust Network Access (ZTNA) -- HTTP/3 Proxies -- Internal Websites -- Cloud-based collaboration suites (Google Workspace, Microsoft Office365, Zoho Workplace, Atlassian Suite, e.t.c) -- Public SaaS applications (Stripe, Quickbooks, Slack, etc.) +How can controls be implemented to assure that only authorised trusted devices can obtain certificates using your organisation's PKI? -### For Organisations With MDM +The answer lies in cryptographic attested device identity: a device provides strong signed evidence, backed by hardware-bound keys, independent of the OS or user space, affirming its identity. -Smallstep integrates with your MDM to deploy client certificates to company-managed devices to enable certificate-based network authentication for Wi-Fi (802.1x EAP-TLS WPA-Enterprise), VPN, ZTNA, etc. +Modern devices feature cryptoprocessors ([TPMs](https://smallstep.com/blog/trusted-platform-modules-tpms/) or Secure Enclaves) that are isolated from the main processor. These cryptoprocessors are shielded from tampering and unauthorized access, even if the primary operating system is compromised. They provide hardware-based security-related functions and perform cryptographic operations. Each cryptoprocessor comes with a unique asymmetric key pair, hard-coded during manufacturing, of which the public part is publicly accessible. -We offer integrations for any MDMs for Apple and Windows devices that support Dynamic SCEP or ACME certificate enrollment protocols. +To verify its identity, a device signs a challenge by decrypting data encrypted with its public key. This public key is stored on the organization's device inventory, and the decryption is done using its hardware-bound private key. After successful verification, the device receives an attested device identity certificate. With this certificate, the device can prove its identity to your organisation's Public Key Infrastructure (PKI) and obtain the necessary certificates to access organisational resources. This can be achieved with device attestation and [ACME device-attest-01 challenge](https://datatracker.ietf.org/doc/html/draft-acme-device-attest-01). -![Jamf MDM Marketecture.png](/graphics/Jamf_MDM_Marketecture.png) +ACME is a client and server protocol that uses "challenges" to ensure a client can prove control over specific identifiers for issuing a certificate. The device-attest-01 challenge allows devices to request attestation from a device inventory. They then forward the signed attestation and Certificate Signing Request (CSR) to a supported ACME server in exchange for a signed certificate from the organisation's PKI. -Supported MDMs include: Jamf, Intune, Workspace ONE, Mosyle, Ivanti, Jumpcloud, and lots more. +This process, known as cryptographic device attestation, forms the foundation for secure, automated device enrollment, and is how we protect your resources. -Smallstep can also be used as a drop-in replacement for Active Directory Certificate Services (ADCS), allowing you to transition from ADCS while still serving legacy workloads. We provide backwards-compatible support for SCEP and NDES, and also let you bring your existing Root CA with you, so you can get up and running in minutes. + -![Intune MDM Marketecture.png](/graphics/Intune_flow_diagram.png) +# How can you use Smallstep? -See: +The Smallstep Agent is the vehicle through which Smallstep delivers cryptographically attested device identity to your organisation. It is the recommended way to identify devices and get client certificates to devices (Windows, Linux, Mac OS) for Enterprise Wi-Fi, VPN, HTTP/3 proxies, or web applications. -- [Why Your Organisation Should Be Migrating From Microsoft AD CS](https://smallstep.com/blog/migrate-from-microsoft-adcs/) -- [How to Bring Your Own Root from AD CS to Smallstep](https://smallstep.com/blog/byor-adcs-to-smallstep/) +It is a lightweight program that runs in the background on devices and manages end-to-end certificate lifecycle for various resources. It works with all TPM 2.0 devices—virtual TPMs, firmware TPMs, or physical TPMs—and on some TEEs and Secure Enclaves (eg. Apple Managed Device Attestation). + +To get started, [sign up now](https://smallstep.com/signup/). + +## For Organisations who do not want to use the Agent + +If for any reason, you cannot have the Smallstep Agent on your devices, Smallstep can still help you get certificates to devices via your MDM using SCEP. This method is less secure than the cryptographic device attestation offered by the ACME device-attest-01 challenge, which is supported by the Smallstep Agent. Regrettably, major MDM providers have yet to adopt ACME device attestation. + +Smallstep integrates with your MDM to deploy client certificates to company-managed devices to enable certificate-based network authentication for Wi-Fi (802.1x EAP-TLS WPA-Enterprise), VPN, ZTNA, etc. + +We offer integrations for any MDMs for Apple and Windows devices that support Dynamic SCEP like Jamf, Intune, Workspace ONE, Mosyle, Ivanti, e.t.c. + +![Jamf MDM Marketecture.png](/graphics/Jamf_MDM_Marketecture.png)
@@ -69,23 +80,20 @@ See:

In static SCEP, a single challenge password is in every SCEP payload for every device. This practice is insecure and not recommended. Furthermore, it only shows a single user in reporting. We do not support this because we believe it's crucial to provide the most secure options for your infrastructure.

In contrast, for Dynamic SCEP, webhooks are used to generate new challenges and unique passwords for each device, and you would be able to see reporting for all devices.

-

If your MDM does not support Dynamic SCEP, your next best bet to deploy Smallstep is to use the Smallstep Agent. See details below.

 -### For Organisations Without MDM or with Linux Devices - -The Smallstep Agent is the recommended way to get identify devices and get client certificates to devices for Enterprise Wi-Fi, VPN, HTTP/3 proxies, or web applications in the following scenarios: +Smallstep can also be used as a drop-in replacement for Active Directory Certificate Services (ADCS), allowing you to transition from ADCS while still serving legacy workloads. We provide backwards-compatible support for SCEP and NDES, and also let you bring your existing Root CA with you, so you can get up and running in minutes. -- SMEs with 20 - 100 devices without an MDM -- Linux devices -- Managed devices under an MDM that does not support Dynamic SCEP +![Intune MDM Marketecture.png](/graphics/Intune_flow_diagram.png) -The Smallstep Agent is a lightweight program that runs in the background on devices and manages end-to-end certificate lifecycle for various resources (workloads). The agent leverages Trusted Platform Modules (TPMs) for trust bootstrapping. It works with all TPM 2.0 devices—virtual TPMs, firmware TPMs, or physical TPMs—and on some TEEs and Secure Enclaves (eg. Apple Managed Device Attestation). + -# How Can You Use Smallstep? +# The Smallstep Ecosystem Depending on what’s best for your infrastructure and current reality, Smallstep offers different deployment options to meets your needs: @@ -103,15 +111,19 @@ Talk to Smallstep’s Customer Engineering Team at [support.smallstep.com](http: ## Smallstep Open-Source Toolchain -Our open source toolchain the most popular open-source certificate management toolchain, and was designed for DevOps and homelab or POC use cases—it’s not a device identity platform, and doesn’t solve the problems listed above. +Our open source toolchain the most popular open-source certificate management toolchain, and was designed for DevOps and homelab or POC use cases. However, it’s not a device identity platform, and doesn’t solve the problems listed above out-of-the-box. + +Our open-source toolchain provides IT/Security/DevOps engineers with an extensive internal PKI toolchain, which includes everything needed to automate the deployment and management (renewal, revocation, and monitoring) of certificates for a broad range of contexts, use cases, and environments. + +We offer robust integration solutions for securing network connections to various resources like servers, databases, internal web applications, Kubernetes clusters, GitHub Actions, VPNs, VMs, Wi-Fi, managed devices, and more. With Smallstep, your PKI can serve as a unified foundation for cryptographic encryption and authentication for all your devices, people, and workloads. Our open-source toolchain for certificate and PKI management features 3 components: -- [step CLI](https://github.com/smallstep/cli): A user-friendly command-line interface to build, operate, and automate PKI systems. -- [step-ca](https://github.com/smallstep/certificates): A powerful online CA for secure, automated certificate management. -- [step-issuer](https://github.com/smallstep/step-issuer) and [autocert](https://github.com/smallstep/autocert): Kubernetes-native solutions for seamless certificate issuance and management in containerized environments. +- step CLI: A user-friendly command-line interface to build, operate, and automate PKI systems, with built-in support for ACME & the **`device-attest-01`** **challenge. +- step-ca: A powerful online CA for secure, automated certificate management. +- step-issuer and autocert: Kubernetes-native solutions for seamless certificate issuance and management in containerized environments. -Get tinkering and [***Join our open-source Discord community*** ](https://u.step.sm/discord). +Join our open-source Discord community. ## Smallstep Enterprise CA @@ -131,4 +143,5 @@ Key Features are: - Connectors for existing PKI backends (AD CS, GCP CAS, AWS PCM) - High availability, automation, and CLM integration with Sectigo and Digicert -We offer standard SLAs with 24-hour response for non-critical issues and 4-hour turnaround for critical incidents. For organizations requiring tailored assistance, enhanced support options are available, ensuring your infrastructure remains secure and operational. [Reach out](https://go.smallstep.com/request-demo) if you're looking to explore this option. +We offer standard SLAs with 24-hour response for non-critical issues and 4-hour turnaround for critical incidents. For organizations requiring tailored assistance, enhanced support options are available, ensuring your infrastructure remains secure and operational. Contact Us. + diff --git a/platform/core-concepts.mdx b/platform/core-concepts.mdx new file mode 100644 index 00000000..b30db9aa --- /dev/null +++ b/platform/core-concepts.mdx @@ -0,0 +1,94 @@ +--- +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. +--- +![Device Identity Attestation Flow](/graphics/tpm-attestation.png) + +Smallstep protects your organisation from phishing and data breach attacks, by limiting access to corporate resources to only company-owned or approved devices. + +This document provides a 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. + +Here’s what happens: + +1. As an administrator, you register company-owned or approved devices on the Smallstep web app using their hardware-attested identifiers, such as the TPM Endorsement Key (for Windows/Linux) or Secure Enclave ID (for Apple devices). +2. You (or your employee) installs **the** Smallstep Agent on a registered device. +3. The Smallstep Agent kicks off the device identity trust bootstrapping process by instructing the cryptographic processor (TPM or Secure Enclave) to create an Attestation Key (AK) ****pair. +4. The Smallstep Agent requests a device attestation certificate from the Smallstep Attestation CA. +5. The Smallstep Attestation CA verifies that a)the request is coming from a company-owned or company-approved device by checking if the specific EK (the public part) is registered on your Smallstep team device inventory, and b)the request is coming from a device from which the Endorsement Key is resident by asking the TPM to complete a challenge instructing the EK private component to decrypt data encrypted with the EK public component. +6. Upon verification, the Smallstep Attestation CA signs an Attestation Certificate for the agent. The Attestation Certificate cannot be used for any purpose other than attestation. +7. The agent uses the Attestation certificate complete an ACME device-attest-01 challenge from the **Agent CA** to obtain an device (agent) certificate. +8. Finally, the agent uses the device certificate via an X5C **Provisioner** to obtain short-lived 24 hour workload certificates needed by the device, from your Smallstep Workload CA. + +This entire workflow doesn't require any credentials to be configured in the agent nor does it need passwords, therefore eliminating common attack vectors. The device certificate is stored only in memory, never saved to disk, and workload certificates are short-lived, lasting only 24 hours. This leaves nothing for an attacker to exfiltrate, significantly narrowing the attack vector. + +## Device Identifiers + +Before restricting access to organizational resources to only your devices, you must know your devices. Smallstep offers a device inventory service to register and document your devices. + +Cryptographic processors used to establish trust in a device workflow come with a unique per-device asymmetric key pair that is hardcoded during manufacturing. For TPM modules, this key pair is known as the Endorsement Key. Sometimes, the TPM's manufacturer signs and includes an Endorsement Key Certificate (EKcert). For Apple's Secure Enclave, this is the Secure Enclave UID, a root cryptographic key fused to the secure enclave during manufacturing, and is inaccessible even to Apple. + +When registering devices on Smallstep, you will need to provide the Key URI, which contains information about the public part of the key, as the device identifier. + +The private part of these hardware-bound keys, used as identifiers, cannot sign data. They can only decrypt data encrypted with their corresponding public key. This means these keys cannot be used to directly track a device's identity. However, they can provide strong assurance when used as part of trust evaluation because they can only be used on the device where they were created. + +A third party could verify possession of an Endorsement Key pair by encrypting a small piece of data with the public key and asking the TPM to decrypt it with the private key. This simple device authentication mechanism offers the highest assurance that a request originates from a known device, compared to the SCEP + MDM enrolment process. + +## Smallstep Agent +The Smallstep agent is lightweight background software that offers a uniform experience for device identity across MacOS, Windows, and Linux platforms. 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 agent 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. + +After proving its identity to the Smallstep Attestation CA, the agent 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. + +## Smallstep Attestation CA +The Smallstep Attestation CA service is responsible for verifying the identity of a device that is authenticating itself. It confirms that the key presented by the device is hardware-bound and that the device is a known device registered to your Smallstep team account. + +The Attestation CA carries out a challenge/response protocol with the attestor (the device with the TPM) to validate the TPM's identity and issue an attestation certificate to the device. Subsequently, the device uses the attestation certificate to acquire a device identity certificate from the Agent CA. + +For a device to successfully complete an ACME Device Attestation challenge and obtain a high-assurance device identity certificate, it must present a valid attestation certificate (chain) signed by a trusted Attestation CA. + +Devices like Apple and Yubikeys have an Attestation CA maintained by their manufacturers. However, not all devices with TPMs (and similar tech) operate in environments where an Attestation CA is available that can (remotely) attest to device identity. + +The Attestation CA was built into the Smallstep platform to provide a uniform standard device identity attestation protocol. + +## Agent CA +The Agent CA is the certificate authority responsible for issuing, renewing, and revoking agent (device) certificates for device identity. It is configured to trust the Smallstep Attestation CA. As a result, when the agent receives an Attestation Certificate from the Smallstep Attestation CA, it can use this certificate to procure a device identity certificate from the Agent CA by completing an ACME device-attest-01 challenge or another certificate enrollment method, in cases where the former is not possible. + +## Attestation Key (AK) Certificate +An Attestation Certificate (AKcert) is a type of device identity certificate stored in the TPM, with its private key hardware-bound. The Attestation Certificate is provided to a trusted device after the Smallstep Attestation CA has verified its authenticity. + +To obtain an Attestation Certificate, the device must demonstrate to the Attestation CA that it possesses the hardware-bound private key of the cryptoprocessor. This Attestation Certificate is only used to establish a trust relationship with the device. The device agent uses it to acquire a device certificate that can be utilized for a variety of use cases. + +## Account +An Account represents the way access is gained to a resource, like a wifi network, or VPN server, is typically oriented around end-users (like employees in an organisation who need access to a wifi network and are issued Wi-Fi account certificates). + +## Account CA +The Account CA is the certificate authority responsible for issuing 24-hour short-lived certificates for securely accessing different workloads. When you create a Wi-Fi or VPN account via the Smallstep web app UI or API, the Agent obtains the respective Wi-Fi or VPN access certificate from the Account CA. + +Every Smallstep team has one Account Certificate Authority (CA). For each account or workload created, an X5C provisioner is created. + +After the Agent has obtained a device identity certificate from the Agent CA, it uses this certificate to obtain the necessary client workload certificate from the Account CA via an X5C provisioner. The Account CA trusts the Agent CA as a root of trust and verifies every request against the Agent CA’s public key. + +## Device Collection +A Device Collection is a named group of specific devices of the same ***type***, which share configurations or policies. + +A device type refers to a specific variant of a kind (such as VMs, laptops, or mobile phones) that runs the same OS (Windows, MacOS, Linux, iPadOS, or iOS), and comes from the same source (AWS, GCP, Azure, etc.). For instance, AWS VMs, Azure VMs, GCP VMs, and Linux laptops are different types of **Devices**. + +Collections are useful for applying shared configurations. There can be anywhere from zero to n devices in a collection. + +On the Smallstep web app, individual devices are created or added within collections. So, on the UI, the hierarchy is: list of collections > list of instances in a specific collection > details of a specific instance. This means that you first create a collection for a specific type of device and then add individual devices of the same type to that collection. + +## Provisioners +Provisioners provide the mechanism to verify the legitimacy of certificate signing requests and attest to the identity of the requesting entity. + +The role of a Certificate Authority is to issue certificates. However for the Certificate Authority to issue certificates to an entity, it needs to somehow verify that the entity is authorised to make a certificate request. + +Used to help bootstrap new entities into the PKI, each Provisioner addresses a particular environment. A certificate authority can have support different provisioners for enabling different use cases. A few examples include: + +- **X5C provisioner** - Useful for when a client can authenticate a certificate request using an existing X.509 certificate from a different CA. It allows clients to use a different PKI to bootstrap trust. Configure this provisioner with a root CA certificate, and any certificate that chains up to that root can be used in a certificate request. +- **ACME Provisioner** - Useful for automating TLS certificates, the ACME provisioner provides CSR generation, domain ownership verification, certificate download, and installation. With support for all of the ACME challenge types supported by Let’s Encrypt (HTTP, DNS, ALPN), the ACME provisioner unlocks the entire ACME ecosystem of tools and clients. +- **The SCEP Provisioner** - Useful for signing and renewing certificates using the SCEP protocol ([RFC8894](https://datatracker.ietf.org/doc/html/rfc8894)). SCEP is very popular for use in network equipment and mobile device management (MDM). It runs over HTTP using POSTed binary data or base64-encoded GET parameters, using CMS (PKCS#7) and CSR (PKCS#10) data formats, and a (shared) secret authenticates clients to the CA. +- **Cloud API Provisioners** - Useful for issuing certificates to public cloud virtual machines, Cloud API Provisioners use the native cloud provider API and instance identity documents to automate certificates. With support for AWS, GCP, and Azure metadata APIs, the Cloud API provisioner accelerates secure cloud operations. +- **OIDC Provisioner** - Useful for getting certificates to people, the OAuth/OpenID Connect (OIDC) Provisioner uses identity tokens for authentication. With this provisioner, you can use single sign-on with G Suite, Okta, Azure Active Directory, or any other OAuth OIDC provider to verify the user's identity before issuing a certificate. +- **JWK Provisioner** - Useful for a broad range of workflows, the JWK provisioner provides a flexible JSON Web Token-based authentication flow. Often paired with infrastructure automation solutions, the JWK Provisioner can deliver one-time tokens to a new workload to later be exchanged for an x.509 certificate. \ No newline at end of file From bd9412574815d006836df85d5b2a680a4e11d78d Mon Sep 17 00:00:00 2001 From: Linda-Ikechukwu Date: Mon, 24 Jun 2024 12:01:48 +0200 Subject: [PATCH 2/6] adding core concepts page --- platform/README.mdx | 4 ++-- platform/core-concepts.mdx | 26 ++++++++++++-------------- 2 files changed, 14 insertions(+), 16 deletions(-) diff --git a/platform/README.mdx b/platform/README.mdx index d6976e8f..73356d7e 100644 --- a/platform/README.mdx +++ b/platform/README.mdx @@ -99,7 +99,7 @@ Depending on what’s best for your infrastructure and current reality, Smallste ## Smallstep SaaS cloud offering -The Smallstep Saas cloud offering is our default recommended offering, unless you have security requirements that prohibit you from using a cloud CA. We also provide an ****API, Terraform Provider, and Ansible Collection for automation and IaC integration. +The Smallstep Saas cloud offering is our default recommended offering, unless you have security requirements that prohibit you from using a cloud CA. We also provide an API, Terraform Provider, and Ansible Collection for automation and IaC integration. ## Smallstep Run Anywhere @@ -119,7 +119,7 @@ We offer robust integration solutions for securing network connections to variou Our open-source toolchain for certificate and PKI management features 3 components: -- step CLI: A user-friendly command-line interface to build, operate, and automate PKI systems, with built-in support for ACME & the **`device-attest-01`** **challenge. +- step CLI: A user-friendly command-line interface to build, operate, and automate PKI systems, with built-in support for ACME & the **`device-attest-01`** challenge. - step-ca: A powerful online CA for secure, automated certificate management. - step-issuer and autocert: Kubernetes-native solutions for seamless certificate issuance and management in containerized environments. diff --git a/platform/core-concepts.mdx b/platform/core-concepts.mdx index b30db9aa..25ebcb59 100644 --- a/platform/core-concepts.mdx +++ b/platform/core-concepts.mdx @@ -9,16 +9,16 @@ Smallstep protects your organisation from phishing and data breach attacks, by l This document provides a 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. -Here’s what happens: +When using the Smallstep Agent to initiate high assurance [Cryptographic Attested Device Identity](https://smallstep.com/docs/platform/), here’s what happens: -1. As an administrator, you register company-owned or approved devices on the Smallstep web app using their hardware-attested identifiers, such as the TPM Endorsement Key (for Windows/Linux) or Secure Enclave ID (for Apple devices). -2. You (or your employee) installs **the** Smallstep Agent on a registered device. -3. The Smallstep Agent kicks off the device identity trust bootstrapping process by instructing the cryptographic processor (TPM or Secure Enclave) to create an Attestation Key (AK) ****pair. -4. The Smallstep Agent requests a device attestation certificate from the Smallstep Attestation CA. +1. As an administrator, you register each company-owned or approved device to a **Device Collection** on the Smallstep web app using their hardware-attested identifiers, such as the TPM Endorsement Key (for Windows/Linux) or Secure Enclave ID (for Apple devices). +2. You (or your employee) installs the **Smallstep Agent** on a registered device. +3. The Smallstep Agent kicks off the device identity trust bootstrapping process by instructing the cryptographic processor (TPM or Secure Enclave) to create an Attestation Key (AK) pair. +4. The Smallstep Agent requests a device attestation certificate from the **Smallstep Attestation CA**. 5. The Smallstep Attestation CA verifies that a)the request is coming from a company-owned or company-approved device by checking if the specific EK (the public part) is registered on your Smallstep team device inventory, and b)the request is coming from a device from which the Endorsement Key is resident by asking the TPM to complete a challenge instructing the EK private component to decrypt data encrypted with the EK public component. 6. Upon verification, the Smallstep Attestation CA signs an Attestation Certificate for the agent. The Attestation Certificate cannot be used for any purpose other than attestation. 7. The agent uses the Attestation certificate complete an ACME device-attest-01 challenge from the **Agent CA** to obtain an device (agent) certificate. -8. Finally, the agent uses the device certificate via an X5C **Provisioner** to obtain short-lived 24 hour workload certificates needed by the device, from your Smallstep Workload CA. +8. Finally, the agent uses the device certificate via an X5C **Provisioner** to obtain short-lived 24 hour client certificates needed by the device, from your **Smallstep Account CA**. This entire workflow doesn't require any credentials to be configured in the agent nor does it need passwords, therefore eliminating common attack vectors. The device certificate is stored only in memory, never saved to disk, and workload certificates are short-lived, lasting only 24 hours. This leaves nothing for an attacker to exfiltrate, significantly narrowing the attack vector. @@ -61,23 +61,21 @@ An Attestation Certificate (AKcert) is a type of device identity certificate sto To obtain an Attestation Certificate, the device must demonstrate to the Attestation CA that it possesses the hardware-bound private key of the cryptoprocessor. This Attestation Certificate is only used to establish a trust relationship with the device. The device agent uses it to acquire a device certificate that can be utilized for a variety of use cases. ## Account -An Account represents the way access is gained to a resource, like a wifi network, or VPN server, is typically oriented around end-users (like employees in an organisation who need access to a wifi network and are issued Wi-Fi account certificates). +An account is the means by which an end-user can access a resource protected by Smallstep, such as Wi-Fi, VPN, or a website. For instance, employees (their registered devices) in an organization who need access to a Wi-Fi network are issued Wi-Fi account certificates for their devices. ## Account CA -The Account CA is the certificate authority responsible for issuing 24-hour short-lived certificates for securely accessing different workloads. When you create a Wi-Fi or VPN account via the Smallstep web app UI or API, the Agent obtains the respective Wi-Fi or VPN access certificate from the Account CA. +The Account CA is the certificate authority responsible for issuing 24-hour short-lived certificates for securely accessing different resources. When you create a Wi-Fi or VPN account via the Smallstep web app UI or API, the Agent obtains the respective Wi-Fi or VPN access certificate from the Account CA. -Every Smallstep team has one Account Certificate Authority (CA). For each account or workload created, an X5C provisioner is created. +Every Smallstep team has one Account Certificate Authority (CA). For each account created, an X5C provisioner is created. -After the Agent has obtained a device identity certificate from the Agent CA, it uses this certificate to obtain the necessary client workload certificate from the Account CA via an X5C provisioner. The Account CA trusts the Agent CA as a root of trust and verifies every request against the Agent CA’s public key. +After the Agent has obtained a device identity certificate from the Agent CA, it uses this certificate to obtain the necessary client certificate from the Account CA via an X5C provisioner. The Account CA trusts the Agent CA as a root of trust and verifies every request against the Agent CA’s public key. ## Device Collection A Device Collection is a named group of specific devices of the same ***type***, which share configurations or policies. -A device type refers to a specific variant of a kind (such as VMs, laptops, or mobile phones) that runs the same OS (Windows, MacOS, Linux, iPadOS, or iOS), and comes from the same source (AWS, GCP, Azure, etc.). For instance, AWS VMs, Azure VMs, GCP VMs, and Linux laptops are different types of **Devices**. +A device type refers to a specific variant of a kind (such as VMs, laptops, or mobile phones) that runs the same OS (Windows, MacOS, Linux, iPadOS, or iOS), and comes from the same source (AWS, GCP, Azure, etc.). For instance, AWS VMs, Azure VMs, GCP VMs, and Linux laptops are different types of devices. -Collections are useful for applying shared configurations. There can be anywhere from zero to n devices in a collection. - -On the Smallstep web app, individual devices are created or added within collections. So, on the UI, the hierarchy is: list of collections > list of instances in a specific collection > details of a specific instance. This means that you first create a collection for a specific type of device and then add individual devices of the same type to that collection. +Device Collections are useful for applying shared configurations. There can be anywhere from zero to n devices in a collection. On the Smallstep web app, individual devices are created or added within collections. So, on the UI, the hierarchy is: list of collections > list of instances in a specific collection > details of a specific instance. This means that you first create a collection for a specific type of device and then add individual devices of the same type to that collection. ## Provisioners Provisioners provide the mechanism to verify the legitimacy of certificate signing requests and attest to the identity of the requesting entity. From a28b41a96a2bcd738756b10fc211aafe51791750 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Mon, 24 Jun 2024 16:01:43 -0700 Subject: [PATCH 3/6] Change Platform icon color and location on docs index page --- README.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.mdx b/README.mdx index d62cb828..aad486ab 100644 --- a/README.mdx +++ b/README.mdx @@ -4,6 +4,13 @@ disableSidebar: true

Documentation

+ -
From f58b708e1f2123a22a25f83067b24c2cf52247ff Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Mon, 1 Jul 2024 17:22:20 -0700 Subject: [PATCH 4/6] Updates to core concepts --- platform/core-concepts.mdx | 36 +++++++++++++++++------------------- 1 file changed, 17 insertions(+), 19 deletions(-) diff --git a/platform/core-concepts.mdx b/platform/core-concepts.mdx index 25ebcb59..e4b10f23 100644 --- a/platform/core-concepts.mdx +++ b/platform/core-concepts.mdx @@ -1,37 +1,35 @@ --- -title: Core Concepts? -html_title: Smallstep Core Concepts? +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. --- -![Device Identity Attestation Flow](/graphics/tpm-attestation.png) +![Image: Device Identity Attestation Flow](/graphics/tpm-attestation.png) Smallstep protects your organisation from phishing and data breach attacks, by limiting access to corporate resources to only company-owned or approved devices. -This document provides a 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. +This document provides an overview of the major components and concepts you’ll encounter in the Smallstep platform, and how they work together to protect your resources and provide strong assurance of device identity. -When using the Smallstep Agent to initiate high assurance [Cryptographic Attested Device Identity](https://smallstep.com/docs/platform/), here’s what happens: +Here's how Smallstep gets the right certificates to your devices. In this example, we'll assume we're enrolling a Windows or Linux device with a TPM 2.0 crypto processor chip. Apple devices enroll with Secure Enclave, but the workflow is similar. -1. As an administrator, you register each company-owned or approved device to a **Device Collection** on the Smallstep web app using their hardware-attested identifiers, such as the TPM Endorsement Key (for Windows/Linux) or Secure Enclave ID (for Apple devices). -2. You (or your employee) installs the **Smallstep Agent** on a registered device. -3. The Smallstep Agent kicks off the device identity trust bootstrapping process by instructing the cryptographic processor (TPM or Secure Enclave) to create an Attestation Key (AK) pair. -4. The Smallstep Agent requests a device attestation certificate from the **Smallstep Attestation CA**. -5. The Smallstep Attestation CA verifies that a)the request is coming from a company-owned or company-approved device by checking if the specific EK (the public part) is registered on your Smallstep team device inventory, and b)the request is coming from a device from which the Endorsement Key is resident by asking the TPM to complete a challenge instructing the EK private component to decrypt data encrypted with the EK public component. +1. As an administrator, you register your company-owned or approved devices in the Smallstep web UI, using a permanent identifier for the device, such as the TPM 2.0 Endorsement Public Key (EKPub). Smallstep has an API and integrations that simplify syncing device identiers from other services such as MDM servers or IT asset management services. +2. You (or your employee) installs the **Smallstep** app on a registered device. +3. The Smallstep app kicks off the device identity trust bootstrapping process by instructing the cryptographic processor (TPM) to create an Attestation Key (AK) pair. +4. The Smallstep app requests a device attestation certificate (AKCert) from the **Smallstep Attestation CA**. +5. The Smallstep Attestation CA verifies that: + a) The request is coming from a company-owned or company-approved device, by checking if the EKPub is registered on your Smallstep team device inventory, and + b) The request is coming from a device where the Endorsement Key is resident, by asking the TPM to decrypt a challenge encrypted by the CA using the EKPub. 6. Upon verification, the Smallstep Attestation CA signs an Attestation Certificate for the agent. The Attestation Certificate cannot be used for any purpose other than attestation. -7. The agent uses the Attestation certificate complete an ACME device-attest-01 challenge from the **Agent CA** to obtain an device (agent) certificate. -8. Finally, the agent uses the device certificate via an X5C **Provisioner** to obtain short-lived 24 hour client certificates needed by the device, from your **Smallstep Account CA**. +7. The agent uses the Attestation certificate complete an ACME `device-attest-01` challenge from the **Agent CA** to obtain a Smallstep device certificate. +8. Finally, the agent uses the Smallstep device certificate via an X5C **Provisioner** to obtain client certificates needed by the device, from your **Smallstep Account CA**. -This entire workflow doesn't require any credentials to be configured in the agent nor does it need passwords, therefore eliminating common attack vectors. The device certificate is stored only in memory, never saved to disk, and workload certificates are short-lived, lasting only 24 hours. This leaves nothing for an attacker to exfiltrate, significantly narrowing the attack vector. +This workflow requires no credentials be configured in the agent. No passwords. The Smallstep device certificate is stored only in memory, never saved to disk. The client certificates may be short-lived or have TPM-protected private keys, depending on what the operating system and the target application can support. ## Device Identifiers -Before restricting access to organizational resources to only your devices, you must know your devices. Smallstep offers a device inventory service to register and document your devices. +Before restricting access to organizational resources to only your devices, you must register your devices. Smallstep offers a device API to register and document your devices. Cryptographic processors used to establish trust in a device workflow come with a unique per-device asymmetric key pair that is hardcoded during manufacturing. For TPM modules, this key pair is known as the Endorsement Key. Sometimes, the TPM's manufacturer signs and includes an Endorsement Key Certificate (EKcert). For Apple's Secure Enclave, this is the Secure Enclave UID, a root cryptographic key fused to the secure enclave during manufacturing, and is inaccessible even to Apple. -When registering devices on Smallstep, you will need to provide the Key URI, which contains information about the public part of the key, as the device identifier. - -The private part of these hardware-bound keys, used as identifiers, cannot sign data. They can only decrypt data encrypted with their corresponding public key. This means these keys cannot be used to directly track a device's identity. However, they can provide strong assurance when used as part of trust evaluation because they can only be used on the device where they were created. - A third party could verify possession of an Endorsement Key pair by encrypting a small piece of data with the public key and asking the TPM to decrypt it with the private key. This simple device authentication mechanism offers the highest assurance that a request originates from a known device, compared to the SCEP + MDM enrolment process. ## Smallstep Agent @@ -89,4 +87,4 @@ Used to help bootstrap new entities into the PKI, each Provisioner addresses a p - **The SCEP Provisioner** - Useful for signing and renewing certificates using the SCEP protocol ([RFC8894](https://datatracker.ietf.org/doc/html/rfc8894)). SCEP is very popular for use in network equipment and mobile device management (MDM). It runs over HTTP using POSTed binary data or base64-encoded GET parameters, using CMS (PKCS#7) and CSR (PKCS#10) data formats, and a (shared) secret authenticates clients to the CA. - **Cloud API Provisioners** - Useful for issuing certificates to public cloud virtual machines, Cloud API Provisioners use the native cloud provider API and instance identity documents to automate certificates. With support for AWS, GCP, and Azure metadata APIs, the Cloud API provisioner accelerates secure cloud operations. - **OIDC Provisioner** - Useful for getting certificates to people, the OAuth/OpenID Connect (OIDC) Provisioner uses identity tokens for authentication. With this provisioner, you can use single sign-on with G Suite, Okta, Azure Active Directory, or any other OAuth OIDC provider to verify the user's identity before issuing a certificate. -- **JWK Provisioner** - Useful for a broad range of workflows, the JWK provisioner provides a flexible JSON Web Token-based authentication flow. Often paired with infrastructure automation solutions, the JWK Provisioner can deliver one-time tokens to a new workload to later be exchanged for an x.509 certificate. \ No newline at end of file +- **JWK Provisioner** - Useful for a broad range of workflows, the JWK provisioner provides a flexible JSON Web Token-based authentication flow. Often paired with infrastructure automation solutions, the JWK Provisioner can deliver one-time tokens to a new workload to later be exchanged for an x.509 certificate. From 62c5a7c8ffca313d657e1f3b4ee4746bdb33d45b Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Tue, 2 Jul 2024 10:09:35 -0700 Subject: [PATCH 5/6] Updates to core concepts --- platform/README.mdx | 23 ++++++----------------- platform/core-concepts.mdx | 18 ++++++++++-------- 2 files changed, 16 insertions(+), 25 deletions(-) diff --git a/platform/README.mdx b/platform/README.mdx index e0f5c0e8..1a3c423f 100644 --- a/platform/README.mdx +++ b/platform/README.mdx @@ -123,25 +123,14 @@ Our open-source toolchain for certificate and PKI management features 3 componen - step-ca: A powerful online CA for secure, automated certificate management. - step-issuer and autocert: Kubernetes-native solutions for seamless certificate issuance and management in containerized environments. -Join our open-source Discord community. +[Join our open-source Discord community.](https://u.step.sm/discord) -## Smallstep Enterprise CA +## `step-ca` Pro -Smallstep Enterprise CA is a drop-in upgrade for open-source certificate management toolchain, offering advanced features, support, and compliance options. It extends our open source with Device Identity features and integrations. +`step-ca` Pro is Smallstep's drop-in upgrade for our open-source Certificate Authority server, offering advanced features, support, and compliance options. It extends our open source with high availability, active revocation, FIPS compliance, simpler integrations and APIs, and device identity features. -The Enterprise CA is ideal for organisations who want full On-Prem Control or need to make the transition from open-source to commercial to access Device Identity capabilities and advanced compliance options. +`step-ca` Pro is ideal for organisations who want full On-Prem Control or need to make the transition from open-source to commercial to access Device Identity capabilities and advanced compliance options. -With Enterprise CA, just like our open source toolchain, you still maintain full control over the CA and root signing keys while benefiting from our cloud-based integrations and management interface. - -Key Features are: - -- Fast and lightweight setup on Linux, Kubernetes, and Docker -- Smallstep Device Identity, including MDM & posture integrations and active revocation (CRL & OCSP) -- High-volume certificate issuance with HSM integration -- FIPS and software supply-chain compliance, including SBOM & code-signing -- Broad support for enrollment protocols, such as SCEP, REST API, SSO (OAuth OIDC), SPIFFE, cloud identities, and Kubernetes integration -- Connectors for existing PKI backends (AD CS, GCP CAS, AWS PCM) -- High availability, automation, and CLM integration with Sectigo and Digicert - -We offer standard SLAs with 24-hour response for non-critical issues and 4-hour turnaround for critical incidents. For organizations requiring tailored assistance, enhanced support options are available, ensuring your infrastructure remains secure and operational. Contact Us. +With `step-ca` Pro, just like our open source packages, you maintain full control over the CA and signing keys while benefiting from our cloud-based integrations and management interface. +Interested? [Reach out to our Sales team](https://go.smallstep.com/request-demo). diff --git a/platform/core-concepts.mdx b/platform/core-concepts.mdx index e4b10f23..26092efa 100644 --- a/platform/core-concepts.mdx +++ b/platform/core-concepts.mdx @@ -12,17 +12,19 @@ This document provides an overview of the major components and concepts you’ll Here's how Smallstep gets the right certificates to your devices. In this example, we'll assume we're enrolling a Windows or Linux device with a TPM 2.0 crypto processor chip. Apple devices enroll with Secure Enclave, but the workflow is similar. 1. As an administrator, you register your company-owned or approved devices in the Smallstep web UI, using a permanent identifier for the device, such as the TPM 2.0 Endorsement Public Key (EKPub). Smallstep has an API and integrations that simplify syncing device identiers from other services such as MDM servers or IT asset management services. -2. You (or your employee) installs the **Smallstep** app on a registered device. +2. You (or your employee) installs the **Smallstep app** on a registered device. 3. The Smallstep app kicks off the device identity trust bootstrapping process by instructing the cryptographic processor (TPM) to create an Attestation Key (AK) pair. 4. The Smallstep app requests a device attestation certificate (AKCert) from the **Smallstep Attestation CA**. 5. The Smallstep Attestation CA verifies that: a) The request is coming from a company-owned or company-approved device, by checking if the EKPub is registered on your Smallstep team device inventory, and b) The request is coming from a device where the Endorsement Key is resident, by asking the TPM to decrypt a challenge encrypted by the CA using the EKPub. -6. Upon verification, the Smallstep Attestation CA signs an Attestation Certificate for the agent. The Attestation Certificate cannot be used for any purpose other than attestation. -7. The agent uses the Attestation certificate complete an ACME `device-attest-01` challenge from the **Agent CA** to obtain a Smallstep device certificate. -8. Finally, the agent uses the Smallstep device certificate via an X5C **Provisioner** to obtain client certificates needed by the device, from your **Smallstep Account CA**. +6. Upon verification, the Smallstep Attestation CA signs an Attestation Certificate for the app. The Attestation Certificate cannot be used for any purpose other than attestation. +7. The app uses the Attestation certificate complete an ACME `device-attest-01` challenge from the **Agent CA** to obtain a Smallstep device certificate. +8. Finally, the app uses the Smallstep device certificate via an X5C **Provisioner** to obtain client certificates needed by the device, from your **Smallstep Account CA**. -This workflow requires no credentials be configured in the agent. No passwords. The Smallstep device certificate is stored only in memory, never saved to disk. The client certificates may be short-lived or have TPM-protected private keys, depending on what the operating system and the target application can support. +This workflow requires no credentials be configured in the app. No passwords. The Smallstep device certificate is stored only in memory, never saved to disk. The client certificates may be short-lived or have TPM-protected private keys, depending on what the operating system and the target application can support. + +# Definitions ## Device Identifiers @@ -32,10 +34,10 @@ Cryptographic processors used to establish trust in a device workflow come with A third party could verify possession of an Endorsement Key pair by encrypting a small piece of data with the public key and asking the TPM to decrypt it with the private key. This simple device authentication mechanism offers the highest assurance that a request originates from a known device, compared to the SCEP + MDM enrolment process. -## Smallstep Agent -The Smallstep agent is lightweight background software that offers a uniform experience for device identity across MacOS, Windows, and Linux platforms. 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. +## 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 agent 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 operates without administrative privileges. It only collects the device security context essential for your organisation's administrative policy configuration. After proving its identity to the Smallstep Attestation CA, the agent 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. From a98c2722a77169e17e17cd59fc26f02fd8925d8f Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Tue, 2 Jul 2024 10:22:19 -0700 Subject: [PATCH 6/6] Update core concepts --- platform/core-concepts.mdx | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/platform/core-concepts.mdx b/platform/core-concepts.mdx index 26092efa..39bfdc94 100644 --- a/platform/core-concepts.mdx +++ b/platform/core-concepts.mdx @@ -5,6 +5,8 @@ description: High-level overview of the major components and concepts you’ll e --- ![Image: Device Identity Attestation Flow](/graphics/tpm-attestation.png) +# Workflow Overview + Smallstep protects your organisation from phishing and data breach attacks, by limiting access to corporate resources to only company-owned or approved devices. This document provides an overview of the major components and concepts you’ll encounter in the Smallstep platform, and how they work together to protect your resources and provide strong assurance of device identity. @@ -39,7 +41,7 @@ The Smallstep app is a desktop app that offers a uniform experience for device i 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. -After proving its identity to the Smallstep Attestation CA, the agent 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. +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. ## Smallstep Attestation CA The Smallstep Attestation CA service is responsible for verifying the identity of a device that is authenticating itself. It confirms that the key presented by the device is hardware-bound and that the device is a known device registered to your Smallstep team account. @@ -53,12 +55,12 @@ Devices like Apple and Yubikeys have an Attestation CA maintained by their manuf The Attestation CA was built into the Smallstep platform to provide a uniform standard device identity attestation protocol. ## Agent CA -The Agent CA is the certificate authority responsible for issuing, renewing, and revoking agent (device) certificates for device identity. It is configured to trust the Smallstep Attestation CA. As a result, when the agent receives an Attestation Certificate from the Smallstep Attestation CA, it can use this certificate to procure a device identity certificate from the Agent CA by completing an ACME device-attest-01 challenge or another certificate enrollment method, in cases where the former is not possible. +The Agent CA is the certificate authority responsible for issuing, renewing, and revoking device certificates for device identity. It is configured to trust the Smallstep Attestation CA. As a result, when the app receives an Attestation Certificate from the Smallstep Attestation CA, it can use this certificate to procure a device identity certificate from the Agent CA by completing an ACME device-attest-01 challenge or another certificate enrollment method, in cases where the former is not possible. ## Attestation Key (AK) Certificate An Attestation Certificate (AKcert) is a type of device identity certificate stored in the TPM, with its private key hardware-bound. The Attestation Certificate is provided to a trusted device after the Smallstep Attestation CA has verified its authenticity. -To obtain an Attestation Certificate, the device must demonstrate to the Attestation CA that it possesses the hardware-bound private key of the cryptoprocessor. This Attestation Certificate is only used to establish a trust relationship with the device. The device agent uses it to acquire a device certificate that can be utilized for a variety of use cases. +To obtain an Attestation Certificate, the device must demonstrate to the Attestation CA that it possesses the hardware-bound private key of the cryptoprocessor. This Attestation Certificate is only used to establish a trust relationship with the device. The device uses it to acquire a device certificate, which is then used as an authentication token for client certificates. ## Account An account is the means by which an end-user can access a resource protected by Smallstep, such as Wi-Fi, VPN, or a website. For instance, employees (their registered devices) in an organization who need access to a Wi-Fi network are issued Wi-Fi account certificates for their devices. @@ -75,12 +77,11 @@ A Device Collection is a named group of specific devices of the same ***type***, A device type refers to a specific variant of a kind (such as VMs, laptops, or mobile phones) that runs the same OS (Windows, MacOS, Linux, iPadOS, or iOS), and comes from the same source (AWS, GCP, Azure, etc.). For instance, AWS VMs, Azure VMs, GCP VMs, and Linux laptops are different types of devices. -Device Collections are useful for applying shared configurations. There can be anywhere from zero to n devices in a collection. On the Smallstep web app, individual devices are created or added within collections. So, on the UI, the hierarchy is: list of collections > list of instances in a specific collection > details of a specific instance. This means that you first create a collection for a specific type of device and then add individual devices of the same type to that collection. +Device Collections are useful for applying shared configurations. ## Provisioners -Provisioners provide the mechanism to verify the legitimacy of certificate signing requests and attest to the identity of the requesting entity. -The role of a Certificate Authority is to issue certificates. However for the Certificate Authority to issue certificates to an entity, it needs to somehow verify that the entity is authorised to make a certificate request. +Provisioners provide various mechanism to authenticate certificate signing requests. The role of a Certificate Authority is to issue certificates to end entities, and it needs to somehow verify that the entity is authorised to make a certificate request. Used to help bootstrap new entities into the PKI, each Provisioner addresses a particular environment. A certificate authority can have support different provisioners for enabling different use cases. A few examples include: