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

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

@@ -0,0 +1,74 @@
+(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.
+
+## Authentication
+
+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. Clients such as the snap command-line tool read this file and include the relevant credentials when making requests to the snapd API. These credentials allow snapd to authenticate subsequent snapd API requests and perform operations for the user. When a user logs out using snap logout, the local authentication data and associated snapd user identity are removed.
+
+## API authorization mechanisms
+
+After a request to the snapd API is authenticated, snapd determines whether the caller is permitted to perform the requested operation. Snapd uses several authorization mechanisms depending on the operation being performed.
+
+### Open access
+
+Some API endpoints are available without authentication. These endpoints typically expose read-only information about snapd or the system.
+
+### Root access
+
+Requests originating from the root user are authorized to perform administrative operations on the system. This includes actions such as installing, removing, or refreshing snaps.
+
+### API credentials
+
+Snapd supports authentication using API credentials, represented by a local macaroon associated with a snapd user. Clients include these credentials when making API requests, allowing snapd to authenticate and authorize the request on behalf of the associated snapd user.
+
+### PolicyKit
+
+For certain privileged operations initiated by non-root users, snapd may defer the authorization decision to polkit. Polkit allows the system to prompt the user for confirmation or otherwise grant permission to perform the requested action.
+
+### Interface-based authorization
+
+Some API operations exposed through the snap API access socket require the snap associated with the calling process to have specific interfaces connected. Interface connections define which system resources a snap is permitted to access. If the required interface is not connected, the operation will not be authorized.
+
+## 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 {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>

docs/explanation/security/security-policies.md

@@ -80,12 +80,20 @@ Locally, these are handled by the snap daemon, *snapd*, while remote connections
 * **Hashing of snaps**</br>
 [SHA3-384]
 * **HTTPS communication**</br>
-Snapd uses the [Go standard library TLS package] for the client, configured to use at least TLS >= 1.2.
+Snapd uses the [Go standard library TLS package] for the client, configured to use TLS 1.2 or later.
 * **Device session request signing**</br>
 Same as digital signatures for assertions: [SHA3-384], [SHA512] and [OpenGPG signature packet]. [RSA] 4096 device key.
 * **Macaroons for authorisation and authentication**</br>
 Snapd uses them via [Go macaroon V1], which means [SHA256] [HMAC]s and [NaCL secretbox].
 
+In the standard snapd, cryptographic functionality is provided by Go’s native cryptographic implementations from the Go standard library. These implementations may make use of architecture-specific optimizations (CPU instruction set extensions such as AES-NI or SHA) where available.
+
+Snapd is also being developed in a FIPS variant - not yet generally available - in which cryptographic operations are provided by OpenSSL rather than Go’s native implementations. In this variant, OpenSSL may either be bundled with snapd or supplied by the host system, enabling integration with cryptographic modules validated under FIPS in environments that require FIPS compliance. For more information about FIPS see: [Information about FIPS on Ubuntu 22.04].
+
+In both variants, cryptographically secure randomness is sourced from the operating system via the Linux kernel’s randomness interfaces (for example getrandom(2)), which provide entropy to user-space cryptographic libraries.
+
+[Information about FIPS on Ubuntu 22.04]: https://ubuntu.com/security/certifications/docs/2204/fips#p-99917-updates-and-preview
+
 ### Snap Store cryptography
 
 * **Digital signatures for [assertions](https://ubuntu.com/core/docs/reference/assertions)**</br>
@@ -179,9 +187,9 @@ Before _refresh awareness_ became available, if a refresh occurred while a snap
 (ref-security-policies_refresh-awareness)=
 ### Refresh awareness
 
-By default, a service running from a snap needs to be restarted whenever the snap is refreshed (see {ref}`Services and daemons <explanation-security-security-policies>`) for more details).
+By default, a service running from a snap needs to be restarted whenever the snap is refreshed (see {ref}`Services and daemons <explanation-security-security-policies>` for more details).
 
-Stopping and starting a service is a requirement to support {ref}`snap revert <explanation-security-security-policies>`) and its copying of a snap’s system data from the current version to the new version.
+Stopping and starting a service is a requirement to support {ref}`snap revert <explanation-security-security-policies>` and its copying of a snap’s system data from the current version to the new version.
 
 System data typically includes databases, data files, and configuration files (see {ref}`Data locations <interfaces-data-locations>`), although all of this is up to the snap developer.
 
@@ -201,7 +209,7 @@ Snapd includes the following built-in features that interacts with user informat
 * {ref}`Snapshots <how-to-guides-manage-snaps-create-data-snapshots>` of snap {ref}`user data <interfaces-data-locations>`
 * The {ref}`home <interfaces-home-interface>` interface allows access to non-hidden files in the user’s home
 * The {ref}`personal-files <interfaces-personal-files-interface>` interface allows access to specified files in the user's home
