Wi-Fi & VPN
      Back to home
      1. Smallstep Knowledge Base
      2. Device Identity
      3. Wi-Fi & VPN

      Learn how the Smallstep agent works

      How the Smallstep agent manages your resources

      Agent workflow on macOS — Wi-Fi

      1. Issuance or renewal of certificate happens before any configuration changes are applied to the system.
      2. We use Apple APIs to apply Wi-Fi configuration, using platform-specific reference to the certificate’s serial number. So, it links to key pairs in the login Keychain.
        • The first time any Wi-Fi network is added:
          • The agent will force a prompt asking the user for permission to create a Wi-Fi configuration. This does not happen for MDM-managed Wi-Fi configurations.
            • The agent will emit an error if the user says no.
          • The agent will force a prompt asking the user for location permissions, which is required to allow the agent to scan Wi-Fi networks. This does not happen for MDM-managed Wi-Fi configurations.
            • The agent will emit an error if the user says no.
      3. If the agent can’t find the Wi-Fi network SSID being configured, an error is emitted to Smallstep.
      4. If the configuration changes are applied successfully, we try to initiate a Wi-Fi connection based on the auto-join setting in Smallstep.

        • When the connection is established, Apple’s Wi-Fi client will ask to use the agent-managed key from the keychain. If the user says no, there’s no way to log this as an error to Smallstep.

          Note: For MDM deployments of Wi-Fi configurations, MDM client also prompts for permission to use an MDM-managed key.

        • If the Wi-Fi connection fails or the configuration change is not applied successfully, an error is logged to Smallstep (if there is network connectivity)

      5. We continually renew the certificate once it reaches 60% of its lifetime. We don’t rekey unless you change the key type. In which case, Apple’s Wi-Fi client will ask the user again for permission to use the key.

      Agent workflow on Linux — Wi-Fi

      1. Issuance or renewal of certificate happens before any configuration changes are applied to the system.

      2. We use NetworkManager APIs over dbus to apply Wi-Fi configuration, using platform-specific keypair references. If the key format is not hardware-protected, we use filesystem-based key and certificate objects. If the key format is hardware-protected, we will use PKCS#11.

        • The agent runs as root by default, so it has access to talk over dbus to the NetworkManager APIs.
        • Right now, by default, only the device identity certificate is hardware-attested. Endpoint keypairs are not configured as hardware-protected by default. They are derived credentials based off of the device identity certificate.

      3. If the agent can’t find the Wi-Fi network SSID being configured, an error is emitted to Smallstep.

      4. If the configuration changes are applied successfully, we try to initiate a Wi-Fi connection based on the auto-join setting in Smallstep

        If there are any issues applying the configuration or joining the Wi-Fi network, we emit an error from the Smallstep agent. Including: WI-Fi SSID not found, no network adapter found, certificate rejected by the server, configuration not applied successfully.

      5. We continually renew the certificate once it reaches 60% of its lifetime. We don’t rekey, unless you decide to change the key type in Smallstep.

      Agent workflow on macOS — VPN

      1. Issuance or renewal of certificate happens before any configuration changes are applied to the system.
      2. We use Apple APIs to apply VPN configuration, using platform-specific reference to the certificate’s serial number. So, it links to key pairs in the login Keychain.
        • The first time any Wi-Fi network is added:
          • The agent will force a prompt asking the user for permission to create a VPN configuration. This does not happen for MDM-managed VPN configurations.
            • The agent will emit an error if the user says no.
      3. If the configuration changes are applied successfully, we try to initiate a VPN connection based on the auto-join setting in Smallstep.

        • When the connection is established, Apple’s VPN client will ask to use the agent-managed key from the keychain. If the user says no, there’s no way to log this as an error to Smallstep.

          Note: For MDM deployments of VPN configurations, the MDM client also prompts for permission to use an MDM-managed key.

        • If the VPN connection fails or the configuration change is not applied successfully, an error is logged to Smallstep

      4. We continually renew the certificate once it reaches 60% of its lifetime. We don’t rekey, unless you changes the key type. (In which case, Apple’s VPN client will ask the user again for permission to use the key).

      Agent workflow on Linux — VPN

      Because Linux Wi-Fi and VPN connections are managed by NetworkManager, this flow is identical to the Wi-Fi flow for Linux.

      Agent workflow on Linux — Wi-Fi 802.1X Ethernet

      Because Linux Wi-Fi and VPN connections are managed by NetworkManager, this flow is identical to the Wi-Fi flow for Linux.