docs/explanation/security: modified snapd security documentation to be SEC30 V1.3 compliant

docs/explanation/security/api-authentication-and-authorization.md

@@ -0,0 +1,117 @@
+(explanation-security-api-authentication-and-authorization)=
+# API Authentication and Authorization
+
+Snapd performs authentication and authorization checks before executing operations that may affect system state or modify snap security policies. These checks are applied to interactions with the snapd REST API, which is the primary interface used by the snap command-line tool and other clients. Authentication establishes the identity of the caller, while authorization determines whether that identity is permitted to perform a given operation. Many snap management operations - such as installing snaps, connecting interfaces, or refreshing packages - may alter the system’s security posture. Snapd therefore ensures that only authenticated and authorized callers can perform such operations.
+
+## User identities in snapd
+
+Snapd distinguishes between three related types of users.
+
+### Snapd user
+
+A snapd user is a local identity maintained by snapd. It represents an authenticated user within snapd and is used when authorizing API requests.
+
+Each snapd user is uniquely identified by:
+
+- a snapd user ID
+- a snapd macaroon
+
+Multiple snapd users may refer to the same store identity.
+
+### Store user
+
+A store user is an identity managed by the Snap Store and authenticated through login.ubuntu.com. Store users are uniquely identified by their email address. When a user logs in using snap login, the store identity is associated with a local snapd user. The Snap Store provides authentication tokens (macaroons and discharges) that allow snapd to interact with the store on behalf of that user.
+
+### Linux system user
+
+A Linux system user is a standard user account on the host operating system. System users are uniquely identified by their system username or user ID (UID). Snapd may associate a Linux system user with a snapd user so that API requests originating from that account can be authenticated and authorized. In managed environments such as Ubuntu Core systems, Linux system users may be created from system-user assertions signed by the device brand, or from user information retrieved from the Snap Store for a given store user email address.
+
+On system user removal, the Linux system user is removed as well as the associated snapd user. The identity file ($HOME/.snap/auth.json) is removed indirectly when the system user is removed.
+
+## Authentication
+
+Snapd authenticates users using peer credential passing, snapd local macaroons, and Polkit authentication requests. Snaps are authenticated using PID-based cgroup lookup to determine which snap a requesting process belongs to.
+
+### Summary of identities and layered authentication mechanisms
+
+| Identity                    | Mechanism                   | Description                                                |
+|-----------------------------|-----------------------------|------------------------------------------------------------|
+| Snapd user                  | Local macaroons             | Authenticates the snapd user                               |
+| System user                 | `SO_PEERCRED`, `SOL_SOCKET` | Authenticates calling system process, user and socket      |
+| System admin                | Polkit                      | Authenticates system user as administrator                 |
+| Calling snap                | PID → cgroup lookup         | Authenticates the snap that the calling process belongs to |
+
+#### Snapd local macaroon
+
+When a user logs in to the Snap Store using `snap login`, snapd creates or updates the associated snapd user and stores authentication information locally.
+The authenticated identity is persisted in:
+
+```console
+$HOME/.snap/auth.json
+```
+
+This file contains the snapd user identity and local authentication tokens (local macaroons). The `snap` command-line tool reads this file and includes the relevant credentials in the request headers when making snapd API calls. These credentials allow snapd to authenticate snapd API calls on behalf of the logged-in user. When a user logs out using `snap logout`, the local authentication data and associated snapd user identity are removed.
+
+#### Unix domain socket peer credential passing
+
+UNIX domain socket peer credentials (`SO_PEERCRED`) allows a server to securely obtain  the Process ID (PID), User ID (UID), and socket to which the peer connection was established, directly from the kernel.
+
+#### PID-based cgroup snap lookup
+
+Snapd authenticates snaps by performing a cgroup lookup using the process PID obtained from peer credentials to determine which snap the requesting process belongs to. This identifies the calling snap, whose connected interfaces are then used for authorization decisions. The cgroup is assigned during process bootstrap, and the sandbox prevents the snap process from moving itself to a different cgroup, which helps protect this mechanism against spoofing.
+
+#### Polkit authenticaton requests
+
+Certain snapd API operations are authorized via Polkit. For these operations, snapd queries Polkit to determine whether the caller is permitted to perform the requested action. Polkit is an authorization framework that may require user or administrator authentication before authorization is granted.
+
+Polkit actions with suitable messages for different scenarios are defined in:
+
+```console
+/usr/share/polkit-1/actions/io.snapcraft.snapd.policy
+```
+
+## Authorization
+
+After authenticating the calling snap, system user, socket and snapd user, snapd determines whether the caller is authorized to perform the requested operation with access level specified by the API endpoint policy.
+For details about API endpoint policy refer to the [snapd API documentation].
+
+[snapd API documentation]: https://snapcraft.io/docs/reference/development/snapd-rest-api/
+
+### Base access levels
+
+#### Open
+
+Allows requests without authentication, provided they have peer credentials and were not received on `snapd-snap.socket`.
+
+#### Authenticated
+
+Allows requests from authenticated users, provided they were not received on `snapd-snap.socket`.
+
+#### Root
+
+Allows requests from the root UID (0), provided they were not received on `snapd-snap.socket`
+
+### Other variations
+
+#### Snap
+
+Allows requests from the `snapd-snap.socket` only.
+
+#### Interface \<base access level\>
+
+Additive to the corresponding base access level. Allows requests from `snapd-snap.socket` for snaps that plug one of the required interfaces, or carry a required slot.
+
+#### Interface provider root
+
+Additive to the root access level. Allows requests over `snapd-snap.socket` for snaps that have a connection of specific interface and are present on the slot side of that connection.
+
+## Interaction with snap security policies
+
+Snap confinement is enforced through security policies generated by snapd using mechanisms such as:
+
+- AppArmor
+- seccomp
+- cgroups
+- Linux namespaces
+
+These policies define the level of isolation and permitted access for each snap and are typically derived from the interfaces declared and connected for that snap. Authorized operations performed through the snapd API - such as installing snaps or connecting interfaces - may cause snapd to generate or update these policies. Once generated, the policies are enforced by the Linux kernel. For more information, refer to the {ref}`security policies <explanation-security-security-policies>`.