-* {ref}`Persisted data on Ubuntu Core devices <interfaces-data-locations>`
+* {ref}`Persisted data on Ubuntu Core devices <interfaces-data-locations_ubuntu-core-persisted-data>`
 
 Snapd is designed to make these interactions secure by default. Developers are expected to implement their own data storage solutions, e.g. database and configuration files, on top of snapd’s secure mechanisms. This means developers share responsibility for ensuring the availability, integrity, confidentiality, and compatibility of user data over the lifetime of a snap or snap-based product.
 
@@ -226,5 +234,33 @@ Sometimes it is also required to extend what is allowed by an existing interface
   * {ref}`File permissions and cgroups <explanation-security-security-policies>`
 * {ref}`How to request store approval for snap policy changes <interfaces-reviewing-classic-confinement-snaps>`
 
-To publish a classic snap that operates outside these restrictions it is required to request a classic confinement request that involves a rigorous process for vetting the publisher.
+To publish a classic snap that operates outside these restrictions, you must submit a classic confinement request that involves a rigorous process for vetting the publisher.
+
+## Security maintenance
+
+Snapd is delivered both as Debian packages and as snaps, and the security maintenance responsibilities and lifecycles differ depending on the delivery mechanism.
+
+The snapd Debian packages are maintained by the Ubuntu Security Team and receive security updates through the standard Ubuntu security maintenance process. The duration of this maintenance follows the [Ubuntu Release Cycle]. This lifecycle applies only to the snapd deb packages provided as part of Ubuntu releases.
+
+The snapd snap is maintained by the snapd team, who are responsible for delivering security updates through snap revisions. The lifecycle and maintenance model for snapd snaps is separate from the Ubuntu release lifecycle and follows the Ubuntu Core and snap track maintenance model.
+
+Ubuntu Core 16 includes snapd embedded within the core snap (which functions as the base operating system snap). Security maintenance for snapd in the Ubuntu Core 16 core snap is handled by the snapd team through updates to the core snap.
+
+[Ubuntu Release Cycle]: https://ubuntu.com/about/release-cycle
+
+### Security updates
+
+The snapd team allocates capacity for security fixes following each major snapd release. Major snapd releases currently occur on an approximately two-month cadence, and a planned security update window is scheduled after each major release.
+
+These security update releases are primarily intended to address high-priority security vulnerabilities that require timely remediation outside of the normal feature release cycle.
+
+Lower-priority security vulnerabilities may be accumulated and delivered as part of these planned security update releases. Security updates may be released outside of this preferred cadence where required to address critical vulnerabilities.
+
+Security vulnerabilities are handled under a responsible disclosure process. Security issues are tracked and developed privately and are not publicly visible until fixes are released and the vulnerability is disclosed. This ensures that users receive fixes before detailed vulnerability information becomes publicly available.
+
+### How to report vulnerabilities
+
+Please report [suspected security vulnerabilities] **privately** by following the instructions in [SECURITY.md].
 
+[suspected security vulnerabilities]: https://github.com/canonical/snapd/blob/master/SECURITY.md#what-qualifies-as-a-security-issue
+[SECURITY.md]: https://github.com/canonical/snapd/blob/master/SECURITY.md#reporting-a-vulnerability

docs/explanation/security/snap-confinement.md

@@ -12,7 +12,7 @@ A snap's confinement level controls the degree of isolation it has from the user
 There are two levels of snap confinement for published snaps:
 - **Strict** 
    Used by the majority of snaps. Strictly confined snaps run in complete isolation, up to a minimal access level that's deemed always safe. Consequently, strictly confined snaps can not access files, network, processes or any other system resource without requesting specific access via an interface.
-- **Classic**
+- {ref}`**Classic** <explanation-security-classic-confinement>`
    Allows access to the system's resources in much the same way traditional packages do. To safeguard against abuse, publishing a classic snap requires {ref}`manual approval <interfaces-reviewing-classic-confinement-snaps>`, and installation requires the `--classic` command line argument.
 
 An additional mode is useful during the development process:

docs/reference/administration/data-locations.md

@@ -35,6 +35,7 @@ Snaps can also contain user data. As with the system data environment variables,
 
 Both `SNAP_USER_COMMON` and `SNAP_USER_DATA` only become available after a snap has been run once.
 
+(interfaces-data-locations_ubuntu-core-persisted-data)=
 ### Ubuntu Core
 
 On Ubuntu Core, the **`SNAP_SAVE_DATA`** environment variable within a snap's environment points to a snap-specific location on the [ubuntu-save](https://ubuntu.com/core/docs/uc20/inside#heading--layouts) volume. This is used to store data that can be accessed during recovery or after re-installation of Ubuntu Core.