diff options
Diffstat (limited to 'Documentation/security')
| -rw-r--r-- | Documentation/security/IMA-export-delete.rst | 203 | ||||
| -rw-r--r-- | Documentation/security/credentials.rst | 8 | ||||
| -rw-r--r-- | Documentation/security/index.rst | 1 | ||||
| -rw-r--r-- | Documentation/security/ipe.rst | 10 | ||||
| -rw-r--r-- | Documentation/security/keys/trusted-encrypted.rst | 138 | ||||
| -rw-r--r-- | Documentation/security/landlock.rst | 51 | ||||
| -rw-r--r-- | Documentation/security/self-protection.rst | 2 |
7 files changed, 401 insertions, 12 deletions
diff --git a/Documentation/security/IMA-export-delete.rst b/Documentation/security/IMA-export-delete.rst new file mode 100644 index 000000000000..1600ead03b03 --- /dev/null +++ b/Documentation/security/IMA-export-delete.rst @@ -0,0 +1,203 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================== +IMA Measurements Export and Delete +================================== + + +Introduction +============ + +The IMA measurements list is currently stored in the kernel memory. Memory +occupation grows linearly with the number of records, and can become a +problem especially in environments with reduced resources. + +While there is an advantage in keeping the IMA measurements list in kernel +memory, so that it is always available for reading from the securityfs +interfaces, storing it elsewhere would make it possible to free precious +memory for other kernel usage. + +The IMA measurements list needs to be retained and safely stored for new +attestation servers to validate it. Assuming the IMA measurements list is +properly saved, storing it outside the kernel does not introduce security +issues, since its integrity is anyway protected by the TPM. + +Hence, the new IMA staging mechanism is introduced to export IMA +measurements to user space and delete them from kernel space. + +Staging consists in atomically moving the current measurements list to a +temporary list, so that measurements can be deleted afterwards. The staging +operation locks the hot path (racing with addition of new measurements) for +a very short time, only for swapping the list pointers. Deletion of the +measurements instead is done locklessly, away from the hot path. + +There are two flavors of the staging mechanism. In the staging with prompt, +all current measurements are staged, read and deleted upon confirmation. In +the staging and deleting flavor, N measurements are staged from the +beginning of the current measurements list and immediately deleted without +confirmation. + + +Management of Staged Measurements +================================= + +Since with the staging mechanism measurement records are removed from the +kernel, the staged measurements need to be saved in a storage and +concatenated together, so that they can be presented during remote +attestation as if staging was never done. This task can be accomplished by +a remote attestation agent modified to support staging, or a system +service. + +Coordination is necessary in the case where there are multiple actors +requesting measurements to be staged. + +In the staging with prompt case, the measurement interfaces can be accessed +only by one actor (writer) at a time, so the others will get an error until +the former closes it. Since the actors don't care about N, when they gain +access to the interface, they will get all the staged measurements at the +time of their request. + +In the case of staging and deleting, coordination is more important, since +there is the risk that two actors unaware of each other compute the value N +on the current measurements list and request IMA to stage N twice. + + +Remote Attestation Agent Workflow +================================= + +Remote attestation agents can be configured to always present all the +measurements to the remote verifiers or, alternatively, to only provide the +measurements that have not been verified yet by the remote verifiers. + +In the latter case, determining which measurements need to be sent and +verified must solely depend on the remote verifier. The remote attestation +agent can proactively send partial measurements, at the condition that they +are the ones that the remote verifier needs. + +An agent can rely on one of the supported staging methods to proactively +send to a remote verifier the measurements since the previous request up +to the ones that verify the TPM quote obtained in the current request. +The workflow with each staging method is the following. + +With staging with prompt, the agent stages the current measurements list, +reads and stores the measurements in a storage and immediately requests +IMA to delete the staged measurements from kernel memory. Afterwards, it +calculates N by replaying the PCR extend on the stored measurements until +the calculated PCRs match the quoted PCRs. It then keeps the measurements +in excess for the next attestation request. + +At the next attestation request, the agent performs the same steps above, +and concatenates the new measurements to the ones in excess from the +previous request. Also in this case, the agent replays the PCR extend until +it matches the currently quoted PCRs, keeps the measurements in excess and +presents the new N measurement records to the remote attestation server. + +With the staging and deleting method, the agent reads the current +measurements list, calculates N and requests IMA to delete only those. The +measurements in excess are kept in the IMA measurements list and can be +retrieved at the next remote attestation request. + +While keeping only the excess measurements in the storage could be +sufficient to serve the requests of a remote verifier, it is advised to +keep all the obtained measurements locally, as they might be needed for the +attestation with a different remote verifier. + + +Usage +===== + +The IMA staging mechanism can be enabled from the kernel configuration with +the CONFIG_IMA_STAGING option. This option prevents inadvertently removing +the IMA measurement list on systems which do not properly save it. + +If the option is enabled, IMA duplicates the current securityfs +measurements interfaces (both binary and ASCII), by adding the ``_staged`` +file suffix. Both the original and the staging interfaces gain the write +permission for the root user and group, but require the process to have +CAP_SYS_ADMIN set. + +The staging mechanism supports two flavors. + + +Staging with prompt +~~~~~~~~~~~~~~~~~~~ + +The current measurements list is moved to a temporary staging area, +allowing it to be saved to external storage, before being deleted upon +confirmation. + +This staging process is achieved with the following steps. + + 1. ``echo A > <_staged interface>``: the user requests IMA to stage the + entire measurements list; + 2. ``cat <_staged interface>``: the user reads the staged measurements; + 3. ``echo D > <_staged interface>``: the user requests IMA to delete + staged measurements. + + +Staging and deleting +~~~~~~~~~~~~~~~~~~~~ + +N measurements are staged to a temporary staging area, and immediately +deleted without further confirmation. + +This staging process is achieved with the following steps. + + 1. ``cat <original interface>``: the user reads the current measurements + list and determines what the value N for staging should be; + 2. ``echo N > <original interface>``: the user requests IMA to delete N + measurements from the current measurements list. + + +Interface Access +================ + +In order to avoid the IMA measurements list being suddenly truncated by the +staging mechanism during a read, or having multiple concurrent staging, a +semaphore-like locking scheme has been implemented on all the measurements +list interfaces. + +Multiple readers can access concurrently the original and staged +interfaces, and they can be in mutual exclusion with one writer. In order +to see the same state across all the measurement interfaces, the same +writer is allowed to open multiple interfaces for write or read/write. + +If an illegal access occurs, the open to the measurements list interface is +denied. + + +Kexec +===== + +In the event a kexec() system call occurs between staging and deleting, the +staged measurement records are marshalled before the current measurements +list, so that they are both available when the secondary kernel starts. + +If measurement is suspended before requesting to delete staged or current +measurements, IMA returns an error to user space to let it know that +marshalling is already in progress, so that it does not save the +measurements twice. + +IMA also disallows staging when suspending measurement, to avoid the +situation where neither measurements are carried over to the secondary +kernel, nor they are saved by user space to the storage. + + +Hash table +========== + +By default, the template digest of staged measurement records are kept in +kernel memory (only template data are freed), to be able to detect +duplicate records independently of staging. + +The new kernel option ``ima_flush_htable`` has been introduced to +explicitly request a complete deletion of the staged measurements, for +maximum kernel memory saving. If the option has been specified, duplicate +records are still avoided on records of the current measurements list, +but there can be duplicates between different groups of staged +measurements. + +Flushing the hash table is supported only for the staging with prompt +flavor. For the staging and deleting flavor, it would have been necessary +to lock the hot path adding new measurements for the time needed to remove +each selected measurement individually. diff --git a/Documentation/security/credentials.rst b/Documentation/security/credentials.rst index 2aa0791bcefe..4996838491b1 100644 --- a/Documentation/security/credentials.rst +++ b/Documentation/security/credentials.rst @@ -189,9 +189,9 @@ The Linux kernel supports the following types of credentials: be searched for the desired key. Each process may subscribe to a number of keyrings: - Per-thread keying - Per-process keyring - Per-session keyring + - Per-thread keyring + - Per-process keyring + - Per-session keyring When a process accesses a key, if not already present, it will normally be cached on one of these keyrings for future accesses to find. @@ -555,5 +555,5 @@ the VFS, and that can be done by calling into such as ``vfs_mkdir()`` with a different set of credentials. This is done in the following places: * ``sys_faccessat()``. - * ``do_coredump()``. + * ``vfs_coredump()``. * nfs4recover.c. diff --git a/Documentation/security/index.rst b/Documentation/security/index.rst index 3e0a7114a862..00650dcf38cb 100644 --- a/Documentation/security/index.rst +++ b/Documentation/security/index.rst @@ -8,6 +8,7 @@ Security Documentation credentials snp-tdx-threat-model IMA-templates + IMA-export-delete keys/index lsm lsm-development diff --git a/Documentation/security/ipe.rst b/Documentation/security/ipe.rst index 4a7d953abcdc..5eb3e6265fbd 100644 --- a/Documentation/security/ipe.rst +++ b/Documentation/security/ipe.rst @@ -18,7 +18,7 @@ strong integrity guarantees over both the executable code, and specific *data files* on the system, that were critical to its function. These specific data files would not be readable unless they passed integrity policy. A mandatory access control system would be present, and -as a result, xattrs would have to be protected. This lead to a selection +as a result, xattrs would have to be protected. This led to a selection of what would provide the integrity claims. At the time, there were two main mechanisms considered that could guarantee integrity for the system with these requirements: @@ -195,7 +195,7 @@ of the policy to apply the minute usermode starts. Generally, that storage can be handled in one of three ways: 1. The policy file(s) live on disk and the kernel loads the policy prior - to an code path that would result in an enforcement decision. + to a code path that would result in an enforcement decision. 2. The policy file(s) are passed by the bootloader to the kernel, who parses the policy. 3. There is a policy file that is compiled into the kernel that is @@ -235,8 +235,8 @@ Updatable, Rebootless Policy ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ As requirements change over time (vulnerabilities are found in previously -trusted applications, keys roll, etcetera). Updating a kernel to change the -meet those security goals is not always a suitable option, as updates are not +trusted applications, keys roll, etcetera), updating a kernel to meet +those security goals is not always a suitable option, as updates are not always risk-free, and blocking a security update leaves systems vulnerable. This means IPE requires a policy that can be completely updated (allowing revocations of existing policy) from a source external to the kernel (allowing @@ -370,7 +370,7 @@ Simplified Policy: Finally, IPE's policy is designed for sysadmins, not kernel developers. Instead of covering individual LSM hooks (or syscalls), IPE covers operations. This means instead of sysadmins needing to know that the syscalls ``mmap``, ``mprotect``, -``execve``, and ``uselib`` must have rules protecting them, they must simple know +``execve``, and ``uselib`` must have rules protecting them, they must simply know that they want to restrict code execution. This limits the amount of bypasses that could occur due to a lack of knowledge of the underlying system; whereas the maintainers of IPE, being kernel developers can make the correct choice to determine diff --git a/Documentation/security/keys/trusted-encrypted.rst b/Documentation/security/keys/trusted-encrypted.rst index f4d7e162d5e4..ddff7c7c2582 100644 --- a/Documentation/security/keys/trusted-encrypted.rst +++ b/Documentation/security/keys/trusted-encrypted.rst @@ -10,6 +10,37 @@ of a Trust Source for greater security, while Encrypted Keys can be used on any system. All user level blobs, are displayed and loaded in hex ASCII for convenience, and are integrity verified. +Trusted Keys as Protected key +============================= +It is the secure way of keeping the keys in the kernel key-ring as Trusted-Key, +such that: + +- Key-blob, an encrypted key-data, created to be stored, loaded and seen by + userspace. +- Key-data, the plain-key text in the system memory, to be used by + kernel space only. + +Though key-data is not accessible to the user-space in plain-text, but it is in +plain-text in system memory, when used in kernel space. Even though kernel-space +attracts small surface attack, but with compromised kernel or side-channel +attack accessing the system memory can lead to a chance of the key getting +compromised/leaked. + +In order to protect the key in kernel space, the concept of "protected-keys" is +introduced which will act as an added layer of protection. The key-data of the +protected keys is encrypted with Key-Encryption-Key(KEK), and decrypted inside +the trust source boundary. The plain-key text never available out-side in the +system memory. Thus, any crypto operation that is to be executed using the +protected key, can only be done by the trust source, which generated the +key blob. + +Hence, if the protected-key is leaked or compromised, it is of no use to the +hacker. + +Trusted keys as protected keys, with trust source having the capability of +generating: + +- Key-Blob, to be loaded, stored and seen by user-space. Trust Source ============ @@ -50,6 +81,14 @@ safe. and the UNIQUE key. Default is to use the UNIQUE key, but selecting the OTP key can be done via a module parameter (dcp_use_otp_key). + (5) PKWM (PowerVM Key Wrapping Module: IBM PowerVM + Platform KeyStore) + + Rooted to a unique, per-LPAR key, which is derived from a system-wide, + randomly generated LPAR root key. Both the per-LPAR keys and the LPAR + root key are stored in hypervisor-owned secure memory at runtime, + and the LPAR root key is additionally persisted in secure locations + such as the processor SEEPROMs and encrypted NVRAM. + * Execution isolation (1) TPM @@ -71,6 +110,14 @@ safe. environment. Only basic blob key encryption is executed there. The actual key sealing/unsealing is done on main processor/kernel space. + (5) PKWM (PowerVM Key Wrapping Module: IBM PowerVM + Platform KeyStore) + + Fixed set of cryptographic operations done on on-chip hardware + cryptographic acceleration unit NX. Keys for wrapping and unwrapping + are managed by PowerVM Platform KeyStore, which stores keys in an + isolated in-memory copy in secure hypervisor memory, as well as in a + persistent copy in hypervisor-encrypted NVRAM. + * Optional binding to platform integrity state (1) TPM @@ -98,6 +145,11 @@ safe. Relies on Secure/Trusted boot process (called HAB by vendor) for platform integrity. + (5) PKWM (PowerVM Key Wrapping Module: IBM PowerVM + Platform KeyStore) + + Relies on secure and trusted boot process of IBM Power systems for + platform integrity. + * Interfaces and APIs (1) TPM @@ -118,6 +170,11 @@ safe. Vendor-specific API that is implemented as part of the DCP crypto driver in ``drivers/crypto/mxs-dcp.c``. + (5) PKWM (PowerVM Key Wrapping Module: IBM PowerVM + Platform KeyStore) + + Platform Keystore has well documented interfaces in PAPR document. + Refer to ``Documentation/arch/powerpc/papr_hcalls.rst`` + * Threat model The strength and appropriateness of a particular trust source for a given @@ -160,6 +217,10 @@ selected trust source: a dedicated hardware RNG that is independent from DCP which can be enabled to back the kernel RNG. + * PKWM (PowerVM Key Wrapping Module: IBM PowerVM + Platform KeyStore) + + The normal kernel random number generator is used to generate keys. + Users may override this by specifying ``trusted.rng=kernel`` on the kernel command-line to override the used RNG with the kernel's random number pool. @@ -252,7 +313,7 @@ in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits). Trusted Keys usage: CAAM ------------------------ -Usage:: +Trusted Keys Usage:: keyctl add trusted name "new keylen" ring keyctl add trusted name "load hex_blob" ring @@ -262,6 +323,21 @@ Usage:: CAAM-specific format. The key length for new keys is always in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits). +Trusted Keys as Protected Keys Usage:: + + keyctl add trusted name "new keylen pk [options]" ring + keyctl add trusted name "load hex_blob [options]" ring + keyctl print keyid + + where, 'pk' is used to direct trust source to generate protected key. + + options: + key_enc_algo = For CAAM, supported enc algo are ECB(2), CCM(1). + +"keyctl print" returns an ASCII hex copy of the sealed key, which is in a +CAAM-specific format. The key length for new keys is always in bytes. +Trusted Keys can be 32 - 128 bytes (256 - 1024 bits). + Trusted Keys usage: DCP ----------------------- @@ -275,6 +351,26 @@ Usage:: specific to this DCP key-blob implementation. The key length for new keys is always in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits). +Trusted Keys usage: PKWM +------------------------ + +Usage:: + + keyctl add trusted name "new keylen [options]" ring + keyctl add trusted name "load hex_blob" ring + keyctl print keyid + + options: + wrap_flags= ascii hex value of security policy requirement + 0x00: no secure boot requirement (default) + 0x01: require secure boot to be in either audit or + enforced mode + 0x02: require secure boot to be in enforced mode + +"keyctl print" returns an ASCII hex copy of the sealed key, which is in format +specific to PKWM key-blob implementation. The key length for new keys is +always in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits). + Encrypted Keys usage -------------------- @@ -343,6 +439,46 @@ Load a trusted key from the saved blob:: f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b e4a8aea2b607ec96931e6f4d4fe563ba +Create and save a trusted key as protected key named "kmk" of length 32 bytes. + +:: + + $ keyctl add trusted kmk "new 32 pk key_enc_algo=1" @u + 440502848 + + $ keyctl show + Session Keyring + -3 --alswrv 500 500 keyring: _ses + 97833714 --alswrv 500 -1 \_ keyring: _uid.500 + 440502848 --alswrv 500 500 \_ trusted: kmk + + $ keyctl print 440502848 + 0101000000000000000001005d01b7e3f4a6be5709930f3b70a743cbb42e0cc95e18e915 + 3f60da455bbf1144ad12e4f92b452f966929f6105fd29ca28e4d4d5a031d068478bacb0b + 27351119f822911b0a11ba3d3498ba6a32e50dac7f32894dd890eb9ad578e4e292c83722 + a52e56a097e6a68b3f56f7a52ece0cdccba1eb62cad7d817f6dc58898b3ac15f36026fec + d568bd4a706cb60bb37be6d8f1240661199d640b66fb0fe3b079f97f450b9ef9c22c6d5d + dd379f0facd1cd020281dfa3c70ba21a3fa6fc2471dc6d13ecf8298b946f65345faa5ef0 + f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b + e4a8aea2b607ec96931e6f4d4fe563ba + + $ keyctl pipe 440502848 > kmk.blob + +Load a trusted key from the saved blob:: + + $ keyctl add trusted kmk "load `cat kmk.blob` key_enc_algo=1" @u + 268728824 + + $ keyctl print 268728824 + 0101000000000000000001005d01b7e3f4a6be5709930f3b70a743cbb42e0cc95e18e915 + 3f60da455bbf1144ad12e4f92b452f966929f6105fd29ca28e4d4d5a031d068478bacb0b + 27351119f822911b0a11ba3d3498ba6a32e50dac7f32894dd890eb9ad578e4e292c83722 + a52e56a097e6a68b3f56f7a52ece0cdccba1eb62cad7d817f6dc58898b3ac15f36026fec + d568bd4a706cb60bb37be6d8f1240661199d640b66fb0fe3b079f97f450b9ef9c22c6d5d + dd379f0facd1cd020281dfa3c70ba21a3fa6fc2471dc6d13ecf8298b946f65345faa5ef0 + f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b + e4a8aea2b607ec96931e6f4d4fe563ba + Reseal (TPM specific) a trusted key under new PCR values:: $ keyctl update 268728824 "update pcrinfo=`cat pcr.blob`" diff --git a/Documentation/security/landlock.rst b/Documentation/security/landlock.rst index e0fc54aff09e..c5186526e76f 100644 --- a/Documentation/security/landlock.rst +++ b/Documentation/security/landlock.rst @@ -7,7 +7,7 @@ Landlock LSM: kernel documentation ================================== :Author: Mickaël Salaün -:Date: March 2025 +:Date: March 2026 Landlock's goal is to create scoped access-control (i.e. sandboxing). To harden a whole system, this feature should be available to any process, @@ -89,6 +89,46 @@ this is required to keep access controls consistent over the whole system, and this avoids unattended bypasses through file descriptor passing (i.e. confused deputy attack). +.. _scoped-flags-interaction: + +Interaction between scoped flags and other access rights +-------------------------------------------------------- + +The ``scoped`` flags in &struct landlock_ruleset_attr restrict the +use of *outgoing* IPC from the created Landlock domain, while they +permit reaching out to IPC endpoints *within* the created Landlock +domain. + +In the future, scoped flags *may* interact with other access rights, +e.g. so that abstract UNIX sockets can be allow-listed by name, or so +that signals can be allow-listed by signal number or target process. + +When introducing ``LANDLOCK_ACCESS_FS_RESOLVE_UNIX``, we defined it to +implicitly have the same scoping semantics as a +``LANDLOCK_SCOPE_PATHNAME_UNIX_SOCKET`` flag would have: connecting to +UNIX sockets within the same domain (where +``LANDLOCK_ACCESS_FS_RESOLVE_UNIX`` is used) is unconditionally +allowed. + +The reasoning is: + +* Like other IPC mechanisms, connecting to named UNIX sockets in the + same domain should be expected and harmless. (If needed, users can + further refine their Landlock policies with nested domains or by + restricting ``LANDLOCK_ACCESS_FS_MAKE_SOCK``.) +* We reserve the option to still introduce + ``LANDLOCK_SCOPE_PATHNAME_UNIX_SOCKET`` in the future. (This would + be useful if we wanted to have a Landlock rule to permit IPC access + to other Landlock domains.) +* But we can postpone the point in time when users have to deal with + two interacting flags visible in the userspace API. (In particular, + it is possible that it won't be needed in practice, in which case we + can avoid the second flag altogether.) +* If we *do* introduce ``LANDLOCK_SCOPE_PATHNAME_UNIX_SOCKET`` in the + future, setting this scoped flag in a ruleset does *not reduce* the + restrictions, because access within the same scope is already + allowed based on ``LANDLOCK_ACCESS_FS_RESOLVE_UNIX``. + Tests ===== @@ -110,6 +150,12 @@ Filesystem .. kernel-doc:: security/landlock/fs.h :identifiers: +Process credential +------------------ + +.. kernel-doc:: security/landlock/cred.h + :identifiers: + Ruleset and domain ------------------ @@ -128,6 +174,9 @@ makes the reasoning much easier and helps avoid pitfalls. .. kernel-doc:: security/landlock/ruleset.h :identifiers: +.. kernel-doc:: security/landlock/domain.h + :identifiers: + Additional documentation ======================== diff --git a/Documentation/security/self-protection.rst b/Documentation/security/self-protection.rst index 910668e665cb..a32ca23c21b0 100644 --- a/Documentation/security/self-protection.rst +++ b/Documentation/security/self-protection.rst @@ -303,7 +303,7 @@ Memory poisoning When releasing memory, it is best to poison the contents, to avoid reuse attacks that rely on the old contents of memory. E.g., clear stack on a -syscall return (``CONFIG_GCC_PLUGIN_STACKLEAK``), wipe heap memory on a +syscall return (``CONFIG_KSTACK_ERASE``), wipe heap memory on a free. This frustrates many uninitialized variable attacks, stack content exposures, heap content exposures, and use-after-free attacks. |