docs/explanation/security/decommissioning.md

@@ -0,0 +1,72 @@
+(explanation-security-decommissioning)=
+# Decommissioning
+
+Snapd runs on three system types:
+
+ - [Ubuntu Core]
+ - Hybrid Classic
+ - Classic
+
+The approach to decommissioning snapd differs depending on the system type, as snapd provides core system functionality on Ubuntu Core and Hybrid Classic systems, but is an optional package on Classic Ubuntu systems.
+
+[Ubuntu Core]: https://documentation.ubuntu.com/core/
+
+## Ubuntu Core systems
+
+On Ubuntu Core systems, snapd is a fundamental component of the operating system and part of the overall device image and product lifecycle. Ubuntu Core devices are typically deployed as integrated IoT or appliance-style systems with a fixed software lifetime.
+
+Decommissioning of Ubuntu Core systems should be performed at the system level rather than by removing snapd, and is therefore outside the scope of this section.
+
+## Hybrid Classic systems
+
+Hybrid Classic system is a classic system with kernel snap e.g. Ubuntu 26.04 using the TPM backed FDE installation option. It provides a Classic Ubuntu user experience but rely on snapd for essential system functionality such as system snaps, recovery, and full disk encryption. On these systems, snapd is not an optional component and should not be removed.
+
+Decommissioning of Hybrid Classic systems should be performed at the system level rather than by removing snapd, and is therefore outside the scope of this section.
+
+## Classic systems
+
+On Classic Ubuntu systems, snapd is an optional component and may be decommissioned if it is no longer required. Snapd is bootstrapped by the snapd deb package, but installation of any non-essential snap (core, gadget, kernel, snapd) would also trigger installation of snapd snap. On Classic Ubuntu systems, re-execution is enabled by default, which means the deb package will re-execute to snapd provided by the snap package whenever that version is more recent than the deb package version.
+
+Decommissioning snapd on Classic systems involves:
+
+ - Removing installed snaps
+ - Removing the snapd package
+ - Removing remaining snap data, state directories, and stored snapshots (including user, system, and configuration data)
+
+Typical locations where snap data may remain include:
+
+- `/var/snap/`:         Snap system data and persistent application data
+- `/var/lib/snapd/`:    Snapd state, installed snap revisions, assertions, snapshots
+- `/var/cache/snapd/`:  Downloaded snap packages and cache
+- `/snap/`:             Mounted snap squashfs files (read-only runtime files)
+- `/home/$USER/snap/`:  Per-user snap data, configuration, and user files
+- `/home/$USER/.snap/`: Authentication data and signing keys
+- `/var/log/journal/`:  Persistent logging (configurable)
+- `/run/log/journal/`:  Non-persistent logging (default)
+
+### Removing installed snaps
+
+Removal of the snapd snap requires first removing all other snaps. Removing installed snaps with `snap remove --purge <snap>` prevents taking an automatic snapshot, however existing [snapshots] still remain.
+
+[snapshots]: https://snapcraft.io/docs/how-to-guides/manage-snaps/create-data-snapshots/
+
+### Removing the snapd snap
+
+When all other snaps have been removed the snapd snap can also be removed. Removal of the snapd snap does not remove /var/lib/ in order to allow the snapd deb package
+to function.
+
+### Removing the snapd deb package
+
+Removal of the snapd deb package with `sudo apt remove --purge snapd` removes:
+- `/var/snap`
+- `/var/lib/snapd/`
+- `/var/cache/snapd/`
+- `/snap/`
+
+### User data
+
+If required, root and other user data should be manually removed by wiping `/root/snap/` and `/root/.snap/` as well as `/home/$USER/snap/` and `/home/$USER/.snap/`.
+
+### Removing journal logs
+
+If deemed necessary, journal containing snapd logs can be removed, but this cannot be done cleanly without impacting non-snapd logging. Identify if the journal contains any snapd files using `journalctl --directory=/var/log/journal -u snapd` and remove the log if required.

