diff options
Diffstat (limited to 'Documentation/security')
21 files changed, 1692 insertions, 115 deletions
diff --git a/Documentation/security/IMA-templates.rst b/Documentation/security/IMA-templates.rst index c5a8432972ef..15b4add314fc 100644 --- a/Documentation/security/IMA-templates.rst +++ b/Documentation/security/IMA-templates.rst @@ -66,22 +66,35 @@ descriptors by adding their identifier to the format string calculated with the SHA1 or MD5 hash algorithm; - 'n': the name of the event (i.e. the file name), with size up to 255 bytes; - 'd-ng': the digest of the event, calculated with an arbitrary hash - algorithm (field format: [<hash algo>:]digest, where the digest - prefix is shown only if the hash algorithm is not SHA1 or MD5); + algorithm (field format: <hash algo>:digest); + - 'd-ngv2': same as d-ng, but prefixed with the "ima" or "verity" digest type + (field format: <digest type>:<hash algo>:digest); - 'd-modsig': the digest of the event without the appended modsig; - 'n-ng': the name of the event, without size limitations; - - 'sig': the file signature; + - 'sig': the file signature, based on either the file's/fsverity's digest[1], + or the EVM portable signature, if 'security.ima' contains a file hash. - 'modsig' the appended file signature; - 'buf': the buffer data that was used to generate the hash without size limitations; + - 'evmsig': the EVM portable signature; + - 'iuid': the inode UID; + - 'igid': the inode GID; + - 'imode': the inode mode; + - 'xattrnames': a list of xattr names (separated by ``|``), only if the xattr is + present; + - 'xattrlengths': a list of xattr lengths (u32), only if the xattr is present; + - 'xattrvalues': a list of xattr values; Below, there is the list of defined template descriptors: - "ima": its format is ``d|n``; - "ima-ng" (default): its format is ``d-ng|n-ng``; + - "ima-ngv2": its format is ``d-ngv2|n-ng``; - "ima-sig": its format is ``d-ng|n-ng|sig``; + - "ima-sigv2": its format is ``d-ngv2|n-ng|sig``; - "ima-buf": its format is ``d-ng|n-ng|buf``; - "ima-modsig": its format is ``d-ng|n-ng|sig|d-modsig|modsig``; + - "evm-sig": its format is ``d-ng|n-ng|evmsig|xattrnames|xattrlengths|xattrvalues|iuid|igid|imode``; Use diff --git a/Documentation/security/SCTP.rst b/Documentation/security/SCTP.rst index 0bcf6c1245ee..6d80d464ab6e 100644 --- a/Documentation/security/SCTP.rst +++ b/Documentation/security/SCTP.rst @@ -15,10 +15,7 @@ For security module support, three SCTP specific hooks have been implemented:: security_sctp_assoc_request() security_sctp_bind_connect() security_sctp_sk_clone() - -Also the following security hook has been utilised:: - - security_inet_conn_established() + security_sctp_assoc_established() The usage of these hooks are described below with the SELinux implementation described in the `SCTP SELinux Support`_ chapter. @@ -26,11 +23,11 @@ described in the `SCTP SELinux Support`_ chapter. security_sctp_assoc_request() ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Passes the ``@ep`` and ``@chunk->skb`` of the association INIT packet to the +Passes the ``@asoc`` and ``@chunk->skb`` of the association INIT packet to the security module. Returns 0 on success, error on failure. :: - @ep - pointer to sctp endpoint structure. + @asoc - pointer to sctp association structure. @skb - pointer to skbuff of association packet. @@ -84,7 +81,7 @@ A summary of the ``@optname`` entries is as follows:: destination addresses. SCTP_SENDMSG_CONNECT - Initiate a connection that is generated by a - sendmsg(2) or sctp_sendmsg(3) on a new asociation. + sendmsg(2) or sctp_sendmsg(3) on a new association. SCTP_PRIMARY_ADDR - Set local primary address. @@ -117,16 +114,17 @@ Called whenever a new socket is created by **accept**\(2) calls **sctp_peeloff**\(3). :: - @ep - pointer to current sctp endpoint structure. + @asoc - pointer to current sctp association structure. @sk - pointer to current sock structure. - @sk - pointer to new sock structure. + @newsk - pointer to new sock structure. -security_inet_conn_established() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Called when a COOKIE ACK is received:: +security_sctp_assoc_established() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Called when a COOKIE ACK is received, and the peer secid will be +saved into ``@asoc->peer_secid`` for client:: - @sk - pointer to sock structure. + @asoc - pointer to sctp association structure. @skb - pointer to skbuff of the COOKIE ACK packet. @@ -134,7 +132,7 @@ Security Hooks used for Association Establishment ------------------------------------------------- The following diagram shows the use of ``security_sctp_bind_connect()``, -``security_sctp_assoc_request()``, ``security_inet_conn_established()`` when +``security_sctp_assoc_request()``, ``security_sctp_assoc_established()`` when establishing an association. :: @@ -151,9 +149,9 @@ establishing an association. INIT ---------------------------------------------> sctp_sf_do_5_1B_init() Respond to an INIT chunk. - SCTP peer endpoint "A" is - asking for an association. Call - security_sctp_assoc_request() + SCTP peer endpoint "A" is asking + for a temporary association. + Call security_sctp_assoc_request() to set the peer label if first association. If not first association, check @@ -163,13 +161,16 @@ establishing an association. | discard the packet. | COOKIE ECHO ------------------------------------------> - | - | - | + sctp_sf_do_5_1D_ce() + Respond to an COOKIE ECHO chunk. + Confirm the cookie and create a + permanent association. + Call security_sctp_assoc_request() to + do the same as for INIT chunk Response. <------------------------------------------- COOKIE ACK | | sctp_sf_do_5_1E_ca | - Call security_inet_conn_established() | + Call security_sctp_assoc_established() | to set the peer label. | | | | If SCTP_SOCKET_TCP or peeled off @@ -195,27 +196,27 @@ hooks with the SELinux specifics expanded below:: security_sctp_assoc_request() security_sctp_bind_connect() security_sctp_sk_clone() - security_inet_conn_established() + security_sctp_assoc_established() security_sctp_assoc_request() ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Passes the ``@ep`` and ``@chunk->skb`` of the association INIT packet to the +Passes the ``@asoc`` and ``@chunk->skb`` of the association INIT packet to the security module. Returns 0 on success, error on failure. :: - @ep - pointer to sctp endpoint structure. + @asoc - pointer to sctp association structure. @skb - pointer to skbuff of association packet. The security module performs the following operations: - IF this is the first association on ``@ep->base.sk``, then set the peer + IF this is the first association on ``@asoc->base.sk``, then set the peer sid to that in ``@skb``. This will ensure there is only one peer sid - assigned to ``@ep->base.sk`` that may support multiple associations. + assigned to ``@asoc->base.sk`` that may support multiple associations. - ELSE validate the ``@ep->base.sk peer_sid`` against the ``@skb peer sid`` + ELSE validate the ``@asoc->base.sk peer_sid`` against the ``@skb peer sid`` to determine whether the association should be allowed or denied. - Set the sctp ``@ep sid`` to socket's sid (from ``ep->base.sk``) with + Set the sctp ``@asoc sid`` to socket's sid (from ``asoc->base.sk``) with MLS portion taken from ``@skb peer sid``. This will be used by SCTP TCP style sockets and peeled off connections as they cause a new socket to be generated. @@ -259,21 +260,21 @@ security_sctp_sk_clone() Called whenever a new socket is created by **accept**\(2) (i.e. a TCP style socket) or when a socket is 'peeled off' e.g userspace calls **sctp_peeloff**\(3). ``security_sctp_sk_clone()`` will set the new -sockets sid and peer sid to that contained in the ``@ep sid`` and -``@ep peer sid`` respectively. +sockets sid and peer sid to that contained in the ``@asoc sid`` and +``@asoc peer sid`` respectively. :: - @ep - pointer to current sctp endpoint structure. + @asoc - pointer to current sctp association structure. @sk - pointer to current sock structure. - @sk - pointer to new sock structure. + @newsk - pointer to new sock structure. -security_inet_conn_established() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +security_sctp_assoc_established() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Called when a COOKIE ACK is received where it sets the connection's peer sid to that in ``@skb``:: - @sk - pointer to sock structure. + @asoc - pointer to sctp association structure. @skb - pointer to skbuff of the COOKIE ACK packet. diff --git a/Documentation/security/credentials.rst b/Documentation/security/credentials.rst index 282e79feee6a..2aa0791bcefe 100644 --- a/Documentation/security/credentials.rst +++ b/Documentation/security/credentials.rst @@ -323,7 +323,6 @@ credentials (the value is simply returned in each case):: uid_t current_fsuid(void) Current's file access UID gid_t current_fsgid(void) Current's file access GID kernel_cap_t current_cap(void) Current's effective capabilities - void *current_security(void) Current's LSM security pointer struct user_struct *current_user(void) Current's user account There are also convenience wrappers for retrieving specific associated pairs of @@ -453,9 +452,9 @@ still at this point. When replacing the group list, the new list must be sorted before it is added to the credential, as a binary search is used to test for -membership. In practice, this means :c:func:`groups_sort` should be -called before :c:func:`set_groups` or :c:func:`set_current_groups`. -:c:func:`groups_sort)` must not be called on a ``struct group_list`` which +membership. In practice, this means groups_sort() should be +called before set_groups() or set_current_groups(). +groups_sort() must not be called on a ``struct group_list`` which is shared as it may permute elements as part of the sorting process even if the array is already sorted. @@ -528,11 +527,6 @@ There are some functions to help manage credentials: This gets a reference on a live set of credentials, returning a pointer to that set of credentials. - - ``struct cred *get_new_cred(struct cred *cred);`` - - This gets a reference on a set of credentials that is under construction - and is thus still mutable, returning a pointer to that set of credentials. - Open File Credentials ===================== @@ -548,6 +542,10 @@ pointer will not change over the lifetime of the file struct, and nor will the contents of the cred struct pointed to, barring the exceptions listed above (see the Task Credentials section). +To avoid "confused deputy" privilege escalation attacks, access control checks +during subsequent operations on an opened file should use these credentials +instead of "current"'s credentials, as the file may have been passed to a more +privileged process. Overriding the VFS's Use of Credentials ======================================= diff --git a/Documentation/security/digsig.rst b/Documentation/security/digsig.rst index f6a8902d3ef7..de035f282196 100644 --- a/Documentation/security/digsig.rst +++ b/Documentation/security/digsig.rst @@ -82,7 +82,7 @@ The signing and key management utilities evm-utils provide functionality to generate signatures, to load keys into the kernel keyring. Keys can be in PEM or converted to the kernel format. When the key is added to the kernel keyring, the keyid defines the name -of the key: 5D2B05FC633EE3E8 in the example bellow. +of the key: 5D2B05FC633EE3E8 in the example below. Here is example output of the keyctl utility:: diff --git a/Documentation/security/index.rst b/Documentation/security/index.rst index 8129405eb2cc..3e0a7114a862 100644 --- a/Documentation/security/index.rst +++ b/Documentation/security/index.rst @@ -6,6 +6,7 @@ Security Documentation :maxdepth: 1 credentials + snp-tdx-threat-model IMA-templates keys/index lsm @@ -16,3 +17,6 @@ Security Documentation siphash tpm/index digsig + landlock + secrets/index + ipe diff --git a/Documentation/security/ipe.rst b/Documentation/security/ipe.rst new file mode 100644 index 000000000000..4a7d953abcdc --- /dev/null +++ b/Documentation/security/ipe.rst @@ -0,0 +1,446 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Integrity Policy Enforcement (IPE) - Kernel Documentation +========================================================= + +.. NOTE:: + + This is documentation targeted at developers, instead of administrators. + If you're looking for documentation on the usage of IPE, please see + :doc:`IPE admin guide </admin-guide/LSM/ipe>`. + +Historical Motivation +--------------------- + +The original issue that prompted IPE's implementation was the creation +of a locked-down system. This system would be born-secure, and have +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 +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: + + 1. IMA + EVM Signatures + 2. DM-Verity + +Both options were carefully considered, however the choice to use DM-Verity +over IMA+EVM as the *integrity mechanism* in the original use case of IPE +was due to three main reasons: + + 1. Protection of additional attack vectors: + + * With IMA+EVM, without an encryption solution, the system is vulnerable + to offline attack against the aforementioned specific data files. + + Unlike executables, read operations (like those on the protected data + files), cannot be enforced to be globally integrity verified. This means + there must be some form of selector to determine whether a read should + enforce the integrity policy, or it should not. + + At the time, this was done with mandatory access control labels. An IMA + policy would indicate what labels required integrity verification, which + presented an issue: EVM would protect the label, but if an attacker could + modify filesystem offline, the attacker could wipe all the xattrs - + including the SELinux labels that would be used to determine whether the + file should be subject to integrity policy. + + With DM-Verity, as the xattrs are saved as part of the Merkel tree, if + offline mount occurs against the filesystem protected by dm-verity, the + checksum no longer matches and the file fails to be read. + + * As userspace binaries are paged in Linux, dm-verity also offers the + additional protection against a hostile block device. In such an attack, + the block device reports the appropriate content for the IMA hash + initially, passing the required integrity check. Then, on the page fault + that accesses the real data, will report the attacker's payload. Since + dm-verity will check the data when the page fault occurs (and the disk + access), this attack is mitigated. + + 2. Performance: + + * dm-verity provides integrity verification on demand as blocks are + read versus requiring the entire file being read into memory for + validation. + + 3. Simplicity of signing: + + * No need for two signatures (IMA, then EVM): one signature covers + an entire block device. + * Signatures can be stored externally to the filesystem metadata. + * The signature supports an x.509-based signing infrastructure. + +The next step was to choose a *policy* to enforce the integrity mechanism. +The minimum requirements for the policy were: + + 1. The policy itself must be integrity verified (preventing trivial + attack against it). + 2. The policy itself must be resistant to rollback attacks. + 3. The policy enforcement must have a permissive-like mode. + 4. The policy must be able to be updated, in its entirety, without + a reboot. + 5. Policy updates must be atomic. + 6. The policy must support *revocations* of previously authored + components. + 7. The policy must be auditable, at any point-of-time. + +IMA, as the only integrity policy mechanism at the time, was +considered against these list of requirements, and did not fulfill +all of the minimum requirements. Extending IMA to cover these +requirements was considered, but ultimately discarded for a +two reasons: + + 1. Regression risk; many of these changes would result in + dramatic code changes to IMA, which is already present in the + kernel, and therefore might impact users. + + 2. IMA was used in the system for measurement and attestation; + separation of measurement policy from local integrity policy + enforcement was considered favorable. + +Due to these reasons, it was decided that a new LSM should be created, +whose responsibility would be only the local integrity policy enforcement. + +Role and Scope +-------------- + +IPE, as its name implies, is fundamentally an integrity policy enforcement +solution; IPE does not mandate how integrity is provided, but instead +leaves that decision to the system administrator to set the security bar, +via the mechanisms that they select that suit their individual needs. +There are several different integrity solutions that provide a different +level of security guarantees; and IPE allows sysadmins to express policy for +theoretically all of them. + +IPE does not have an inherent mechanism to ensure integrity on its own. +Instead, there are more effective layers available for building systems that +can guarantee integrity. It's important to note that the mechanism for proving +integrity is independent of the policy for enforcing that integrity claim. + +Therefore, IPE was designed around: + + 1. Easy integrations with integrity providers. + 2. Ease of use for platform administrators/sysadmins. + +Design Rationale: +----------------- + +IPE was designed after evaluating existing integrity policy solutions +in other operating systems and environments. In this survey of other +implementations, there were a few pitfalls identified: + + 1. Policies were not readable by humans, usually requiring a binary + intermediary format. + 2. A single, non-customizable action was implicitly taken as a default. + 3. Debugging the policy required manual steps to determine what rule was violated. + 4. Authoring a policy required an in-depth knowledge of the larger system, + or operating system. + +IPE attempts to avoid all of these pitfalls. + +Policy +~~~~~~ + +Plain Text +^^^^^^^^^^ + +IPE's policy is plain-text. This introduces slightly larger policy files than +other LSMs, but solves two major problems that occurs with some integrity policy +solutions on other platforms. + +The first issue is one of code maintenance and duplication. To author policies, +the policy has to be some form of string representation (be it structured, +through XML, JSON, YAML, etcetera), to allow the policy author to understand +what is being written. In a hypothetical binary policy design, a serializer +is necessary to write the policy from the human readable form, to the binary +form, and a deserializer is needed to interpret the binary form into a data +structure in the kernel. + +Eventually, another deserializer will be needed to transform the binary from +back into the human-readable form with as much information preserved. This is because a +user of this access control system will have to keep a lookup table of a checksum +and the original file itself to try to understand what policies have been deployed +on this system and what policies have not. For a single user, this may be alright, +as old policies can be discarded almost immediately after the update takes hold. +For users that manage computer fleets in the thousands, if not hundreds of thousands, +with multiple different operating systems, and multiple different operational needs, +this quickly becomes an issue, as stale policies from years ago may be present, +quickly resulting in the need to recover the policy or fund extensive infrastructure +to track what each policy contains. + +With now three separate serializer/deserializers, maintenance becomes costly. If the +policy avoids the binary format, there is only one required serializer: from the +human-readable form to the data structure in kernel, saving on code maintenance, +and retaining operability. + +The second issue with a binary format is one of transparency. As IPE controls +access based on the trust of the system's resources, it's policy must also be +trusted to be changed. This is done through signatures, resulting in needing +signing as a process. Signing, as a process, is typically done with a +high security bar, as anything signed can be used to attack integrity +enforcement systems. It is also important that, when signing something, that +the signer is aware of what they are signing. A binary policy can cause +obfuscation of that fact; what signers see is an opaque binary blob. A +plain-text policy, on the other hand, the signers see the actual policy +submitted for signing. + +Boot Policy +~~~~~~~~~~~ + +IPE, if configured appropriately, is able to enforce a policy as soon as a +kernel is booted and usermode starts. That implies some level of storage +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. + 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 + parsed and enforced on initialization. + +The first option has problems: the kernel reading files from userspace +is typically discouraged and very uncommon in the kernel. + +The second option also has problems: Linux supports a variety of bootloaders +across its entire ecosystem - every bootloader would have to support this +new methodology or there must be an independent source. It would likely +result in more drastic changes to the kernel startup than necessary. + +The third option is the best but it's important to be aware that the policy +will take disk space against the kernel it's compiled in. It's important to +keep this policy generalized enough that userspace can load a new, more +complicated policy, but restrictive enough that it will not overauthorize +and cause security issues. + +The initramfs provides a way that this bootup path can be established. The +kernel starts with a minimal policy, that trusts the initramfs only. Inside +the initramfs, when the real rootfs is mounted, but not yet transferred to, +it deploys and activates a policy that trusts the new root filesystem. +This prevents overauthorization at any step, and keeps the kernel policy +to a minimal size. + +Startup +^^^^^^^ + +Not every system, however starts with an initramfs, so the startup policy +compiled into the kernel will need some flexibility to express how trust +is established for the next phase of the bootup. To this end, if we just +make the compiled-in policy a full IPE policy, it allows system builders +to express the first stage bootup requirements appropriately. + +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 +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 +policies to be updated without updating the kernel). + +Additionally, since the kernel is stateless between invocations, and reading +policy files off the disk from kernel space is a bad idea(tm), then the +policy updates have to be done rebootlessly. + +To allow an update from an external source, it could be potentially malicious, +so this policy needs to have a way to be identified as trusted. This is +done via a signature chained to a trust source in the kernel. Arbitrarily, +this is the ``SYSTEM_TRUSTED_KEYRING``, a keyring that is initially +populated at kernel compile-time, as this matches the expectation that the +author of the compiled-in policy described above is the same entity that can +deploy policy updates. + +Anti-Rollback / Anti-Replay +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Over time, vulnerabilities are found and trusted resources may not be +trusted anymore. IPE's policy has no exception to this. There can be +instances where a mistaken policy author deploys an insecure policy, +before correcting it with a secure policy. + +Assuming that as soon as the insecure policy is signed, and an attacker +acquires the insecure policy, IPE needs a way to prevent rollback +from the secure policy update to the insecure policy update. + +Initially, IPE's policy can have a policy_version that states the +minimum required version across all policies that can be active on +the system. This will prevent rollback while the system is live. + +.. WARNING:: + + However, since the kernel is stateless across boots, this policy + version will be reset to 0.0.0 on the next boot. System builders + need to be aware of this, and ensure the new secure policies are + deployed ASAP after a boot to ensure that the window of + opportunity is minimal for an attacker to deploy the insecure policy. + +Implicit Actions: +~~~~~~~~~~~~~~~~~ + +The issue of implicit actions only becomes visible when you consider +a mixed level of security bars across multiple operations in a system. +For example, consider a system that has strong integrity guarantees +over both the executable code, and specific *data files* on the system, +that were critical to its function. In this system, three types of policies +are possible: + + 1. A policy in which failure to match any rules in the policy results + in the action being denied. + 2. A policy in which failure to match any rules in the policy results + in the action being allowed. + 3. A policy in which the action taken when no rules are matched is + specified by the policy author. + +The first option could make a policy like this:: + + op=EXECUTE integrity_verified=YES action=ALLOW + +In the example system, this works well for the executables, as all +executables should have integrity guarantees, without exception. The +issue becomes with the second requirement about specific data files. +This would result in a policy like this (assuming each line is +evaluated in order):: + + op=EXECUTE integrity_verified=YES action=ALLOW + + op=READ integrity_verified=NO label=critical_t action=DENY + op=READ action=ALLOW + +This is somewhat clear if you read the docs, understand the policy +is executed in order and that the default is a denial; however, the +last line effectively changes that default to an ALLOW. This is +required, because in a realistic system, there are some unverified +reads (imagine appending to a log file). + +The second option, matching no rules results in an allow, is clearer +for the specific data files:: + + op=READ integrity_verified=NO label=critical_t action=DENY + +And, like the first option, falls short with the execution scenario, +effectively needing to override the default:: + + op=EXECUTE integrity_verified=YES action=ALLOW + op=EXECUTE action=DENY + + op=READ integrity_verified=NO label=critical_t action=DENY + +This leaves the third option. Instead of making users be clever +and override the default with an empty rule, force the end-user +to consider what the appropriate default should be for their +scenario and explicitly state it:: + + DEFAULT op=EXECUTE action=DENY + op=EXECUTE integrity_verified=YES action=ALLOW + + DEFAULT op=READ action=ALLOW + op=READ integrity_verified=NO label=critical_t action=DENY + +Policy Debugging: +~~~~~~~~~~~~~~~~~ + +When developing a policy, it is useful to know what line of the policy +is being violated to reduce debugging costs; narrowing the scope of the +investigation to the exact line that resulted in the action. Some integrity +policy systems do not provide this information, instead providing the +information that was used in the evaluation. This then requires a correlation +with the policy to evaluate what went wrong. + +Instead, IPE just emits the rule that was matched. This limits the scope +of the investigation to the exact policy line (in the case of a specific +rule), or the section (in the case of a DEFAULT). This decreases iteration +and investigation times when policy failures are observed while evaluating +policies. + +IPE's policy engine is also designed in a way that it makes it obvious to +a human of how to investigate a policy failure. Each line is evaluated in +the sequence that is written, so the algorithm is very simple to follow +for humans to recreate the steps and could have caused the failure. In other +surveyed systems, optimizations occur (sorting rules, for instance) when loading +the policy. In those systems, it requires multiple steps to debug, and the +algorithm may not always be clear to the end-user without reading the code first. + +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 +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 +whether something maps to these operations, and under what conditions. + +Implementation Notes +-------------------- + +Anonymous Memory +~~~~~~~~~~~~~~~~ + +Anonymous memory isn't treated any differently from any other access in IPE. +When anonymous memory is mapped with ``+X``, it still comes into the ``file_mmap`` +or ``file_mprotect`` hook, but with a ``NULL`` file object. This is submitted to +the evaluation, like any other file. However, all current trust properties will +evaluate to false, as they are all file-based and the operation is not +associated with a file. + +.. WARNING:: + + This also occurs with the ``kernel_load_data`` hook, when the kernel is + loading data from a userspace buffer that is not backed by a file. In this + scenario all current trust properties will also evaluate to false. + +Securityfs Interface +~~~~~~~~~~~~~~~~~~~~ + +The per-policy securityfs tree is somewhat unique. For example, for +a standard securityfs policy tree:: + + MyPolicy + |- active + |- delete + |- name + |- pkcs7 + |- policy + |- update + |- version + +The policy is stored in the ``->i_private`` data of the MyPolicy inode. + +Tests +----- + +IPE has KUnit Tests for the policy parser. Recommended kunitconfig:: + + CONFIG_KUNIT=y + CONFIG_SECURITY=y + CONFIG_SECURITYFS=y + CONFIG_PKCS7_MESSAGE_PARSER=y + CONFIG_SYSTEM_DATA_VERIFICATION=y + CONFIG_FS_VERITY=y + CONFIG_FS_VERITY_BUILTIN_SIGNATURES=y + CONFIG_BLOCK=y + CONFIG_MD=y + CONFIG_BLK_DEV_DM=y + CONFIG_DM_VERITY=y + CONFIG_DM_VERITY_VERIFY_ROOTHASH_SIG=y + CONFIG_NET=y + CONFIG_AUDIT=y + CONFIG_AUDITSYSCALL=y + CONFIG_BLK_DEV_INITRD=y + + CONFIG_SECURITY_IPE=y + CONFIG_IPE_PROP_DM_VERITY=y + CONFIG_IPE_PROP_DM_VERITY_SIGNATURE=y + CONFIG_IPE_PROP_FS_VERITY=y + CONFIG_IPE_PROP_FS_VERITY_BUILTIN_SIG=y + CONFIG_SECURITY_IPE_KUNIT_TEST=y + +In addition, IPE has a python based integration +`test suite <https://github.com/microsoft/ipe/tree/test-suite>`_ that +can test both user interfaces and enforcement functionalities. diff --git a/Documentation/security/keys/core.rst b/Documentation/security/keys/core.rst index cdc42ccc12e4..326b8a973828 100644 --- a/Documentation/security/keys/core.rst +++ b/Documentation/security/keys/core.rst @@ -869,7 +869,7 @@ The keyctl syscall functions are: - ``char *hashname`` specifies the NUL terminated string identifying the hash used from the kernel crypto API and applied for the KDF - operation. The KDF implemenation complies with SP800-56A as well + operation. The KDF implementation complies with SP800-56A as well as with SP800-108 (the counter KDF). - ``char *otherinfo`` specifies the OtherInfo data as documented in @@ -912,7 +912,7 @@ The keyctl syscall functions are: One application of restricted keyrings is to verify X.509 certificate chains or individual certificate signatures using the asymmetric key type. - See Documentation/crypto/asymmetric-keys.txt for specific restrictions + See Documentation/crypto/asymmetric-keys.rst for specific restrictions applicable to the asymmetric key type. @@ -1040,13 +1040,13 @@ The keyctl syscall functions are: "key" is the ID of the key to be watched. - "queue_fd" is a file descriptor referring to an open "/dev/watch_queue" - which manages the buffer into which notifications will be delivered. + "queue_fd" is a file descriptor referring to an open pipe which + manages the buffer into which notifications will be delivered. "filter" is either NULL to remove a watch or a filter specification to indicate what events are required from the key. - See Documentation/watch_queue.rst for more information. + See Documentation/core-api/watch_queue.rst for more information. Note that only one watch may be emplaced for any particular { key, queue_fd } combination. diff --git a/Documentation/security/keys/trusted-encrypted.rst b/Documentation/security/keys/trusted-encrypted.rst index 50ac8bcd6970..f4d7e162d5e4 100644 --- a/Documentation/security/keys/trusted-encrypted.rst +++ b/Documentation/security/keys/trusted-encrypted.rst @@ -6,30 +6,188 @@ Trusted and Encrypted Keys are two new key types added to the existing kernel key ring service. Both of these new types are variable length symmetric keys, and in both cases all keys are created in the kernel, and user space sees, stores, and loads only encrypted blobs. Trusted Keys require the availability -of a Trusted Platform Module (TPM) chip 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. +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 use a TPM both to generate and to seal the keys. Keys are sealed -under a 2048 bit RSA key in the TPM, and optionally sealed to specified PCR -(integrity measurement) values, and only unsealed by the TPM, if PCRs and blob -integrity verifications match. A loaded Trusted Key can be updated with new -(future) PCR values, so keys are easily migrated to new pcr values, such as -when the kernel and initramfs are updated. The same key can have many saved -blobs under different PCR values, so multiple boots are easily supported. -TPM 1.2 -------- +Trust Source +============ -By default, trusted keys are sealed under the SRK, which has the default -authorization value (20 zeros). This can be set at takeownership time with the -trouser's utility: "tpm_takeownership -u -z". +A trust source provides the source of security for Trusted Keys. This +section lists currently supported trust sources, along with their security +considerations. Whether or not a trust source is sufficiently safe depends +on the strength and correctness of its implementation, as well as the threat +environment for a specific use case. Since the kernel doesn't know what the +environment is, and there is no metric of trust, it is dependent on the +consumer of the Trusted Keys to determine if the trust source is sufficiently +safe. -TPM 2.0 -------- + * Root of trust for storage -The user must first create a storage key and make it persistent, so the key is -available after reboot. This can be done using the following commands. + (1) TPM (Trusted Platform Module: hardware device) + + Rooted to Storage Root Key (SRK) which never leaves the TPM that + provides crypto operation to establish root of trust for storage. + + (2) TEE (Trusted Execution Environment: OP-TEE based on Arm TrustZone) + + Rooted to Hardware Unique Key (HUK) which is generally burnt in on-chip + fuses and is accessible to TEE only. + + (3) CAAM (Cryptographic Acceleration and Assurance Module: IP on NXP SoCs) + + When High Assurance Boot (HAB) is enabled and the CAAM is in secure + mode, trust is rooted to the OTPMK, a never-disclosed 256-bit key + randomly generated and fused into each SoC at manufacturing time. + Otherwise, a common fixed test key is used instead. + + (4) DCP (Data Co-Processor: crypto accelerator of various i.MX SoCs) + + Rooted to a one-time programmable key (OTP) that is generally burnt + in the on-chip fuses and is accessible to the DCP encryption engine only. + DCP provides two keys that can be used as root of trust: the OTP key + 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). + + * Execution isolation + + (1) TPM + + Fixed set of operations running in isolated execution environment. + + (2) TEE + + Customizable set of operations running in isolated execution + environment verified via Secure/Trusted boot process. + + (3) CAAM + + Fixed set of operations running in isolated execution environment. + + (4) DCP + + Fixed set of cryptographic operations running in isolated execution + environment. Only basic blob key encryption is executed there. + The actual key sealing/unsealing is done on main processor/kernel space. + + * Optional binding to platform integrity state + + (1) TPM + + Keys can be optionally sealed to specified PCR (integrity measurement) + values, and only unsealed by the TPM, if PCRs and blob integrity + verifications match. A loaded Trusted Key can be updated with new + (future) PCR values, so keys are easily migrated to new PCR values, + such as when the kernel and initramfs are updated. The same key can + have many saved blobs under different PCR values, so multiple boots are + easily supported. + + (2) TEE + + Relies on Secure/Trusted boot process for platform integrity. It can + be extended with TEE based measured boot process. + + (3) CAAM + + Relies on the High Assurance Boot (HAB) mechanism of NXP SoCs + for platform integrity. + + (4) DCP + + Relies on Secure/Trusted boot process (called HAB by vendor) for + platform integrity. + + * Interfaces and APIs + + (1) TPM + + TPMs have well-documented, standardized interfaces and APIs. + + (2) TEE + + TEEs have well-documented, standardized client interface and APIs. For + more details refer to ``Documentation/driver-api/tee.rst``. + + (3) CAAM + + Interface is specific to silicon vendor. + + (4) DCP + + Vendor-specific API that is implemented as part of the DCP crypto driver in + ``drivers/crypto/mxs-dcp.c``. + + * Threat model + + The strength and appropriateness of a particular trust source for a given + purpose must be assessed when using them to protect security-relevant data. + + +Key Generation +============== + +Trusted Keys +------------ + +New keys are created from random numbers. They are encrypted/decrypted using +a child key in the storage key hierarchy. Encryption and decryption of the +child key must be protected by a strong access control policy within the +trust source. The random number generator in use differs according to the +selected trust source: + + * TPM: hardware device based RNG + + Keys are generated within the TPM. Strength of random numbers may vary + from one device manufacturer to another. + + * TEE: OP-TEE based on Arm TrustZone based RNG + + RNG is customizable as per platform needs. It can either be direct output + from platform specific hardware RNG or a software based Fortuna CSPRNG + which can be seeded via multiple entropy sources. + + * CAAM: Kernel RNG + + The normal kernel random number generator is used. To seed it from the + CAAM HWRNG, enable CRYPTO_DEV_FSL_CAAM_RNG_API and ensure the device + is probed. + + * DCP (Data Co-Processor: crypto accelerator of various i.MX SoCs) + + The DCP hardware device itself does not provide a dedicated RNG interface, + so the kernel default RNG is used. SoCs with DCP like the i.MX6ULL do have + a dedicated hardware RNG that is independent from DCP which can be enabled + to back the kernel RNG. + +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. + +Encrypted Keys +-------------- + +Encrypted keys do not depend on a trust source, and are faster, as they use AES +for encryption/decryption. New keys are created either from kernel-generated +random numbers or user-provided decrypted data, and are encrypted/decrypted +using a specified ‘master’ key. The ‘master’ key can either be a trusted-key or +user-key type. The main disadvantage of encrypted keys is that if they are not +rooted in a trusted key, they are only as secure as the user key encrypting +them. The master user key should therefore be loaded in as secure a way as +possible, preferably early in boot. + + +Usage +===== + +Trusted Keys usage: TPM +----------------------- + +TPM 1.2: By default, trusted keys are sealed under the SRK, which has the +default authorization value (20 bytes of 0s). This can be set at takeownership +time with the TrouSerS utility: "tpm_takeownership -u -z". + +TPM 2.0: The user must first create a storage key and make it persistent, so the +key is available after reboot. This can be done using the following commands. With the IBM TSS 2 stack:: @@ -39,10 +197,9 @@ With the IBM TSS 2 stack:: Or with the Intel TSS 2 stack:: - #> tpm2_createprimary --hierarchy o -G rsa2048 -o key.ctxt + #> tpm2_createprimary --hierarchy o -G rsa2048 -c key.ctxt [...] - handle: 0x800000FF - #> tpm2_evictcontrol -c key.ctxt -p 0x81000001 + #> tpm2_evictcontrol -c key.ctxt 0x81000001 persistentHandle: 0x81000001 Usage:: @@ -79,14 +236,47 @@ TPM_STORED_DATA format. The key length for new keys are always in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits), the upper limit is to fit within the 2048 bit SRK (RSA) keylength, with all necessary structure/padding. -Encrypted keys do not depend on a TPM, and are faster, as they use AES for -encryption/decryption. New keys are created from kernel generated random -numbers, and are encrypted/decrypted using a specified 'master' key. The -'master' key can either be a trusted-key or user-key type. The main -disadvantage of encrypted keys is that if they are not rooted in a trusted key, -they are only as secure as the user key encrypting them. The master user key -should therefore be loaded in as secure a way as possible, preferably early in -boot. +Trusted Keys usage: TEE +----------------------- + +Usage:: + + keyctl add trusted name "new keylen" ring + keyctl add trusted name "load hex_blob" ring + keyctl print keyid + +"keyctl print" returns an ASCII hex copy of the sealed key, which is in format +specific to TEE device implementation. The key length for new keys is always +in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits). + +Trusted Keys usage: CAAM +------------------------ + +Usage:: + + keyctl add trusted name "new keylen" ring + keyctl add trusted name "load hex_blob" ring + keyctl print keyid + +"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 +----------------------- + +Usage:: + + keyctl add trusted name "new keylen" ring + keyctl add trusted name "load hex_blob" ring + keyctl print keyid + +"keyctl print" returns an ASCII hex copy of the sealed key, which is in format +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). + +Encrypted Keys usage +-------------------- The decrypted portion of encrypted keys can contain either a simple symmetric key or a more complex structure. The format of the more complex structure is @@ -96,6 +286,8 @@ Usage:: keyctl add encrypted name "new [format] key-type:master-key-name keylen" ring + keyctl add encrypted name "new [format] key-type:master-key-name keylen + decrypted-data" ring keyctl add encrypted name "load hex_blob" ring keyctl update keyid "update key-type:master-key-name" @@ -104,8 +296,8 @@ Where:: format:= 'default | ecryptfs | enc32' key-type:= 'trusted' | 'user' - -Examples of trusted and encrypted key usage: +Examples of trusted and encrypted key usage +------------------------------------------- Create and save a trusted key named "kmk" of length 32 bytes. @@ -151,7 +343,7 @@ Load a trusted key from the saved blob:: f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b e4a8aea2b607ec96931e6f4d4fe563ba -Reseal a trusted key under new pcr values:: +Reseal (TPM specific) a trusted key under new PCR values:: $ keyctl update 268728824 "update pcrinfo=`cat pcr.blob`" $ keyctl print 268728824 @@ -165,11 +357,12 @@ Reseal a trusted key under new pcr values:: 7ef6a24defe4846104209bf0c3eced7fa1a672ed5b125fc9d8cd88b476a658a4434644ef df8ae9a178e9f83ba9f08d10fa47e4226b98b0702f06b3b8 + The initial consumer of trusted keys is EVM, which at boot time needs a high -quality symmetric key for HMAC protection of file metadata. The use of a +quality symmetric key for HMAC protection of file metadata. The use of a trusted key provides strong guarantees that the EVM key has not been -compromised by a user level problem, and when sealed to specific boot PCR -values, protects against boot and offline attacks. Create and save an +compromised by a user level problem, and when sealed to a platform integrity +state, protects against boot and offline attacks. Create and save an encrypted key "evm" using the above trusted key "kmk": option 1: omitting 'format':: @@ -199,8 +392,19 @@ Load an encrypted key "evm" from saved blob:: 82dbbc55be2a44616e4959430436dc4f2a7a9659aa60bb4652aeb2120f149ed197c564e0 24717c64 5972dcb82ab2dde83376d82b2e3c09ffc +Instantiate an encrypted key "evm" using user-provided decrypted data:: + + $ evmkey=$(dd if=/dev/urandom bs=1 count=32 | xxd -c32 -p) + $ keyctl add encrypted evm "new default user:kmk 32 $evmkey" @u + 794890253 + + $ keyctl print 794890253 + default user:kmk 32 2375725ad57798846a9bbd240de8906f006e66c03af53b1b382d + bbc55be2a44616e4959430436dc4f2a7a9659aa60bb4652aeb2120f149ed197c564e0247 + 17c64 5972dcb82ab2dde83376d82b2e3c09ffc + Other uses for trusted and encrypted keys, such as for disk and file encryption -are anticipated. In particular the new format 'ecryptfs' has been defined in +are anticipated. In particular the new format 'ecryptfs' has been defined in order to use encrypted keys to mount an eCryptfs filesystem. More details about the usage can be found in the file ``Documentation/security/keys/ecryptfs.rst``. @@ -208,3 +412,70 @@ about the usage can be found in the file Another new format 'enc32' has been defined in order to support encrypted keys with payload size of 32 bytes. This will initially be used for nvdimm security but may expand to other usages that require 32 bytes payload. + + +TPM 2.0 ASN.1 Key Format +------------------------ + +The TPM 2.0 ASN.1 key format is designed to be easily recognisable, +even in binary form (fixing a problem we had with the TPM 1.2 ASN.1 +format) and to be extensible for additions like importable keys and +policy:: + + TPMKey ::= SEQUENCE { + type OBJECT IDENTIFIER + emptyAuth [0] EXPLICIT BOOLEAN OPTIONAL + parent INTEGER + pubkey OCTET STRING + privkey OCTET STRING + } + +type is what distinguishes the key even in binary form since the OID +is provided by the TCG to be unique and thus forms a recognizable +binary pattern at offset 3 in the key. The OIDs currently made +available are:: + + 2.23.133.10.1.3 TPM Loadable key. This is an asymmetric key (Usually + RSA2048 or Elliptic Curve) which can be imported by a + TPM2_Load() operation. + + 2.23.133.10.1.4 TPM Importable Key. This is an asymmetric key (Usually + RSA2048 or Elliptic Curve) which can be imported by a + TPM2_Import() operation. + + 2.23.133.10.1.5 TPM Sealed Data. This is a set of data (up to 128 + bytes) which is sealed by the TPM. It usually + represents a symmetric key and must be unsealed before + use. + +The trusted key code only uses the TPM Sealed Data OID. + +emptyAuth is true if the key has well known authorization "". If it +is false or not present, the key requires an explicit authorization +phrase. This is used by most user space consumers to decide whether +to prompt for a password. + +parent represents the parent key handle, either in the 0x81 MSO space, +like 0x81000001 for the RSA primary storage key. Userspace programmes +also support specifying the primary handle in the 0x40 MSO space. If +this happens the Elliptic Curve variant of the primary key using the +TCG defined template will be generated on the fly into a volatile +object and used as the parent. The current kernel code only supports +the 0x81 MSO form. + +pubkey is the binary representation of TPM2B_PRIVATE excluding the +initial TPM2B header, which can be reconstructed from the ASN.1 octet +string length. + +privkey is the binary representation of TPM2B_PUBLIC excluding the +initial TPM2B header which can be reconstructed from the ASN.1 octed +string length. + +DCP Blob Format +--------------- + +.. kernel-doc:: security/keys/trusted-keys/trusted_dcp.c + :doc: dcp blob format + +.. kernel-doc:: security/keys/trusted-keys/trusted_dcp.c + :identifiers: struct dcp_blob_fmt diff --git a/Documentation/security/landlock.rst b/Documentation/security/landlock.rst new file mode 100644 index 000000000000..e0fc54aff09e --- /dev/null +++ b/Documentation/security/landlock.rst @@ -0,0 +1,140 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. Copyright © 2017-2020 Mickaël Salaün <mic@digikod.net> +.. Copyright © 2019-2020 ANSSI + +================================== +Landlock LSM: kernel documentation +================================== + +:Author: Mickaël Salaün +:Date: March 2025 + +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, +including unprivileged ones. Because such a process may be compromised or +backdoored (i.e. untrusted), Landlock's features must be safe to use from the +kernel and other processes point of view. Landlock's interface must therefore +expose a minimal attack surface. + +Landlock is designed to be usable by unprivileged processes while following the +system security policy enforced by other access control mechanisms (e.g. DAC, +LSM). A Landlock rule shall not interfere with other access-controls enforced +on the system, only add more restrictions. + +Any user can enforce Landlock rulesets on their processes. They are merged and +evaluated against inherited rulesets in a way that ensures that only more +constraints can be added. + +User space documentation can be found here: +Documentation/userspace-api/landlock.rst. + +Guiding principles for safe access controls +=========================================== + +* A Landlock rule shall be focused on access control on kernel objects instead + of syscall filtering (i.e. syscall arguments), which is the purpose of + seccomp-bpf. +* To avoid multiple kinds of side-channel attacks (e.g. leak of security + policies, CPU-based attacks), Landlock rules shall not be able to + programmatically communicate with user space. +* Kernel access check shall not slow down access request from unsandboxed + processes. +* Computation related to Landlock operations (e.g. enforcing a ruleset) shall + only impact the processes requesting them. +* Resources (e.g. file descriptors) directly obtained from the kernel by a + sandboxed process shall retain their scoped accesses (at the time of resource + acquisition) whatever process uses them. + Cf. `File descriptor access rights`_. +* Access denials shall be logged according to system and Landlock domain + configurations. Log entries must contain information about the cause of the + denial and the owner of the related security policy. Such log generation + should have a negligible performance and memory impact on allowed requests. + +Design choices +============== + +Inode access rights +------------------- + +All access rights are tied to an inode and what can be accessed through it. +Reading the content of a directory does not imply to be allowed to read the +content of a listed inode. Indeed, a file name is local to its parent +directory, and an inode can be referenced by multiple file names thanks to +(hard) links. Being able to unlink a file only has a direct impact on the +directory, not the unlinked inode. This is the reason why +``LANDLOCK_ACCESS_FS_REMOVE_FILE`` or ``LANDLOCK_ACCESS_FS_REFER`` are not +allowed to be tied to files but only to directories. + +File descriptor access rights +----------------------------- + +Access rights are checked and tied to file descriptors at open time. The +underlying principle is that equivalent sequences of operations should lead to +the same results, when they are executed under the same Landlock domain. + +Taking the ``LANDLOCK_ACCESS_FS_TRUNCATE`` right as an example, it may be +allowed to open a file for writing without being allowed to +:manpage:`ftruncate` the resulting file descriptor if the related file +hierarchy doesn't grant that access right. The following sequences of +operations have the same semantic and should then have the same result: + +* ``truncate(path);`` +* ``int fd = open(path, O_WRONLY); ftruncate(fd); close(fd);`` + +Similarly to file access modes (e.g. ``O_RDWR``), Landlock access rights +attached to file descriptors are retained even if they are passed between +processes (e.g. through a Unix domain socket). Such access rights will then be +enforced even if the receiving process is not sandboxed by Landlock. Indeed, +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). + +Tests +===== + +Userspace tests for backward compatibility, ptrace restrictions and filesystem +support can be found here: `tools/testing/selftests/landlock/`_. + +Kernel structures +================= + +Object +------ + +.. kernel-doc:: security/landlock/object.h + :identifiers: + +Filesystem +---------- + +.. kernel-doc:: security/landlock/fs.h + :identifiers: + +Ruleset and domain +------------------ + +A domain is a read-only ruleset tied to a set of subjects (i.e. tasks' +credentials). Each time a ruleset is enforced on a task, the current domain is +duplicated and the ruleset is imported as a new layer of rules in the new +domain. Indeed, once in a domain, each rule is tied to a layer level. To +grant access to an object, at least one rule of each layer must allow the +requested action on the object. A task can then only transit to a new domain +that is the intersection of the constraints from the current domain and those +of a ruleset provided by the task. + +The definition of a subject is implicit for a task sandboxing itself, which +makes the reasoning much easier and helps avoid pitfalls. + +.. kernel-doc:: security/landlock/ruleset.h + :identifiers: + +Additional documentation +======================== + +* Documentation/userspace-api/landlock.rst +* Documentation/admin-guide/LSM/landlock.rst +* https://landlock.io + +.. Links +.. _tools/testing/selftests/landlock/: + https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/testing/selftests/landlock/ diff --git a/Documentation/security/lsm-development.rst b/Documentation/security/lsm-development.rst index 31d92bc5fdd2..5895e529da7f 100644 --- a/Documentation/security/lsm-development.rst +++ b/Documentation/security/lsm-development.rst @@ -2,7 +2,7 @@ Linux Security Module Development ================================= -Based on https://lkml.org/lkml/2007/10/26/215, +Based on https://lore.kernel.org/r/20071026073721.618b4778@laptopd505.fenrus.org, a new LSM is accepted into the kernel when its intent (a description of what it tries to protect against and in what cases one would expect to use it) has been appropriately documented in ``Documentation/admin-guide/LSM/``. @@ -11,7 +11,7 @@ that end users and distros can make a more informed decision about which LSMs suit their requirements. For extensive documentation on the available LSM hook interfaces, please -see ``include/linux/lsm_hooks.h`` and associated structures: +see ``security/security.c`` and associated structures: -.. kernel-doc:: include/linux/lsm_hooks.h - :internal: +.. kernel-doc:: security/security.c + :export: diff --git a/Documentation/security/lsm.rst b/Documentation/security/lsm.rst index 6a2a2e973080..c20c7c72e2d6 100644 --- a/Documentation/security/lsm.rst +++ b/Documentation/security/lsm.rst @@ -98,7 +98,7 @@ associate these values with real security attributes. LSM hooks are maintained in lists. A list is maintained for each hook, and the hooks are called in the order specified by CONFIG_LSM. Detailed documentation for each hook is -included in the `include/linux/lsm_hooks.h` header file. +included in the `security/security.c` source file. The LSM framework provides for a close approximation of general security module stacking. It defines diff --git a/Documentation/security/secrets/coco.rst b/Documentation/security/secrets/coco.rst new file mode 100644 index 000000000000..a1210db8ec07 --- /dev/null +++ b/Documentation/security/secrets/coco.rst @@ -0,0 +1,103 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================== +Confidential Computing secrets +============================== + +This document describes how Confidential Computing secret injection is handled +from the firmware to the operating system, in the EFI driver and the efi_secret +kernel module. + + +Introduction +============ + +Confidential Computing (coco) hardware such as AMD SEV (Secure Encrypted +Virtualization) allows guest owners to inject secrets into the VMs +memory without the host/hypervisor being able to read them. In SEV, +secret injection is performed early in the VM launch process, before the +guest starts running. + +The efi_secret kernel module allows userspace applications to access these +secrets via securityfs. + + +Secret data flow +================ + +The guest firmware may reserve a designated memory area for secret injection, +and publish its location (base GPA and length) in the EFI configuration table +under a ``LINUX_EFI_COCO_SECRET_AREA_GUID`` entry +(``adf956ad-e98c-484c-ae11-b51c7d336447``). This memory area should be marked +by the firmware as ``EFI_RESERVED_TYPE``, and therefore the kernel should not +be use it for its own purposes. + +During the VM's launch, the virtual machine manager may inject a secret to that +area. In AMD SEV and SEV-ES this is performed using the +``KVM_SEV_LAUNCH_SECRET`` command (see [sev]_). The structure of the injected +Guest Owner secret data should be a GUIDed table of secret values; the binary +format is described in ``drivers/virt/coco/efi_secret/efi_secret.c`` under +"Structure of the EFI secret area". + +On kernel start, the kernel's EFI driver saves the location of the secret area +(taken from the EFI configuration table) in the ``efi.coco_secret`` field. +Later it checks if the secret area is populated: it maps the area and checks +whether its content begins with ``EFI_SECRET_TABLE_HEADER_GUID`` +(``1e74f542-71dd-4d66-963e-ef4287ff173b``). If the secret area is populated, +the EFI driver will autoload the efi_secret kernel module, which exposes the +secrets to userspace applications via securityfs. The details of the +efi_secret filesystem interface are in [secrets-coco-abi]_. + + +Application usage example +========================= + +Consider a guest performing computations on encrypted files. The Guest Owner +provides the decryption key (= secret) using the secret injection mechanism. +The guest application reads the secret from the efi_secret filesystem and +proceeds to decrypt the files into memory and then performs the needed +computations on the content. + +In this example, the host can't read the files from the disk image +because they are encrypted. Host can't read the decryption key because +it is passed using the secret injection mechanism (= secure channel). +Host can't read the decrypted content from memory because it's a +confidential (memory-encrypted) guest. + +Here is a simple example for usage of the efi_secret module in a guest +to which an EFI secret area with 4 secrets was injected during launch:: + + # ls -la /sys/kernel/security/secrets/coco + total 0 + drwxr-xr-x 2 root root 0 Jun 28 11:54 . + drwxr-xr-x 3 root root 0 Jun 28 11:54 .. + -r--r----- 1 root root 0 Jun 28 11:54 736870e5-84f0-4973-92ec-06879ce3da0b + -r--r----- 1 root root 0 Jun 28 11:54 83c83f7f-1356-4975-8b7e-d3a0b54312c6 + -r--r----- 1 root root 0 Jun 28 11:54 9553f55d-3da2-43ee-ab5d-ff17f78864d2 + -r--r----- 1 root root 0 Jun 28 11:54 e6f5a162-d67f-4750-a67c-5d065f2a9910 + + # hd /sys/kernel/security/secrets/coco/e6f5a162-d67f-4750-a67c-5d065f2a9910 + 00000000 74 68 65 73 65 2d 61 72 65 2d 74 68 65 2d 6b 61 |these-are-the-ka| + 00000010 74 61 2d 73 65 63 72 65 74 73 00 01 02 03 04 05 |ta-secrets......| + 00000020 06 07 |..| + 00000022 + + # rm /sys/kernel/security/secrets/coco/e6f5a162-d67f-4750-a67c-5d065f2a9910 + + # ls -la /sys/kernel/security/secrets/coco + total 0 + drwxr-xr-x 2 root root 0 Jun 28 11:55 . + drwxr-xr-x 3 root root 0 Jun 28 11:54 .. + -r--r----- 1 root root 0 Jun 28 11:54 736870e5-84f0-4973-92ec-06879ce3da0b + -r--r----- 1 root root 0 Jun 28 11:54 83c83f7f-1356-4975-8b7e-d3a0b54312c6 + -r--r----- 1 root root 0 Jun 28 11:54 9553f55d-3da2-43ee-ab5d-ff17f78864d2 + + +References +========== + +See [sev-api-spec]_ for more info regarding SEV ``LAUNCH_SECRET`` operation. + +.. [sev] Documentation/virt/kvm/x86/amd-memory-encryption.rst +.. [secrets-coco-abi] Documentation/ABI/testing/securityfs-secrets-coco +.. [sev-api-spec] https://www.amd.com/system/files/TechDocs/55766_SEV-KM_API_Specification.pdf diff --git a/Documentation/security/secrets/index.rst b/Documentation/security/secrets/index.rst new file mode 100644 index 000000000000..ced34e9c43bd --- /dev/null +++ b/Documentation/security/secrets/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================== +Secrets documentation +===================== + +.. toctree:: + + coco diff --git a/Documentation/security/self-protection.rst b/Documentation/security/self-protection.rst index f584fb74b4ff..910668e665cb 100644 --- a/Documentation/security/self-protection.rst +++ b/Documentation/security/self-protection.rst @@ -81,8 +81,7 @@ of the kernel, gaining the protection of the kernel's strict memory permissions as described above. For variables that are initialized once at ``__init`` time, these can -be marked with the (new and under development) ``__ro_after_init`` -attribute. +be marked with the ``__ro_after_init`` attribute. What remains are variables that are updated rarely (e.g. GDT). These will need another infrastructure (similar to the temporary exceptions diff --git a/Documentation/security/siphash.rst b/Documentation/security/siphash.rst index bd9363025fcb..023bd95c74a5 100644 --- a/Documentation/security/siphash.rst +++ b/Documentation/security/siphash.rst @@ -85,7 +85,7 @@ Often times the XuY functions will not be large enough, and instead you'll want to pass a pre-filled struct to siphash. When doing this, it's important to always ensure the struct has no padding holes. The easiest way to do this is to simply arrange the members of the struct in descending order of size, -and to use offsetendof() instead of sizeof() for getting the size. For +and to use offsetofend() instead of sizeof() for getting the size. For performance reasons, if possible, it's probably a good thing to align the struct to the right boundary. Here's an example:: @@ -121,26 +121,36 @@ even scarier, uses an easily brute-forcable 64-bit key (with a 32-bit output) instead of SipHash's 128-bit key. However, this may appeal to some high-performance `jhash` users. -Danger! +HalfSipHash support is provided through the "hsiphash" family of functions. -Do not ever use HalfSipHash except for as a hashtable key function, and only -then when you can be absolutely certain that the outputs will never be -transmitted out of the kernel. This is only remotely useful over `jhash` as a -means of mitigating hashtable flooding denial of service attacks. +.. warning:: + Do not ever use the hsiphash functions except for as a hashtable key + function, and only then when you can be absolutely certain that the outputs + will never be transmitted out of the kernel. This is only remotely useful + over `jhash` as a means of mitigating hashtable flooding denial of service + attacks. -Generating a HalfSipHash key -============================ +On 64-bit kernels, the hsiphash functions actually implement SipHash-1-3, a +reduced-round variant of SipHash, instead of HalfSipHash-1-3. This is because in +64-bit code, SipHash-1-3 is no slower than HalfSipHash-1-3, and can be faster. +Note, this does *not* mean that in 64-bit kernels the hsiphash functions are the +same as the siphash ones, or that they are secure; the hsiphash functions still +use a less secure reduced-round algorithm and truncate their outputs to 32 +bits. + +Generating a hsiphash key +========================= Keys should always be generated from a cryptographically secure source of -random numbers, either using get_random_bytes or get_random_once: +random numbers, either using get_random_bytes or get_random_once:: -hsiphash_key_t key; -get_random_bytes(&key, sizeof(key)); + hsiphash_key_t key; + get_random_bytes(&key, sizeof(key)); If you're not deriving your key from here, you're doing it wrong. -Using the HalfSipHash functions -=============================== +Using the hsiphash functions +============================ There are two variants of the function, one that takes a list of integers, and one that takes a buffer:: @@ -183,7 +193,7 @@ You may then iterate like usual over the returned hash bucket. Performance =========== -HalfSipHash is roughly 3 times slower than JenkinsHash. For many replacements, -this will not be a problem, as the hashtable lookup isn't the bottleneck. And -in general, this is probably a good sacrifice to make for the security and DoS -resistance of HalfSipHash. +hsiphash() is roughly 3 times slower than jhash(). For many replacements, this +will not be a problem, as the hashtable lookup isn't the bottleneck. And in +general, this is probably a good sacrifice to make for the security and DoS +resistance of hsiphash(). diff --git a/Documentation/security/snp-tdx-threat-model.rst b/Documentation/security/snp-tdx-threat-model.rst new file mode 100644 index 000000000000..3a2d41d2e645 --- /dev/null +++ b/Documentation/security/snp-tdx-threat-model.rst @@ -0,0 +1,253 @@ +====================================================== +Confidential Computing in Linux for x86 virtualization +====================================================== + +.. contents:: :local: + +By: Elena Reshetova <elena.reshetova@intel.com> and Carlos Bilbao <carlos.bilbao.osdev@gmail.com> + +Motivation +========== + +Kernel developers working on confidential computing for virtualized +environments in x86 operate under a set of assumptions regarding the Linux +kernel threat model that differ from the traditional view. Historically, +the Linux threat model acknowledges attackers residing in userspace, as +well as a limited set of external attackers that are able to interact with +the kernel through various networking or limited HW-specific exposed +interfaces (USB, thunderbolt). The goal of this document is to explain +additional attack vectors that arise in the confidential computing space +and discuss the proposed protection mechanisms for the Linux kernel. + +Overview and terminology +======================== + +Confidential Computing (CoCo) is a broad term covering a wide range of +security technologies that aim to protect the confidentiality and integrity +of data in use (vs. data at rest or data in transit). At its core, CoCo +solutions provide a Trusted Execution Environment (TEE), where secure data +processing can be performed and, as a result, they are typically further +classified into different subtypes depending on the SW that is intended +to be run in TEE. This document focuses on a subclass of CoCo technologies +that are targeting virtualized environments and allow running Virtual +Machines (VM) inside TEE. From now on in this document will be referring +to this subclass of CoCo as 'Confidential Computing (CoCo) for the +virtualized environments (VE)'. + +CoCo, in the virtualization context, refers to a set of HW and/or SW +technologies that allow for stronger security guarantees for the SW running +inside a CoCo VM. Namely, confidential computing allows its users to +confirm the trustworthiness of all SW pieces to include in its reduced +Trusted Computing Base (TCB) given its ability to attest the state of these +trusted components. + +While the concrete implementation details differ between technologies, all +available mechanisms aim to provide increased confidentiality and +integrity for the VM's guest memory and execution state (vCPU registers), +more tightly controlled guest interrupt injection, as well as some +additional mechanisms to control guest-host page mapping. More details on +the x86-specific solutions can be found in +:doc:`Intel Trust Domain Extensions (TDX) </arch/x86/tdx>` and +`AMD Memory Encryption <https://www.amd.com/system/files/techdocs/sev-snp-strengthening-vm-isolation-with-integrity-protection-and-more.pdf>`_. + +The basic CoCo guest layout includes the host, guest, the interfaces that +communicate guest and host, a platform capable of supporting CoCo VMs, and +a trusted intermediary between the guest VM and the underlying platform +that acts as a security manager. The host-side virtual machine monitor +(VMM) typically consists of a subset of traditional VMM features and +is still in charge of the guest lifecycle, i.e. create or destroy a CoCo +VM, manage its access to system resources, etc. However, since it +typically stays out of CoCo VM TCB, its access is limited to preserve the +security objectives. + +In the following diagram, the "<--->" lines represent bi-directional +communication channels or interfaces between the CoCo security manager and +the rest of the components (data flow for guest, host, hardware) :: + + +-------------------+ +-----------------------+ + | CoCo guest VM |<---->| | + +-------------------+ | | + | Interfaces | | CoCo security manager | + +-------------------+ | | + | Host VMM |<---->| | + +-------------------+ | | + | | + +--------------------+ | | + | CoCo platform |<--->| | + +--------------------+ +-----------------------+ + +The specific details of the CoCo security manager vastly diverge between +technologies. For example, in some cases, it will be implemented in HW +while in others it may be pure SW. + +Existing Linux kernel threat model +================================== + +The overall components of the current Linux kernel threat model are:: + + +-----------------------+ +-------------------+ + | |<---->| Userspace | + | | +-------------------+ + | External attack | | Interfaces | + | vectors | +-------------------+ + | |<---->| Linux Kernel | + | | +-------------------+ + +-----------------------+ +-------------------+ + | Bootloader/BIOS | + +-------------------+ + +-------------------+ + | HW platform | + +-------------------+ + +There is also communication between the bootloader and the kernel during +the boot process, but this diagram does not represent it explicitly. The +"Interfaces" box represents the various interfaces that allow +communication between kernel and userspace. This includes system calls, +kernel APIs, device drivers, etc. + +The existing Linux kernel threat model typically assumes execution on a +trusted HW platform with all of the firmware and bootloaders included on +its TCB. The primary attacker resides in the userspace, and all of the data +coming from there is generally considered untrusted, unless userspace is +privileged enough to perform trusted actions. In addition, external +attackers are typically considered, including those with access to enabled +external networks (e.g. Ethernet, Wireless, Bluetooth), exposed hardware +interfaces (e.g. USB, Thunderbolt), and the ability to modify the contents +of disks offline. + +Regarding external attack vectors, it is interesting to note that in most +cases external attackers will try to exploit vulnerabilities in userspace +first, but that it is possible for an attacker to directly target the +kernel; particularly if the host has physical access. Examples of direct +kernel attacks include the vulnerabilities CVE-2019-19524, CVE-2022-0435 +and CVE-2020-24490. + +Confidential Computing threat model and its security objectives +=============================================================== + +Confidential Computing adds a new type of attacker to the above list: a +potentially misbehaving host (which can also include some part of a +traditional VMM or all of it), which is typically placed outside of the +CoCo VM TCB due to its large SW attack surface. It is important to note +that this doesn’t imply that the host or VMM are intentionally +malicious, but that there exists a security value in having a small CoCo +VM TCB. This new type of adversary may be viewed as a more powerful type +of external attacker, as it resides locally on the same physical machine +(in contrast to a remote network attacker) and has control over the guest +kernel communication with most of the HW:: + + +------------------------+ + | CoCo guest VM | + +-----------------------+ | +-------------------+ | + | |<--->| | Userspace | | + | | | +-------------------+ | + | External attack | | | Interfaces | | + | vectors | | +-------------------+ | + | |<--->| | Linux Kernel | | + | | | +-------------------+ | + +-----------------------+ | +-------------------+ | + | | Bootloader/BIOS | | + +-----------------------+ | +-------------------+ | + | |<--->+------------------------+ + | | | Interfaces | + | | +------------------------+ + | CoCo security |<--->| Host/Host-side VMM | + | manager | +------------------------+ + | | +------------------------+ + | |<--->| CoCo platform | + +-----------------------+ +------------------------+ + +While traditionally the host has unlimited access to guest data and can +leverage this access to attack the guest, the CoCo systems mitigate such +attacks by adding security features like guest data confidentiality and +integrity protection. This threat model assumes that those features are +available and intact. + +The **Linux kernel CoCo VM security objectives** can be summarized as follows: + +1. Preserve the confidentiality and integrity of CoCo guest's private +memory and registers. + +2. Prevent privileged escalation from a host into a CoCo guest Linux kernel. +While it is true that the host (and host-side VMM) requires some level of +privilege to create, destroy, or pause the guest, part of the goal of +preventing privileged escalation is to ensure that these operations do not +provide a pathway for attackers to gain access to the guest's kernel. + +The above security objectives result in two primary **Linux kernel CoCo +VM assets**: + +1. Guest kernel execution context. +2. Guest kernel private memory. + +The host retains full control over the CoCo guest resources, and can deny +access to them at any time. Examples of resources include CPU time, memory +that the guest can consume, network bandwidth, etc. Because of this, the +host Denial of Service (DoS) attacks against CoCo guests are beyond the +scope of this threat model. + +The **Linux CoCo VM attack surface** is any interface exposed from a CoCo +guest Linux kernel towards an untrusted host that is not covered by the +CoCo technology SW/HW protection. This includes any possible +side-channels, as well as transient execution side channels. Examples of +explicit (not side-channel) interfaces include accesses to port I/O, MMIO +and DMA interfaces, access to PCI configuration space, VMM-specific +hypercalls (towards Host-side VMM), access to shared memory pages, +interrupts allowed to be injected into the guest kernel by the host, as +well as CoCo technology-specific hypercalls, if present. Additionally, the +host in a CoCo system typically controls the process of creating a CoCo +guest: it has a method to load into a guest the firmware and bootloader +images, the kernel image together with the kernel command line. All of this +data should also be considered untrusted until its integrity and +authenticity is established via attestation. + +The table below shows a threat matrix for the CoCo guest Linux kernel but +does not discuss potential mitigation strategies. The matrix refers to +CoCo-specific versions of the guest, host and platform. + +.. list-table:: CoCo Linux guest kernel threat matrix + :widths: auto + :align: center + :header-rows: 1 + + * - Threat name + - Threat description + + * - Guest malicious configuration + - A misbehaving host modifies one of the following guest's + configuration: + + 1. Guest firmware or bootloader + + 2. Guest kernel or module binaries + + 3. Guest command line parameters + + This allows the host to break the integrity of the code running + inside a CoCo guest, and violates the CoCo security objectives. + + * - CoCo guest data attacks + - A misbehaving host retains full control of the CoCo guest's data + in-transit between the guest and the host-managed physical or + virtual devices. This allows any attack against confidentiality, + integrity or freshness of such data. + + * - Malformed runtime input + - A misbehaving host injects malformed input via any communication + interface used by the guest's kernel code. If the code is not + prepared to handle this input correctly, this can result in a host + --> guest kernel privilege escalation. This includes traditional + side-channel and/or transient execution attack vectors. + + * - Malicious runtime input + - A misbehaving host injects a specific input value via any + communication interface used by the guest's kernel code. The + difference with the previous attack vector (malformed runtime input) + is that this input is not malformed, but its value is crafted to + impact the guest's kernel security. Examples of such inputs include + providing a malicious time to the guest or the entropy to the guest + random number generator. Additionally, the timing of such events can + be an attack vector on its own, if it results in a particular guest + kernel action (i.e. processing of a host-injected interrupt). + resistant to supplied host input. + diff --git a/Documentation/security/tpm/index.rst b/Documentation/security/tpm/index.rst index fc40e9f23c85..deda952eacbe 100644 --- a/Documentation/security/tpm/index.rst +++ b/Documentation/security/tpm/index.rst @@ -5,6 +5,9 @@ Trusted Platform Module documentation .. toctree:: tpm_event_log + tpm-security + tpm_tis tpm_vtpm_proxy xen-tpmfront tpm_ftpm_tee + tpm_ffa_crb diff --git a/Documentation/security/tpm/tpm-security.rst b/Documentation/security/tpm/tpm-security.rst new file mode 100644 index 000000000000..4f633f251033 --- /dev/null +++ b/Documentation/security/tpm/tpm-security.rst @@ -0,0 +1,216 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +TPM Security +============ + +The object of this document is to describe how we make the kernel's +use of the TPM reasonably robust in the face of external snooping and +packet alteration attacks (called passive and active interposer attack +in the literature). The current security document is for TPM 2.0. + +Introduction +------------ + +The TPM is usually a discrete chip attached to a PC via some type of +low bandwidth bus. There are exceptions to this such as the Intel +PTT, which is a software TPM running inside a software environment +close to the CPU, which are subject to different attacks, but right at +the moment, most hardened security environments require a discrete +hardware TPM, which is the use case discussed here. + +Snooping and Alteration Attacks against the bus +----------------------------------------------- + +The current state of the art for snooping the `TPM Genie`_ hardware +interposer which is a simple external device that can be installed in +a couple of seconds on any system or laptop. Recently attacks were +successfully demonstrated against the `Windows Bitlocker TPM`_ system. +Most recently the same `attack against TPM based Linux disk +encryption`_ schemes. The next phase of research seems to be hacking +existing devices on the bus to act as interposers, so the fact that +the attacker requires physical access for a few seconds might +evaporate. However, the goal of this document is to protect TPM +secrets and integrity as far as we are able in this environment and to +try to insure that if we can't prevent the attack then at least we can +detect it. + +Unfortunately, most of the TPM functionality, including the hardware +reset capability can be controlled by an attacker who has access to +the bus, so we'll discuss some of the disruption possibilities below. + +Measurement (PCR) Integrity +--------------------------- + +Since the attacker can send their own commands to the TPM, they can +send arbitrary PCR extends and thus disrupt the measurement system, +which would be an annoying denial of service attack. However, there +are two, more serious, classes of attack aimed at entities sealed to +trust measurements. + +1. The attacker could intercept all PCR extends coming from the system + and completely substitute their own values, producing a replay of + an untampered state that would cause PCR measurements to attest to + a trusted state and release secrets + +2. At some point in time the attacker could reset the TPM, clearing + the PCRs and then send down their own measurements which would + effectively overwrite the boot time measurements the TPM has + already done. + +The first can be thwarted by always doing HMAC protection of the PCR +extend and read command meaning measurement values cannot be +substituted without producing a detectable HMAC failure in the +response. However, the second can only really be detected by relying +on some sort of mechanism for protection which would change over TPM +reset. + +Secrets Guarding +---------------- + +Certain information passing in and out of the TPM, such as key sealing +and private key import and random number generation, is vulnerable to +interception which HMAC protection alone cannot protect against, so +for these types of command we must also employ request and response +encryption to prevent the loss of secret information. + +Establishing Initial Trust with the TPM +--------------------------------------- + +In order to provide security from the beginning, an initial shared or +asymmetric secret must be established which must also be unknown to +the attacker. The most obvious avenues for this are the endorsement +and storage seeds, which can be used to derive asymmetric keys. +However, using these keys is difficult because the only way to pass +them into the kernel would be on the command line, which requires +extensive support in the boot system, and there's no guarantee that +either hierarchy would not have some type of authorization. + +The mechanism chosen for the Linux Kernel is to derive the primary +elliptic curve key from the null seed using the standard storage seed +parameters. The null seed has two advantages: firstly the hierarchy +physically cannot have an authorization, so we are always able to use +it and secondly, the null seed changes across TPM resets, meaning if +we establish trust on the null seed at start of day, all sessions +salted with the derived key will fail if the TPM is reset and the seed +changes. + +Obviously using the null seed without any other prior shared secrets, +we have to create and read the initial public key which could, of +course, be intercepted and substituted by the bus interposer. +However, the TPM has a key certification mechanism (using the EK +endorsement certificate, creating an attestation identity key and +certifying the null seed primary with that key) which is too complex +to run within the kernel, so we keep a copy of the null primary key +name, which is what is exported via sysfs so user-space can run the +full certification when it boots. The definitive guarantee here is +that if the null primary key certifies correctly, you know all your +TPM transactions since start of day were secure and if it doesn't, you +know there's an interposer on your system (and that any secret used +during boot may have been leaked). + +Stacking Trust +-------------- + +In the current null primary scenario, the TPM must be completely +cleared before handing it on to the next consumer. However the kernel +hands to user-space the name of the derived null seed key which can +then be verified by certification in user-space. Therefore, this chain +of name handoff can be used between the various boot components as +well (via an unspecified mechanism). For instance, grub could use the +null seed scheme for security and hand the name off to the kernel in +the boot area. The kernel could make its own derivation of the key +and the name and know definitively that if they differ from the handed +off version that tampering has occurred. Thus it becomes possible to +chain arbitrary boot components together (UEFI to grub to kernel) via +the name handoff provided each successive component knows how to +collect the name and verifies it against its derived key. + +Session Properties +------------------ + +All TPM commands the kernel uses allow sessions. HMAC sessions may be +used to check the integrity of requests and responses and decrypt and +encrypt flags may be used to shield parameters and responses. The +HMAC and encryption keys are usually derived from the shared +authorization secret, but for a lot of kernel operations that is well +known (and usually empty). Thus, every HMAC session used by the +kernel must be created using the null primary key as the salt key +which thus provides a cryptographic input into the session key +derivation. Thus, the kernel creates the null primary key once (as a +volatile TPM handle) and keeps it around in a saved context stored in +tpm_chip for every in-kernel use of the TPM. Currently, because of a +lack of de-gapping in the in-kernel resource manager, the session must +be created and destroyed for each operation, but, in future, a single +session may also be reused for the in-kernel HMAC, encryption and +decryption sessions. + +Protection Types +---------------- + +For every in-kernel operation we use null primary salted HMAC to +protect the integrity. Additionally, we use parameter encryption to +protect key sealing and parameter decryption to protect key unsealing +and random number generation. + +Null Primary Key Certification in Userspace +=========================================== + +Every TPM comes shipped with a couple of X.509 certificates for the +primary endorsement key. This document assumes that the Elliptic +Curve version of the certificate exists at 01C00002, but will work +equally well with the RSA certificate (at 01C00001). + +The first step in the certification is primary creation using the +template from the `TCG EK Credential Profile`_ which allows comparison +of the generated primary key against the one in the certificate (the +public key must match). Note that generation of the EK primary +requires the EK hierarchy password, but a pre-generated version of the +EC primary should exist at 81010002 and a TPM2_ReadPublic() may be +performed on this without needing the key authority. Next, the +certificate itself must be verified to chain back to the manufacturer +root (which should be published on the manufacturer website). Once +this is done, an attestation key (AK) is generated within the TPM and +it's name and the EK public key can be used to encrypt a secret using +TPM2_MakeCredential. The TPM then runs TPM2_ActivateCredential which +will only recover the secret if the binding between the TPM, the EK +and the AK is true. the generated AK may now be used to run a +certification of the null primary key whose name the kernel has +exported. Since TPM2_MakeCredential/ActivateCredential are somewhat +complicated, a more simplified process involving an externally +generated private key is described below. + +This process is a simplified abbreviation of the usual privacy CA +based attestation process. The assumption here is that the +attestation is done by the TPM owner who thus has access to only the +owner hierarchy. The owner creates an external public/private key +pair (assume elliptic curve in this case) and wraps the private key +for import using an inner wrapping process and parented to the EC +derived storage primary. The TPM2_Import() is done using a parameter +decryption HMAC session salted to the EK primary (which also does not +require the EK key authority) meaning that the inner wrapping key is +the encrypted parameter and thus the TPM will not be able to perform +the import unless is possesses the certified EK so if the command +succeeds and the HMAC verifies on return we know we have a loadable +copy of the private key only for the certified TPM. This key is now +loaded into the TPM and the Storage primary flushed (to free up space +for the null key generation). + +The null EC primary is now generated using the Storage profile +outlined in the `TCG TPM v2.0 Provisioning Guidance`_; the name of +this key (the hash of the public area) is computed and compared to the +null seed name presented by the kernel in +/sys/class/tpm/tpm0/null_name. If the names do not match, the TPM is +compromised. If the names match, the user performs a TPM2_Certify() +using the null primary as the object handle and the loaded private key +as the sign handle and providing randomized qualifying data. The +signature of the returned certifyInfo is verified against the public +part of the loaded private key and the qualifying data checked to +prevent replay. If all of these tests pass, the user is now assured +that TPM integrity and privacy was preserved across the entire boot +sequence of this kernel. + +.. _TPM Genie: https://www.nccgroup.trust/globalassets/about-us/us/documents/tpm-genie.pdf +.. _Windows Bitlocker TPM: https://dolosgroup.io/blog/2021/7/9/from-stolen-laptop-to-inside-the-company-network +.. _attack against TPM based Linux disk encryption: https://www.secura.com/blog/tpm-sniffing-attacks-against-non-bitlocker-targets +.. _TCG EK Credential Profile: https://trustedcomputinggroup.org/resource/tcg-ek-credential-profile-for-tpm-family-2-0/ +.. _TCG TPM v2.0 Provisioning Guidance: https://trustedcomputinggroup.org/resource/tcg-tpm-v2-0-provisioning-guidance/ diff --git a/Documentation/security/tpm/tpm_ffa_crb.rst b/Documentation/security/tpm/tpm_ffa_crb.rst new file mode 100644 index 000000000000..0184193da3c7 --- /dev/null +++ b/Documentation/security/tpm/tpm_ffa_crb.rst @@ -0,0 +1,65 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================== +TPM CRB over FF-A Driver +======================== + +The TPM Command Response Buffer (CRB) interface is a standard TPM interface +defined in the TCG PC Client Platform TPM Profile (PTP) Specification [1]_. +The CRB provides a structured set of control registers a client uses when +interacting with a TPM as well as a data buffer for storing TPM commands and +responses. A CRB interface can be implemented in: + +- hardware registers in a discrete TPM chip + +- in memory for a TPM running in isolated environment where shared memory + allows a client to interact with the TPM + +The Firmware Framework for Arm A-profile (FF-A) [2]_ is a specification +that defines interfaces and protocols for the following purposes: + +- Compartmentalize firmware into software partitions that run in the Arm + Secure world environment (also know as TrustZone) + +- Provide a standard interface for software components in the Non-secure + state, for example OS and Hypervisors, to communicate with this firmware. + +A TPM can be implemented as an FF-A secure service. This could be a firmware +TPM or could potentially be a TPM service that acts as a proxy to a discrete +TPM chip. An FF-A based TPM abstracts hardware details (e.g. bus controller +and chip selects) away from the OS and can protect locality 4 from access +by an OS. The TCG-defined CRB interface is used by clients to interact +with the TPM service. + +The Arm TPM Service Command Response Buffer Interface Over FF-A [3]_ +specification defines FF-A messages that can be used by a client to signal +when updates have been made to the CRB. + +How the Linux CRB driver interacts with FF-A is summarized below: + +- The tpm_crb_ffa driver registers with the FF-A subsystem in the kernel + with an architected TPM service UUID defined in the CRB over FF-A spec. + +- If a TPM service is discovered by FF-A, the probe() function in the + tpm_crb_ffa driver runs, and the driver initializes. + +- The probing and initialization of the Linux CRB driver is triggered + by the discovery of a TPM advertised via ACPI. The CRB driver can + detect the type of TPM through the ACPI 'start' method. The start + method for Arm FF-A was defined in TCG ACPI v1.4 [4]_. + +- When the CRB driver performs its normal functions such as signaling 'start' + and locality request/relinquish it invokes the tpm_crb_ffa_start() funnction + in the tpm_crb_ffa driver which handles the FF-A messaging to the TPM. + +References +========== + +.. [1] **TCG PC Client Platform TPM Profile (PTP) Specification** + https://trustedcomputinggroup.org/resource/pc-client-platform-tpm-profile-ptp-specification/ +.. [2] **Arm Firmware Framework for Arm A-profile (FF-A)** + https://developer.arm.com/documentation/den0077/latest/ +.. [3] **Arm TPM Service Command Response Buffer Interface Over FF-A** + https://developer.arm.com/documentation/den0138/latest/ +.. [4] **TCG ACPI Specification** + https://trustedcomputinggroup.org/resource/tcg-acpi-specification/ diff --git a/Documentation/security/tpm/tpm_tis.rst b/Documentation/security/tpm/tpm_tis.rst new file mode 100644 index 000000000000..b9637f295638 --- /dev/null +++ b/Documentation/security/tpm/tpm_tis.rst @@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= +TPM FIFO interface driver +========================= + +TCG PTP Specification defines two interface types: FIFO and CRB. The former is +based on sequenced read and write operations, and the latter is based on a +buffer containing the full command or response. + +FIFO (First-In-First-Out) interface is used by the tpm_tis_core dependent +drivers. Originally Linux had only a driver called tpm_tis, which covered +memory mapped (aka MMIO) interface but it was later on extended to cover other +physical interfaces supported by the TCG standard. + +For historical reasons above the original MMIO driver is called tpm_tis and the +framework for FIFO drivers is named as tpm_tis_core. The postfix "tis" in +tpm_tis comes from the TPM Interface Specification, which is the hardware +interface specification for TPM 1.x chips. + +Communication is based on a 20 KiB buffer shared by the TPM chip through a +hardware bus or memory map, depending on the physical wiring. The buffer is +further split into five equal-size 4 KiB buffers, which provide equivalent +sets of registers for communication between the CPU and TPM. These +communication endpoints are called localities in the TCG terminology. + +When the kernel wants to send commands to the TPM chip, it first reserves +locality 0 by setting the requestUse bit in the TPM_ACCESS register. The bit is +cleared by the chip when the access is granted. Once it completes its +communication, the kernel writes the TPM_ACCESS.activeLocality bit. This +informs the chip that the locality has been relinquished. + +Pending localities are served in order by the chip in descending order, one at +a time: + +- Locality 0 has the lowest priority. +- Locality 5 has the highest priority. + +Further information on the purpose and meaning of the localities can be found +in section 3.2 of the TCG PC Client Platform TPM Profile Specification. + +References +========== + +TCG PC Client Platform TPM Profile (PTP) Specification +https://trustedcomputinggroup.org/resource/pc-client-platform-tpm-profile-ptp-specification/ diff --git a/Documentation/security/tpm/xen-tpmfront.rst b/Documentation/security/tpm/xen-tpmfront.rst index 00d5b1db227d..31c67522f2ad 100644 --- a/Documentation/security/tpm/xen-tpmfront.rst +++ b/Documentation/security/tpm/xen-tpmfront.rst @@ -1,4 +1,4 @@ -============================= +============================= Virtual TPM interface for Xen ============================= |