docs/explanation/security/index.md

@@ -10,8 +10,11 @@ myst:
 Learn about how snaps use standard Linux security policies to isolate themselves from the system, and from each other.
 
 * {ref}`Security policies <explanation-security-security-policies>`: How we use AppArmor, Seccomp and cgroups to secure snaps.
-* {ref}`Snap confinement <explanation-security-snap-confinement>`: Learn more about snap's various degrees of isolation.
 * {ref}`Assertions <explanation-security-assertions>`: Digitally signed documents used to verify all snap artefacts.
+* {ref}`Snap confinement <explanation-security-snap-confinement>`: Learn more about snap's various degrees of isolation.
+* {ref}`Classic confinement <explanation-security-classic-confinement>`: Learn more about classic confinement.
+* {ref}`API authentication and authorization <explanation-security-api-authentication-and-authorization>`: How snapd authenticates API callers and authorizes operations.
+* {ref}`Decommissioning <explanation-security-decommissioning>`: How to completely remove snapd and associated data.
 * {ref}`Snapd release process <explanation-security-snapd-release-process>`: How and when we update the snapd package.
 
 
@@ -21,8 +24,10 @@ Learn about how snaps use standard Linux security policies to isolate themselves
 :maxdepth: 2
 :glob:
 
+Security policies <security-policies>
 Assertions <assertions>
 Snap confinement <snap-confinement>
-Security policies <security-policies>
 Classic confinement <classic-confinement>
+API authentication and authorization <api-authentication-and-authorization>
+Decommissioning <decommissioning>
 Release process <snapd-release-process>