| Message ID | 20230710102319.19716-3-greg@enjellic.com (mailing list archive) |
|---|---|
| State | Changes Requested |
| Delegated to: | Paul Moore |
| Headers | show |
| Series | Implement Trusted Security Event Modeling. | expand |
Hi-- On 7/10/23 03:23, Dr. Greg wrote: > diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt > index 9e5bab29685f..0e6640a78936 100644 > --- a/Documentation/admin-guide/kernel-parameters.txt > +++ b/Documentation/admin-guide/kernel-parameters.txt > @@ -6468,6 +6468,24 @@ > with CPUID.16h support and partial CPUID.15h support. > Format: <unsigned int> > These 3 entries should be in alphabetical order: tsem_cache, tsem_digest, tsem_mode. > + tsem_mode= [TSEM] Set the mode that the Trusted Security Event > + Modeling LSM is to run in. > + Format: 1 > + 1 -- Disable root domain modeling. > + > + tsem_cache= [TSEM] Define the size of the caches used to hold > + pointers to structures that will be used to model > + security events occurring in the root modeling > + namespace that are called in atomic context. > + Format: <integer> > + Default: 96 What unit? KB, MB, bytes, pages? > + > + tsem_digest= [TSEM] Define the cryptographic hash function that > + will be used to create security event coefficients > + for in the root modeling namespace. for in ? > + Format: {name of the cryptographic hash function} > + Default: sha256
On Mon, Jul 10, 2023 at 09:37:10PM -0700, Randy Dunlap wrote: > Hi-- Good morning, I hope the week is starting well for everyone. > On 7/10/23 03:23, Dr. Greg wrote: > > diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt > > index 9e5bab29685f..0e6640a78936 100644 > > --- a/Documentation/admin-guide/kernel-parameters.txt > > +++ b/Documentation/admin-guide/kernel-parameters.txt > > @@ -6468,6 +6468,24 @@ > > with CPUID.16h support and partial CPUID.15h support. > > Format: <unsigned int> > > > These 3 entries should be in alphabetical order: tsem_cache, > tsem_digest, tsem_mode. Now alphabetized. > > + tsem_mode= [TSEM] Set the mode that the Trusted Security Event > > + Modeling LSM is to run in. > > + Format: 1 > > + 1 -- Disable root domain modeling. > > + > > + tsem_cache= [TSEM] Define the size of the caches used to hold > > + pointers to structures that will be used to model > > + security events occurring in the root modeling > > + namespace that are called in atomic context. > > + Format: <integer> > > + Default: 96 > What unit? KB, MB, bytes, pages? Our apologies, we obviously erred in the notion that referring to the size of a cache of pointers would be understood to mean the number of pointers. We updated the documentation as follows: tsem_cache= [TSEM] Define the size of the caches used to hold pointers to structures that will be used to model security events occurring in the root modeling namespace that are called in atomic context. The value is the size of the arrays of pointers to the pre-allocated structures that will be maintained. For example, a value of 16 means each array would have 16 entries in it. Format: <integer> Default: 96 > > + > > + tsem_digest= [TSEM] Define the cryptographic hash function that > > + will be used to create security event coefficients > > + for in the root modeling namespace. > for in > ? That must have been an untoward effect of the single-malt. The documentation has been updated to read as follows: tsem_digest= [TSEM] Define the cryptographic hash function that will be used to generate the security event coefficients in the root modeling namespace. Format: {name of the cryptographic hash function} Default: sha256 > > + Format: {name of the cryptographic hash function} > > + Default: sha256 > > -- > ~Randy Thank you for the review comments. Have a good week. As always, Dr. Greg The Quixote Project - Flailing at the Travails of Cybersecurity
On 7/16/23 17:36, Dr. Greg wrote: > On Mon, Jul 10, 2023 at 09:37:10PM -0700, Randy Dunlap wrote: > >> Hi-- > > Good morning, I hope the week is starting well for everyone. > > > That must have been an untoward effect of the single-malt. > Mine are more often from double or triple or imperial IPA. :) > The documentation has been updated to read as follows: > Thanks for the updates. They look good.
On Mon, Jul 10, 2023 at 05:23:08AM -0500, Dr. Greg wrote: > An entry was added to the ABI testing documentation to document "Add an entry..." is the usual way to document this in commit msg. > the files in the TSEM management filesystem. > > The file documenting the kernel command-line parameters was > updated to document the TSEM specific command-line parameters A commit's actions are more normally in present tens ("The file documenting the kernel command-line parameters is") > The primary TSEM documentation file was added to the LSM > administration guide and the file was linked to the index of LSM > documentation. > > Signed-off-by: Greg Wettstein <greg@enjellic.com> > --- > Documentation/ABI/testing/tsem | 828 +++++++++ > Documentation/admin-guide/LSM/index.rst | 1 + > Documentation/admin-guide/LSM/tsem.rst | 1526 +++++++++++++++++ > .../admin-guide/kernel-parameters.txt | 18 + > 4 files changed, 2373 insertions(+) > create mode 100644 Documentation/ABI/testing/tsem > create mode 100644 Documentation/admin-guide/LSM/tsem.rst > > diff --git a/Documentation/ABI/testing/tsem b/Documentation/ABI/testing/tsem > new file mode 100644 > index 000000000000..cfb013b5f1f4 > --- /dev/null > +++ b/Documentation/ABI/testing/tsem > @@ -0,0 +1,828 @@ > +What: /sys/kernel/security/tsem > +Date: July 2023 > +Contact: Greg Wettstein <greg@enjellic.com> > +Description: > + The /sys/kernel/security/tsem directory contains files > + and directories that implement the control plane for > + the Trusted Security Event Modeling (TSEM) LSM. > + > + The files in this directory hierarchy, with the > + exception of the aggregate file, when read, reflect > + the values for the security modeling namespace that > + the process reading the files is operating in. > + > +What: /sys/kernel/security/tsem/id > +Date: July 2023 > +Contact: Greg Wettstein <greg@enjellic.com> > +Description: > + The id file contains the ASCII base 10 representation Why not use base 16 here? Mixing bases amongst the files could get confusing. > + of the model domain/namespace identifier that the > + reading process is operating in. > + > + The root security modeling namespace has a value of > + zero, a non-zero value indicates a modeling namespace > + subordinate to the root model. > + > + Each externally modeled domain will have a file, with > + this id number, created in the > + /sys/kernel/security/tsem/ExternalTMA directory that > + is documented below. > + > +What: /sys/kernel/security/tsem/aggregate > +Date: July 2023 > +Contact: Greg Wettstein <greg@enjellic.com> > +Description: > + The aggregate file contains the ASCII base 16 > + representation of the 256 bit hardware platform > + aggregate that TSEM is modeling under. The platform > + aggregate is the linear extension measurement of the > + Trusted Platform Module PCR registers 0 through 8. > + > + On a platform without a TPM this value will be all > + null bytes. > + > +What: /sys/kernel/security/tsem/control > +Date: July 2023 > +Contact: Greg Wettstein <greg@enjellic.com> > +Description: > + The control file is the only writable file in the > + filesystem and is used by the trust orchestrator's to > + configure and control the behavior of the TSEM > + implementation. > + > + The following keyword and arguments are recognized: > + > + internal > + The internal keyword causes an internally > + modeled domain to be created for the calling > + process. > + > + external > + The external keyword causes an externally > + modeled domain to be created for the calling > + process. > + > + A modeling namespace created by these commands > + accept the following set of key=value pairs > + that configure the namespace: > + > + nsref=initial|current > + The nsref key specifies the namespace > + that is to be referenced when > + determining the UID/GID values that > + define a COE or CELL identity. > + > + The initial keyword specifies that the > + initial user namespace be used. The > + current keyword specifies that the > + user namespace of the process that is > + invoking a security event handler > + (hook) is used. Hm, does this allow a process in a container to escape the container's policy, by creating a new domain inheriting from the initial userns? > +TSEM implements its equivalent of mandatory access controls, without a > +requirement for extended attributes, filesystem labeling or the need > +to protect filesystem metadata against offline attack. A mathematical If the security policy is that no data from /dev/tty, because it is untrusted, may flow into high integrity files, then how do you track the files which are high integrity, without labeling high integrity files? You're intending for the agent to track the files using inode number and fsid? > +The root security model extends each security state coefficient into a > +PCR. The default PCR is 11 but is configurable through the kernel Note pcr 11 will conflict with systemd's usage https://uapi-group.org/specifications/specs/linux_tpm_pcr_registry/ > +It is up to the trust orchestrator and its security policy to > +determine how it handles events that violate the security model being > +enforced. The Quixote trust orchestrators shut down the entire > +workload running in the security namespace if an asynchronously > +modeled event violates the security model being enforced and the model > +is running in enforcing mode. So instead of returning EPERM, you'll let the process speculatively continue until quixote has a chance to catch up and return a "no not allowed" message, after which the whole workload will be killed? > +From a hardware perspective, this is important with respect to the > +notion of a TMA being a model for a successor to the TPM. From a > +system trust or integrity perspective, a TPM is designed to provide a > +retrospective assessment of the actions that have occurred on a > +platform. A verifying party uses the TPM event log and a PCR based > +summary measurement, to verify what actions have occurred on the host, > +in order to allow a determination of whether or not the platform > +should be 'trusted'. FWIW TPM EA policies also refuse access to secrets based on those and other data. It's not purely for retrospective assessment. But indeed TPM does not authorize actions as trusted. Not because it fails to do so but because it's not part of its design. > + > +In contrast, a TSEM/TMA based system enforces, on a real time basis, > +that a platform or workload remains in a trusted state. Security > +relevant actions cannot be conducted unless the TMA authorizes the > +actions as being trusted. > + > +This is particularly important with respect to embedded systems. A > +TPM based architecture would not prevent a system from having its > +trust status altered. Maintaining the system in a trusted state would > +require attestation polling of the system, and presumably, executing > +actions if the platform has engaged in untrusted behavior. > + > +Conversely, a trust orchestrated software implementation enforces that > +a system or workload remain in a security/trust state that it's > +security model was unit tested to. To be convinced that there is *any* use case for this in the real world, you'd need to show me how any useful rule, like your above /etc/shadow set, could actually indicate a less trustworthy state in a robust way, without turning into an easy accidental-self-DOS. I'm afraid the answer is going to be "AI"... > +Security model functional definitions > +------------------------------------- > + > +Previously, classic trusted system implementations supported the > +notion of the 'measurement' of the system. The measurement is the > +value of a linear extension function of all the security relevant > +actions recorded by a trust measurement system such as IMA. > + > +In TPM based trust architectures, this measurement is maintained in a > +PCR. A measurement value is submitted to the TPM that extends the > +current measurement using the following formula: > + > +MEASUREMENT = HASH(CURRENT || NEW) > + > + Where: > + MEASUREMENT = The new measurement value to be maintained > + in the register for the system. > + > + || = Concatenation operator. > + > + HASH = A cryptographic hash function supported > + by the TPM device. > + > + CURRENT = The current measurement value. > + > + NEW = A new measurement value to be added to > + the current measurement. > + > +In TPM1 based systems, the HASH function was SHA1. Due to well > +understood security concerns about the cryptographic vitality of this > +function, TPM2 based systems provide additional HASH functions with > +stronger integrity guarantees, most principally SHA related functions > +with longer digest values such as SHA256, SHA384 and SM3. This previous paragraph simply is not needed in this document. > +The use of a cryptographic function produces a non-commutative sum > +that can be used to verify the integrity of a series of measurements. > +With respect to security modeling theory, this can be thought of as a > +'time-dependent' measurement of the system. Stated more simply, the > +measurement value is sensitive to the order in which the measurements > +were made. > + > +In systems such as IMA, the measurement value reflects the sum of > +digest values of what are considered to be security critical entities, > +most principally, files that are accessed, based on various policies. > + > +In TSEM based TMA's, the measurement of a modeling namespace is the > +sum of the security state coefficients generated by the operative > +security model being enforced. As previously noted, on systems with a > +TPM, the root modeling namespace measurement is maintained by default > +in PCR 11 or the PCR that was selected at kernel configuration time. > + > +The challenge associated with classic integrity measurements is the > +time dependent nature of using a non-commutative summing function. > +The almost universal embrace of SMP based hardware architectures, in > +addition to standard kernel task scheduling issues, makes the > +measurement values non-deterministic. This requires a verifying party > +to evaluate an event log, verified by a measurement value, to > +determine whether or not the system is in a security appropriate > +state. > + > +TSEM addresses this issue by implementing a strategy designed to > +produce a single functional value that represents the security state You've spent a lot of space discussing the "time based" (I think "order dependent" might be better) nature of IMA and TPM measurements. But after reading this section twice, I'm still not seeing what TMA does to work around it. If a process normally reads files F1, F2, .. F10, then writes F11, but next time it reads F1, F3, F2, F4, .. F10, how will these two different vectors be used in TMA? > +of a model. This allows a TMA to attest to the trust/security status > +of a platform or workload by signing this singular value and > +presenting it to a verifying party. > + > +In TSEM nomenclature, this singular value is referred to as the > +'state' of the model. The attestation model is to use trust > +orchestrators to generate the state value of a workload by unit > +testing. This state value can be packaged with a utility or container > +to represent a summary trust characteristic that can be attested by a > +TMA, eliminating the need for a verifying partner to review and verify > +an event log. > + > +TMA's implement this architecture by maintaining a single instance > +vector of the set of security state coefficients that have been > +generated. A state measurement is generated by sorting the vector in > +big-endian hash format and then generating a standard measurement > +digest over this new vector. Are you saying the TMA will keep every meaningful measurement for the duration of the workload, so that it can always sort them? > +Any security event that generates an associated state coefficient that > +is not in the model will resulted in a perturbed state function value. > +That perturbed value would be interpreted by a verifying party as an > +indication of an untrusted system. > + > +Since the TMA maintains the security event descriptions in time > +ordered form, the option to provide a classic event log and > +measurement are preserved and available. Extensive experience in the > +development of TSEM modeled systems has demonstrated the superiority > +of state value interpretation over classic measurement schemes. I think you're saying that keeping the tens of thousands security relevant events instead of keeping a hash of those events gives you more information... which is true. It also gives you more information. In a presumably limited space and over a presumably limited link. No performance impact? I'd really like to see what a conscise but useful policy looks like. -serge
On Tue, Aug 08, 2023 at 01:48:25PM -0500, Serge Hallyn wrote: Good afternoon Serge, thank you for the comments. > On Mon, Jul 10, 2023 at 05:23:08AM -0500, Dr. Greg wrote: > > An entry was added to the ABI testing documentation to document > "Add an entry..." is the usual way to document this in commit msg. Will modify the commit message when there is a need for it to reappear. > > the files in the TSEM management filesystem. > > > > The file documenting the kernel command-line parameters was > > updated to document the TSEM specific command-line parameters > A commit's actions are more normally in present tens ("The file > documenting the kernel command-line parameters is") Will also correct the diction used here. > > The primary TSEM documentation file was added to the LSM > > administration guide and the file was linked to the index of LSM > > documentation. > > > > Signed-off-by: Greg Wettstein <greg@enjellic.com> > > --- > > Documentation/ABI/testing/tsem | 828 +++++++++ > > Documentation/admin-guide/LSM/index.rst | 1 + > > Documentation/admin-guide/LSM/tsem.rst | 1526 +++++++++++++++++ > > .../admin-guide/kernel-parameters.txt | 18 + > > 4 files changed, 2373 insertions(+) > > create mode 100644 Documentation/ABI/testing/tsem > > create mode 100644 Documentation/admin-guide/LSM/tsem.rst > > > > diff --git a/Documentation/ABI/testing/tsem b/Documentation/ABI/testing/tsem > > new file mode 100644 > > index 000000000000..cfb013b5f1f4 > > --- /dev/null > > +++ b/Documentation/ABI/testing/tsem > > @@ -0,0 +1,828 @@ > > +What: /sys/kernel/security/tsem > > +Date: July 2023 > > +Contact: Greg Wettstein <greg@enjellic.com> > > +Description: > > + The /sys/kernel/security/tsem directory contains files > > + and directories that implement the control plane for > > + the Trusted Security Event Modeling (TSEM) LSM. > > + > > + The files in this directory hierarchy, with the > > + exception of the aggregate file, when read, reflect > > + the values for the security modeling namespace that > > + the process reading the files is operating in. > > + > > +What: /sys/kernel/security/tsem/id > > +Date: July 2023 > > +Contact: Greg Wettstein <greg@enjellic.com> > > +Description: > > + The id file contains the ASCII base 10 representation > Why not use base 16 here? Mixing bases amongst the files could get > confusing. No reason not to, the primary entities reading the file are external trust orchestrators. We will prefix it with 0x to make it easy for strtol running in '0' mode. > > + of the model domain/namespace identifier that the > > + reading process is operating in. > > + > > + The root security modeling namespace has a value of > > + zero, a non-zero value indicates a modeling namespace > > + subordinate to the root model. > > + > > + Each externally modeled domain will have a file, with > > + this id number, created in the > > + /sys/kernel/security/tsem/ExternalTMA directory that > > + is documented below. > > + > > +What: /sys/kernel/security/tsem/aggregate > > +Date: July 2023 > > +Contact: Greg Wettstein <greg@enjellic.com> > > +Description: > > + The aggregate file contains the ASCII base 16 > > + representation of the 256 bit hardware platform > > + aggregate that TSEM is modeling under. The platform > > + aggregate is the linear extension measurement of the > > + Trusted Platform Module PCR registers 0 through 8. > > + > > + On a platform without a TPM this value will be all > > + null bytes. > > + > > +What: /sys/kernel/security/tsem/control > > +Date: July 2023 > > +Contact: Greg Wettstein <greg@enjellic.com> > > +Description: > > + The control file is the only writable file in the > > + filesystem and is used by the trust orchestrator's to > > + configure and control the behavior of the TSEM > > + implementation. > > + > > + The following keyword and arguments are recognized: > > + > > + internal > > + The internal keyword causes an internally > > + modeled domain to be created for the calling > > + process. > > + > > + external > > + The external keyword causes an externally > > + modeled domain to be created for the calling > > + process. > > + > > + A modeling namespace created by these commands > > + accept the following set of key=value pairs > > + that configure the namespace: > > + > > + nsref=initial|current > > + The nsref key specifies the namespace > > + that is to be referenced when > > + determining the UID/GID values that > > + define a COE or CELL identity. > > + > > + The initial keyword specifies that the > > + initial user namespace be used. The > > + current keyword specifies that the > > + user namespace of the process that is > > + invoking a security event handler > > + (hook) is used. > Hm, does this allow a process in a container to escape the > container's policy, by creating a new domain inheriting from the > initial userns? First, to seek some clarification. When you write 'container policy', are you referring to a TSEM security model or a uid/gid userns mapping or other OCI container security policy? Casey had commented, in an unrelated thread, that 'domain' is over-used, so we have standardized on 'security modeling namespace'. I see above that we missed a case where we used domain in the document, so we will fix that and assume that by 'creating a new domain' you mean a new security modeling namespace. FWIW, for TSEM, we have standardized on 'security model' rather than policy for similar reasons. Security modeling namespaces are, by design, only one level deep. The trust orchestrators drop CAP_WHATEVER after setting up a modeling namespace, this locks the workload into whatever security model was specified for the security modeling namespace with no opportunity for the workload to change model context. > > +TSEM implements its equivalent of mandatory access controls, without a > > +requirement for extended attributes, filesystem labeling or the need > > +to protect filesystem metadata against offline attack. A mathematical > If the security policy is that no data from /dev/tty, because it is > untrusted, may flow into high integrity files, then how do you track > the files which are high integrity, without labeling high integrity > files? You're intending for the agent to track the files using > inode number and fsid? The CELL identity generative function for a file access encodes the pathname to the file. Access to the file will need to be through a security event that generates a security state coefficient that derives from a CELL identity referencing the file. Moving forward, we will be adding support to include security labels from extended attributes in the CELL identity generation function, in order to allow security policies that are not dependent on pathnames. Further, the generative function for the security state coefficient includes the concept of a 'task id' that serves to restrict information flow only through a specific corpus of executable code that is anchored by a cryptographic digest of said code. > > +The root security model extends each security state coefficient into a > > +PCR. The default PCR is 11 but is configurable through the kernel > Note pcr 11 will conflict with systemd's usage > > https://uapi-group.org/specifications/specs/linux_tpm_pcr_registry/ Thank you for providing the reference, we will choose the next available PCR according to that document. > > +It is up to the trust orchestrator and its security policy to > > +determine how it handles events that violate the security model being > > +enforced. The Quixote trust orchestrators shut down the entire > > +workload running in the security namespace if an asynchronously > > +modeled event violates the security model being enforced and the model > > +is running in enforcing mode. > So instead of returning EPERM, you'll let the process speculatively > continue until quixote has a chance to catch up and return a "no not > allowed" message, after which the whole workload will be killed? For an externally modeled namespace, that is currently the only option available. The trust orchestrator also has the ability to set the task trust status to untrusted, if the process still exists, which would block any subsequent attempts to invoke security sensitive operations. We've received a fair amount of feedback, that even if the workload doesn't get killed, people feel that it is useful to quickly find out, with a high degree of precision, that a workload is in the process of getting p0wned. The latency to action time isn't a function of quixote 'catching up', but rather a function of how long the TMA takes to run the security coefficient generative function and determine the provenance of the event in the context of the operative security model. That varies with the TMA implementation, with the stock userspace implementation taking in the range of 400-700 micro-seconds. The only way to fix this is to implement a completion callback LSM hook that can be invoked after the initial LSM hook was called from atomic context and asynchronously submits the security event characteristics to the TMA. We have patches for internal use to do this, but hopefully from an understandable perspective, no appetite for submitting something like that. This limitation isn't inconsistent with how security is getting done in the wild with agent based systems. An example from what we have the most experience and visibility into. CrowdStrike's NGAV product advertises the use of 'Cloud based artificial intelligence, behavioral detection and machine learning algorithms for threat detection and exploit mitigation'. I think it can be stated, with a reasonably high degree of confidence, that all of that doesn't typically occur within ~500 micro-seconds after an event occurs that is inconsistent with the desired security state of a workload/platform. Finally, if any delay in response is unacceptable, TSEM offers the ability to run the TMA implementation in the kernel where it would not suffer from this limitation. > > +From a hardware perspective, this is important with respect to the > > +notion of a TMA being a model for a successor to the TPM. From a > > +system trust or integrity perspective, a TPM is designed to provide a > > +retrospective assessment of the actions that have occurred on a > > +platform. A verifying party uses the TPM event log and a PCR based > > +summary measurement, to verify what actions have occurred on the host, > > +in order to allow a determination of whether or not the platform > > +should be 'trusted'. > FWIW TPM EA policies also refuse access to secrets based on those > and other data. It's not purely for retrospective assessment. But > indeed TPM does not authorize actions as trusted. Not because it > fails to do so but because it's not part of its design. No argument there and no criticism of TPM's at large implied by any of what we are proposing. Technology has changed significantly in the 23+ years since TPM's were introduced and we believe that the concept of a TMA, regardless of where it is implemented, introduces the possibility of a more useful superset of TPM type security capabilities. > > +In contrast, a TSEM/TMA based system enforces, on a real time basis, > > +that a platform or workload remains in a trusted state. Security > > +relevant actions cannot be conducted unless the TMA authorizes the > > +actions as being trusted. > > + > > +This is particularly important with respect to embedded systems. A > > +TPM based architecture would not prevent a system from having its > > +trust status altered. Maintaining the system in a trusted state would > > +require attestation polling of the system, and presumably, executing > > +actions if the platform has engaged in untrusted behavior. > > + > > +Conversely, a trust orchestrated software implementation enforces that > > +a system or workload remain in a security/trust state that it's > > +security model was unit tested to. > To be convinced that there is *any* use case for this in the real > world, you'd need to show me how any useful rule, like your above > /etc/shadow set, could actually indicate a less trustworthy state in > a robust way, without turning into an easy accidental-self-DOS. TSEM in its essence embraces 'default deny, exception allow'; the same concept that every firewall on the planet implements. With the exception of all the vendors that are now rapidly claiming to do 'AI' on deep packet inspection. A TSEM security model is the set of coefficients that represent, at a very granular level, the allowed security states of a workload. In an enforcing model, only these actions are allowed. Our trust predicate is that if the workload has not allowed a security behavior inconsistent with its desired security model, it can be considered trusted. Tasks that depart from the model are considered untrusted and get EPERM'ed. It is unclear where the 'accidental-self-denial-of-service' issue would arise, since the only events that would get denied are those that should not be occurring. We would certainly entertain an elaboration on this issue so we could better understand any possible deficiencies in what we are proposing. > I'm afraid the answer is going to be "AI"... No, not if we understand correctly the issue you raise. That being said, we do feel that TSEM opens the door to implementing the most accurate 'AI' models possible, for environments where deterministic or quasi-deterministic security modeling is infeasible. We certainly do understand antipathy with respect to AI, but it seems that it is going to be a fact of life in the security industry and beyond for a significant period of time. I even see that Cisco is doubling down from its 'Talos AI-driven Threat Intelligence' with the June announcement of its 'AI-First Security Cloud'.... :-) We are trying to give Linux the best method, of any OS, to implement security modeling, regardless of its type. > > +Security model functional definitions > > +------------------------------------- > > + > > +Previously, classic trusted system implementations supported the > > +notion of the 'measurement' of the system. The measurement is the > > +value of a linear extension function of all the security relevant > > +actions recorded by a trust measurement system such as IMA. > > + > > +In TPM based trust architectures, this measurement is maintained in a > > +PCR. A measurement value is submitted to the TPM that extends the > > +current measurement using the following formula: > > + > > +MEASUREMENT = HASH(CURRENT || NEW) > > + > > + Where: > > + MEASUREMENT = The new measurement value to be maintained > > + in the register for the system. > > + > > + || = Concatenation operator. > > + > > + HASH = A cryptographic hash function supported > > + by the TPM device. > > + > > + CURRENT = The current measurement value. > > + > > + NEW = A new measurement value to be added to > > + the current measurement. > > + > > +In TPM1 based systems, the HASH function was SHA1. Due to well > > +understood security concerns about the cryptographic vitality of this > > +function, TPM2 based systems provide additional HASH functions with > > +stronger integrity guarantees, most principally SHA related functions > > +with longer digest values such as SHA256, SHA384 and SM3. > This previous paragraph simply is not needed in this document. Yes, not sure how that persisted through internal review, we will drop it. > > +The use of a cryptographic function produces a non-commutative sum > > +that can be used to verify the integrity of a series of measurements. > > +With respect to security modeling theory, this can be thought of as a > > +'time-dependent' measurement of the system. Stated more simply, the > > +measurement value is sensitive to the order in which the measurements > > +were made. > > + > > +In systems such as IMA, the measurement value reflects the sum of > > +digest values of what are considered to be security critical entities, > > +most principally, files that are accessed, based on various policies. > > + > > +In TSEM based TMA's, the measurement of a modeling namespace is the > > +sum of the security state coefficients generated by the operative > > +security model being enforced. As previously noted, on systems with a > > +TPM, the root modeling namespace measurement is maintained by default > > +in PCR 11 or the PCR that was selected at kernel configuration time. > > + > > +The challenge associated with classic integrity measurements is the > > +time dependent nature of using a non-commutative summing function. > > +The almost universal embrace of SMP based hardware architectures, in > > +addition to standard kernel task scheduling issues, makes the > > +measurement values non-deterministic. This requires a verifying party > > +to evaluate an event log, verified by a measurement value, to > > +determine whether or not the system is in a security appropriate > > +state. > > + > > +TSEM addresses this issue by implementing a strategy designed to > > +produce a single functional value that represents the security state > You've spent a lot of space discussing the "time based" (I think > "order dependent" might be better) nature of IMA and TPM > measurements. But after reading this section twice, I'm still not > seeing what TMA does to work around it. Time dependent vs. time independent models tends to be a lingua franca in modeling theory. We will see if we can work some prose in that relates this to ordering. > If a process normally reads files F1, F2, .. F10, then writes F11, > but next time it reads F1, F3, F2, F4, .. F10, how will these two > different vectors be used in TMA? I believe this is discussed below and we will treat it further there. > > +of a model. This allows a TMA to attest to the trust/security status > > +of a platform or workload by signing this singular value and > > +presenting it to a verifying party. > > + > > +In TSEM nomenclature, this singular value is referred to as the > > +'state' of the model. The attestation model is to use trust > > +orchestrators to generate the state value of a workload by unit > > +testing. This state value can be packaged with a utility or container > > +to represent a summary trust characteristic that can be attested by a > > +TMA, eliminating the need for a verifying partner to review and verify > > +an event log. > > + > > +TMA's implement this architecture by maintaining a single instance > > +vector of the set of security state coefficients that have been > > +generated. A state measurement is generated by sorting the vector in > > +big-endian hash format and then generating a standard measurement > > +digest over this new vector. > Are you saying the TMA will keep every meaningful measurement for > the duration of the workload, so that it can always sort them? Correct, every unique security state coefficient. The approach isn't unique and without precedent. Roberto Sassu is using a similar strategy in order generate a time/order independent PCR value for unlocking TPM sealed keys by parsing RPM and .deb distribution manifests. Paul Moore, in his comments in February to the V1 series, even seriously questioned why we would expose the classic linear extension measurement from a TMA. > > +Any security event that generates an associated state coefficient that > > +is not in the model will resulted in a perturbed state function value. > > +That perturbed value would be interpreted by a verifying party as an > > +indication of an untrusted system. > > + > > +Since the TMA maintains the security event descriptions in time > > +ordered form, the option to provide a classic event log and > > +measurement are preserved and available. Extensive experience in the > > +development of TSEM modeled systems has demonstrated the superiority > > +of state value interpretation over classic measurement schemes. > I think you're saying that keeping the tens of thousands security > relevant events instead of keeping a hash of those events gives you > more information... which is true. It also gives you more > information. In a presumably limited space and over a presumably > limited link. No performance impact? Obviously everything we do with respect to security has an impact, as always, it comes down to a cost/benefit analysis. We would offer the following observations: The use of a security modeling namespace reduces the number of coefficients that need to be stored. Any serious initiative involving modeling, deterministic or ML, will demand the notion of the concept of a 'namespace'. Only unique coefficients are stored. There is a surprising amount of redundancy in security state coefficients that are generated by a workload, to wit: The boot of a basic Debian implementation to a shell prompt will generate approximately 7,800 unique coefficients from a field of 57,800 events. Executing a runc based workload, up to the point where you can do something with a shell, yields 98 coefficients from a field of 478. As will likely be the case with TPM's moving forward, it seems unlikely that the future will consist of TMA's being discrete hardware devices. As we note in our documentation, the Quixote/TSEM userspace tools demonstrate the viability of a number of different physical modeling environments. Quixote/TSEM may actually be the 'killer' application for SGX but it seemed we were unable to communicate that effectively. All of that being said. If you download the source for the userspace tools, it will build firmware for a TMA implementation that will run on the Nordic NRF52840-DONGLE micro-controller (USB form factor and comms, 32 bit ARM, 256K RAM), think Yubikey class and style device that GOOGLE is using for its OpenSK initiative. We use it to model a runc based workload consisting of a Java Log4J2 exploit demonstration. Getting Java cranked up doesn't exactly blow your hair back but the Tomcat application is surprisingly responsive after that. Finally, in order to support modeling of the root namespace anchored by a TPM trust root we needed to implement asynchronous TPM updates. Until we did that, boot performance on systems with discrete TPM's was brutally slow, which underscores that classic TPM based trust models are challenged when it comes to anchoring model based security architectures. > I'd really like to see what a conscise but useful policy looks like. Given the above, what in your mind would be a 'useful' policy? > -serge Thanks for the comments. Have a good weekend. As always, Dr. Greg The Quixote Project - Flailing at the Travails of Cybersecurity
On Jul 10, 2023 "Dr. Greg" <greg@enjellic.com> wrote: > > An entry was added to the ABI testing documentation to document > the files in the TSEM management filesystem. > > The file documenting the kernel command-line parameters was > updated to document the TSEM specific command-line parameters > > The primary TSEM documentation file was added to the LSM > administration guide and the file was linked to the index of LSM > documentation. > > Signed-off-by: Greg Wettstein <greg@enjellic.com> > --- > Documentation/ABI/testing/tsem | 828 +++++++++ > Documentation/admin-guide/LSM/index.rst | 1 + > Documentation/admin-guide/LSM/tsem.rst | 1526 +++++++++++++++++ > .../admin-guide/kernel-parameters.txt | 18 + > 4 files changed, 2373 insertions(+) > create mode 100644 Documentation/ABI/testing/tsem > create mode 100644 Documentation/admin-guide/LSM/tsem.rst Let me start by apologizing for the delay in responding, your patience was appreciated. Comments below ... > diff --git a/Documentation/ABI/testing/tsem b/Documentation/ABI/testing/tsem > new file mode 100644 > index 000000000000..cfb013b5f1f4 > --- /dev/null > +++ b/Documentation/ABI/testing/tsem > @@ -0,0 +1,828 @@ > +What: /sys/kernel/security/tsem > +Date: July 2023 > +Contact: Greg Wettstein <greg@enjellic.com> > +Description: > + The /sys/kernel/security/tsem directory contains files > + and directories that implement the control plane for > + the Trusted Security Event Modeling (TSEM) LSM. > + > + The files in this directory hierarchy, with the > + exception of the aggregate file, when read, reflect > + the values for the security modeling namespace that > + the process reading the files is operating in. > + > +What: /sys/kernel/security/tsem/id > +Date: July 2023 > +Contact: Greg Wettstein <greg@enjellic.com> > +Description: > + The id file contains the ASCII base 10 representation > + of the model domain/namespace identifier that the > + reading process is operating in. > + > + The root security modeling namespace has a value of > + zero, a non-zero value indicates a modeling namespace > + subordinate to the root model. > + > + Each externally modeled domain will have a file, with > + this id number, created in the > + /sys/kernel/security/tsem/ExternalTMA directory that > + is documented below. Just making sure you want to use uppercase here. It's your call, but it tends to go against convention, and changing it after the code is in a tagged release it painful enough that it should be considered practically impossible. This applies not just to this file, but all of the other mixed/upper case TSEM files under /sys. > +What: /sys/kernel/security/tsem/aggregate > +Date: July 2023 > +Contact: Greg Wettstein <greg@enjellic.com> > +Description: > + The aggregate file contains the ASCII base 16 > + representation of the 256 bit hardware platform > + aggregate that TSEM is modeling under. The platform > + aggregate is the linear extension measurement of the > + Trusted Platform Module PCR registers 0 through 8. I believe we talked about hash agility previously, but just in case, you may want to reword the above to provide some flexibility around the hash algorithm used. On the other hand, if you want to stick with a single hash algorithm and 256-bit digest length, you might as well specify the hash algorithm here. I don't want to assume too much about the TSEM design, but I'm guessing the aggregate is intended to be a deterministic value based on the PCRs and therefore it seems like there is value in providing a clear explanation of how it is calculated. > + On a platform without a TPM this value will be all > + null bytes. Just to clarify, are you intending this to be NULL bytes (as written) or an ASCII base 16 zero value, padded out to the digest length, similar as to what you might see in the output of the `tpm2_pcrread` command for a zero-value PCR? Once again, it's your call, I just wanted to clarify. > +What: /sys/kernel/security/tsem/control > +Date: July 2023 > +Contact: Greg Wettstein <greg@enjellic.com> > +Description: > + The control file is the only writable file in the > + filesystem and is used by the trust orchestrator's to > + configure and control the behavior of the TSEM > + implementation. I would drop the "only writable file ..." portion above; it may be the only writable file under /sys/kernel/security/tsem at the moment, but I imagine there is a good chance that will change over time and the comment doesn't really add anything important. > + The following keyword and arguments are recognized: > + > + internal > + The internal keyword causes an internally > + modeled domain to be created for the calling > + process. > + > + external > + The external keyword causes an externally > + modeled domain to be created for the calling > + process. > + > + A modeling namespace created by these commands > + accept the following set of key=value pairs > + that configure the namespace: I assume whitespace is used as a delimiter? That would be good to document, both between the key-value-pairs as well as the initial op/keyword. Also, do these key-value-pairs apply to both internal and external domains? The text seems to indicate that they do, but the way the document is structured hints that they only apply to the external domain. Perhaps a sentence in the internal domain description indicating that all of the external domain configuration parameters apply to internal domains as well, unless explicitly stated otherwise. > + nsref=initial|current > + The nsref key specifies the namespace > + that is to be referenced when > + determining the UID/GID values that > + define a COE or CELL identity. Are COE or CELL acronyms? If so, it would be nice to expand them on first use in the document. > + The initial keyword specifies that the > + initial user namespace be used. The > + current keyword specifies that the > + user namespace of the process that is > + invoking a security event handler > + (hook) is used. > + > + digest=digestname > + The digest key is used to specify the > + cryptographic hash function that is to > + be used in the namespace for the > + creation of COE and CELL identities. > + > + The digestname is the name used by the > + Linux kernel cryptographic API to > + identify the hash function. Examples > + would include sha256, sha3-256, sm3 > + etc. The source files for the > + cryptographic hash function in the crypto > + directory of the kernel source has the > + names for hash functions implemented > + in the kernel. > + > + The sha256 hash function is the > + default function for the root modeling > + domain. This can be modified by the > + tsem_digest command-line parameter. > + > + A hash function, used by the root > + modeling domain, must be built into > + the kernel. > + > + cache=NN > + The cache key specifies the size of > + the caches to be used for holding > + pointers to structures used for the > + modeling or export of security events > + that are called while the invoking > + process is in atomic context. > + > + The value NN is the ASCII base 10 > + representation of the number of > + entries in the cache. > + > + By default, the root modeling > + namespace and an externally modeled > + namespace will have 96 entries. An > + internally modeled namespace will have > + 16 entries. > + > + key=HEXID > + The key argument is used to specify > + the authentication key that will be > + used by a trust orchestrator to > + authenticate trust control requests to > + a process running in the security > + modeling namespace. > + > + The HEXID value is the ASCII base16 > + encoded key that is to be used. The > + length of this key, in binary, must be > + equal to the size of the digest > + produced by the cryptographic hash > + function that is being used in the > + modeling namespace. > + > + enforce > + The enforce keyword causes the modeling > + domain/namespace of the process to enter > + enforcing mode. In this mode, a value of > + -EPERM will be returned for a security event > + coefficient that does not map into the current > + set of allowed coefficients for the security > + model being implemented in the namespace. > + > + seal > + The seal keyword causes the security model > + being implemented for the namespace to be > + placed in a sealed state. In this state, the > + current set of security coefficients is > + considered to be the only set of valid > + coefficients for the model. Any subsequent > + events that map to a coefficient not in the > + current model will be considered a violation > + of the model. > + > + trusted pid=PID key=HEXID > + The trusted keyword is used by a trust > + orchestrator to indicate that the process > + identified by the PID argument should be > + allowed to run in trusted status after the > + modeling of a security event. I mentioned this quite a few times in my review of the previous patchset, PIDs are not a safe way to identify a process in the system. PID reuse/recycling is a real danger and you need to account for this risk. > + The HEXID argument is the authentication key > + that has been configured by a trust > + orchestrator for the namespace at the time of > + its creation. > + > + untrusted pid=PID key=HEXID > + The untrusted keyword is used by a trust > + orchestrator to indicate that the process > + identified by the PID argument should be > + designated as an untrusted process. See above, you can't use a PID to safely identify a process. > + The HEXID argument is the authentication key > + that has been configured by a trust > + orchestrator for the namespace at the time > + its creation. > + > + state value=HEXID > + The state keyword is used to indicate that the > + security state coefficient identified by the > + ASCII base 16 encoded value specified by HEXID > + should be loaded into the current security > + model as a valid security event coefficient. > + > + pseudonym valid=HEXID > + The pseudonym keyword is used to indicate that > + the pathname, identified by the ASCII base 16 > + encoded value HEXID, should be designated to > + return a constant digest value for the > + contents of the file named by the pseudonym. > + > + The HEXID value is computed with the following > + function: > + > + HEXID = HF(PATHNAME_LENGTH || PATHNAME) > + > + WHERE HF is the cryptographic hash function > + that has been designated for use by the > + security modeling namespace. How do you handle hash collisions? Given that users will likely be able to create files with arbitrary names, it seems like identifying files by a hash of their pathname without any way to safely resolve digest collisions is a problem in waiting. > + base value=HEXID > + The base keyword is used to indicate that the > + ASCII base 16 encoded value HEXID should be > + registered as the value used to generate > + security state coefficients for the model > + implemented in the modeling namespace. > + > + The binary length of the value specified by > + HEXID must match the digest size of the > + cryptographic hash function specified for use > + in the security modeling namespace. > + > + A model specific base value is designed to be > + used as a 'freshness' nonce, similar to an > + attestation nonce, to prove that a model state > + value or measurement is current and not being > + replayed. > + > +What: /sys/kernel/security/tsem/InternalTMA > +Date: July 2023 > +Contact: Greg Wettstein <greg@enjellic.com> > +Description: > + > + This directory will contain directories that will be > + used to hold files that surface model parameters for > + Trusted Modeling Agents (TMA's) for internally modeled > + security namespaces. > + > + There is currently only one internal TMA that is > + surfaced through the following directory: > + > + /sys/kernel/security/tsem/InternalTMA/model0 > + > + The subsequent descriptions for the files implemented > + in this directory will use ROOTDIR to represent the > + above directory for space conservation purposes. > + > +What: ROOTDIR/measurement > +Date: July 2023 > +Contact: Greg Wettstein <greg@enjellic.com> > +Description: > + The measurement file contains the ASCII base 16 > + representation of the time dependent linear extension > + value of all the security state coefficients in the > + model implemented by the namespace of the calling > + process. If I remember correctly, one of the motivations for TSEM was to avoid the time/ordering aspect of traditional attestation approaches as it can be fragile. Assuming that my memory is correct, and this still holds true in the revision of the patchset, why are you continuing to export time/order dependent measurements to userspace? Either the ordering is important, in which case TSEM's novelty isn't useful, or the ordering isn't important and we can remove this sysfs file. > +What: ROOTDIR/state > +Date: July 2023 > +Contact: Greg Wettstein <greg@enjellic.com> > +Description: > + The state file contains the ASCII base 16 > + representation of the functional value of a security > + modeling namespace. > + > + The state value is a time independent representation > + of the measurement of a security model, and unlike the > + measurement value, is a time independent > + representation of the state. > + > + This value is designed to be a single value that can > + be attested to represent whether or not a workload has > + deviated from a defined security behavior. Continuing the comment above regarding ROOTDIR/measurement, this file makes much more sense in the context of TSEM. > +What: ROOTDIR/trajectory > +Date: July 2023 > +Contact: Greg Wettstein <greg@enjellic.com> > +Description: > + The trajectory file contains a description of the > + security events that have occurred in a security > + modeling namespace > + > + Each entry in this file represents a single security > + event and consists of a JSON encoded record with key > + values that define the characteristics of the event. > + > + Each line in a trajectory, or forensics, file will > + always have the event and COE keys. The event key > + describes the characteristics of a security event > + while the COE field describes the Context Of Execution > + that is requesting execution of a security event. > + > + The event key consists of the following > + characteristic definitions: > + > + process: COMM > + Where COMM is the ASCII representation > + of the name of the process executing > + the event. What happens if a process, either innocently or maliciously, changes its name (see prctl(PR_SET_NAME))? Would it result in a mismatch of the security state of a process? > + type: EVENT_TYPE > + The value field for a type key is the > + name of the security event that is > + being modeled. The list of EVENT_TYPE > + names is defined in the following > + source file: > + > + security/tsem/tsem.c > + > + If the security event is a generically > + modeled event the EVENT_TYPE will be > + generic_event. In this case the CELL > + characteristics for the event will be > + described by a generic_event: key I'm guessing EVENT_TYPE is an ASCII string representation? It would be good to clarify as you have in most (all?) of the other fields and the omission here raises a red flag. > + task_id: HEXID > + The value of the task_id key will the > + ASCII base 16 representation of the > + identity of the task that is executing > + the security handler. The length of > + HEXID will match the size of the > + digest value of the cryptographic hash > + function selected for use by the > + security modeling namespace. > + > + The following documentation file: > + > + Documentation/admin-guide/LSM/TSEM.rst It looks like the file is lowercase ".../tsem.rst". > + Describes how the TASK_ID value is > + generated. I would suggest either moving or copying the TASK_ID definition here so that it is included in the TSEM ABI document. > + The COE key has the following characteristic keys. > + Keys that involve discretionary access values > + (uids/gids) will have their numeric value computed > + based on the user namespace reference value that is > + being implemented in the security modeling namespace. > + > + uid: NN > + The ASCII base 10 representation of > + the numeric value of the discretionary > + user id of the process that is > + executing the security event. > + > + euid: NN > + The ASCII base 10 representation of > + the numeric value of the effective > + discretionary user id of the process > + that is executing the security event. > + > + euid: NN > + The ASCII base 10 representation of > + the numeric value of the effective > + discretionary user id of the process > + that is executing the security event. > + > + suid: NN > + The ASCII base 10 representation of > + the numeric value of the saved user id > + of the process that is executing the > + security event. > + > + gid: NN > + The ASCII base 10 representation of > + the numeric value of the discretionary > + group id of the process that is > + executing the security event. > + > + egid: NN > + The ASCII base 10 representation of > + the numeric value of the discretionary > + effective group id of the process that > + is executing the security event. > + > + egid: NN > + The ASCII base 10 representation of > + the numeric value of the discretionary > + effective group id of the process that > + is executing the security event. > + > + sgid: NN > + The base 10 ASCII representation of > + the numeric value of the saved > + discretionary group id of the process > + that is executing the security event. > + > + fsuid: NN > + The base 10 ASCII representation of > + the numeric value of the discretionary > + filesystem user id of the process that > + is executing the security event. > + > + fsgid: NN > + The ASCII base 10 representation of > + the numeric value of the discretionary > + filesystem group id of the process > + that is executing the security event. > + > + capeff: 0xNNN > + The ASCII base 16 representation of > + the numeric value of effective > + capabilities of the process that is > + executing the security event. > + > + If the CELL value for a security event includes the > + definition of a file a file: key value will be > + included. The following characteristics will be > + encoded in this field: > + > + flags: NN > + The ASCII base 10 representation of > + the flags value of the 'struct file' > + structure that is the source of the > + file description. > + > + uid: NN > + The ASCII base 10 representation of > + the discretionary user id of the file. > + > + gid: NN > + The base 10 ASCII representation of > + the discretionary group id of the > + file. > + > + mode: 0NNN > + The ASCII base 8 representation of the > + mode bits of the file. Does the leading zero followed by three octets imply you don't record the setuid/setgid/sticky bits? > + name_length: NN > + The ASCII base 10 representation of > + the length of the pathname that will > + be encoded in the name= characteristic. To clarify, this is the length of the pathname used during the file lookup and not the length of the hash digest of the previously mentioned pathname, yes? > + name: NN > + The ASCII hexadecimal representation > + of the SHA256 checksum of the pathname > + of the file that is pre-pended with > + the little-endian binary value of the > + length of the pathname. Hash agility? It isn't clear to me if the length is prepended before or after the hash, it would be good to clean this up. Also, similar to some comments above, how are you handling hash collisions? As pathnames can be influenced by unprivileged users, this would appear to be an issue. > + s_magic: 0xNN > + The ASCII base 16 representation of the > + magic number of the filesystem that > + contains the file. > + > + s_id: NAME > + The ASCII name of the block device for > + the filesystem that contains the file. > + > + s_UUID: HEX > + The ASCII base 16 representation of > + the hexadecimal value of the UUID of > + the filesystem that contains the file. > + > + digest: HEX > + The ASCII base 16 representation of > + the SHA256 digest of the file. Hash agility? Is TSEM running a hash over every file included in a file-related security event? > + If the event type is the memory mapping of a file a > + mmap_file key value will be included with > + the following characteristics: Still part of the CELL? COE? This doc could benefit from better explanations of the CELL and COE terms. > + type: N > + Where N is an ASCII 0 or 1 to indicate > + whether or not the mapping is file > + backed or anonymous. A value of 1 is > + used to indicate an anonymous mapping. > + > + reqprot: NN > + Where N is ASCII base 10 > + representation of the protections > + requested for the mapping. > + > + prot: NN > + Where N is the ASCII base 10 > + representation of the protections that > + will be applied to the mapping. > + > + flags: NN > + Where N is the ASCII base 10 > + representation of the flags that will > + be used for the memory mapping operation. You should specify the flags used in the fields above, or refer readers to the mmap(2) flag definitions if appropriate. > + If the event type is a socket creation event a > + socket_create key value will be included with the > + following characteristics: > + > + family: N > + Where N is the ASCII base 10 > + representation of the family type of > + the socket. > + > + type: N > + Where N is the ASCII base 10 > + representation of the type of socket > + being created. > + > + protocol: N > + Where N is the ASCII base 10 > + representation of the protocol family > + for the socket. Similar to the mmap flags above, I would refer people to where these values are defined. The applies to the other socket family/type/proto fields described elsewhere in this document. > + kern: 0 | 1 > + Where 0 or 1 is used to indicate > + whether or not the socket is kernel > + based. A value of 1 implies it is > + kernel based. I'm curious how TSEM would distinguish between different kernel socket events. I would expect most kernel sockets to share the same event key (COE/CELL/etc.), is that not the case? > + If the event type is a socket_connect or a > + socket_bind, a socket_connect: or a socket_bind: key > + value will be included that will be characterized > + based on an encoding of either an IPV4, IPV6, AF_UNIX > + or a generic socket description. > + > + family: N > + Where N is the ASCII base 10 > + representation of the family type of > + the socket. > + > + port: N > + Where N is the base ASCII base 10 > + representation of the port number that > + is being used for either an IPV4 or > + IPV6 socket connection or bind. > + > + addr: N | PATH | HEXID > + In the case of an IPV4 socket the > + value for the addr key will be the > + ASCII base 10 representation of the 32 > + bit IPV4 address being bound or > + connected to. > + > + In the case of an IPV6 connection the > + value to the key will be the ASCII > + base 16 representation of the 128 bit > + address being bound connected. > + > + In the case of an AF_UNIX connection > + the value will be the pathname of the > + socket in the mount namespace that the > + process is running in. > + > + In the case of any other type of > + socket the addr value will be the > + ASCII base 16 representation of the > + cryptographic digest value of the > + entire length of the address > + description. The length of the > + representation will be the size of the > + digest produced by the cryptographic > + hash function that has been specified > + for the modeling namespace. > + > + flow: N > + For an IPV6 socket the value of the > + flow key will be the ASCII base 10 > + representation of the flow identifier > + assigned to the socket. > + > + scope: N > + For an IPV6 socket the value of the > + scope key will be the ASCII base 10 > + representation of the scope identifier > + assigned to the socket. What will "flow" and "scope" be for non-AF_INET6 sockets? You need to specify that here. > + If the event type is a socket_accept a socket_accept > + key value will be included that characterizes either > + an IPV4, IPV6 or a generic socket description with the > + following event descriptions: > + > + family: N > + Where N is the ASCII base 10 > + representation of the family type of > + the socket. > + > + type: N > + Where N is the ASCII base 10 > + representation of the type of the > + socket being created. > + > + port: N > + Where N is the base ASCII base 10 > + representation of the port number that > + is being used for either an IPV4 or > + IPV6 socket connection or bind. > + > + addr: N | PATH | HEXID > + In the case of an IPV4 socket the > + value for the addr key will be the > + ASCII base 10 representation of the 32 > + bit IPV4 address being bound or > + connected to. > + > + In the case of an IPV6 connection the > + value to the key will be the ASCII > + base 16 representation of the 128 bit > + address being bound connected. > + > + In the case of an AF_UNIX connection > + the value will be the pathname of the > + socket in the mount namespace that the > + process is running in. > + > + In the case of any other type of > + socket the addr value will be the > + ASCII base 16 representation of the > + cryptographic digest value of the > + entire length of the address > + description. The length of the > + representation will be the size of the > + digest produced by the cryptographic > + hash function that has been specified > + for the modeling namespace. > + > +What: ROOTDIR/trajectory_coefficients > +Date: July 2023 > +Contact: Greg Wettstein <greg@enjellic.com> > +Description: > + The trajectory_coefficients file will output the ASCII > + base16 representation of each security state > + coefficient that has been generated by the security > + modeling namespace of the calling process. > + > + The length of each point will be the ASCII > + representation of the size of the cryptographic hash > + function that has been specified for the model. Is this just the ROOTDIR/trajectory JSON in ASCII hex, or something different? > +What: ROOTDIR/trajectory_counts > +Date: July 2023 > +Contact: Greg Wettstein <greg@enjellic.com> > +Description: > + The trajectory_coefficients file will output the ASCII > + base10 representation of the number of times each Unless I'm mistaken, I believe you defined it as base16 above ... ? > + security state coefficient has been generated by the > + security modeling namespace of the calling process. This looks like an old cut-n-paste error. I'm guessing this file reports on the number of coefficients in ASCII base10? > +What: ROOTDIR/forensics > +Date: July 2023 > +Contact: Greg Wettstein <greg@enjellic.com> > +Description: > + The forensics file contains the descriptions of > + security events that are inconsistent with the > + security model that the security namespace is > + implementing. Forensics events are generated after a > + security model is 'sealed' and the events represent > + security state coefficients that have not already been > + generated by the model. > + > + The format of lines in this file are identical to the > + output generated by the ROOTDIR/trajectory file > + that is documented above. > + > +What: ROOTDIR/forensics_coefficients > +Date: July 2023 > +Contact: Greg Wettstein <greg@enjellic.com> > +Description: > + The forensics_coefficients file will output the ASCII > + base16 representation of each security state > + coefficient that have been generated by forensics > + events in the security modeling namespace of the > + calling process. > + > + The length of each point will be the ASCII > + representation of the size of the cryptographic hash > + function that has been specified for the model. > + > +What: ROOTDIR/forensics_counts > +Date: July 2023 > +Contact: Greg Wettstein <greg@enjellic.com> > +Description: > + The forensics_counts file will output the ASCII base10 > + representation of the number of times each security > + state coefficient, generated by a forensics event, has > + been generated by the security modeling namespace of > + the calling process. > + > +What: /sys/kernel/security/tsem/ExternalTMA > +Date: July 2023 > +Contact: Greg Wettstein <greg@enjellic.com> > +Description: > + The ExternalTMA directory is a container directory > + that hold files that will be used to export the > + security events, and their associated parameters, for > + externally modeled security modeling namespaces. > + > + The files created in this directory will be named by > + the base 10 ASCII representation of the id value > + assigned to the security modeling namespace. See the > + documentation for the /sys/kernel/security/tsem/id > + file in this documentation for more details on this > + value. > + > + This file will is a read-only file that can be polled > + by a userspace trust orchestrator implementation to > + process security events that are to be modeled by an > + external Trusted Modeling Agent. > + > + Each exported event is a JSON encoded record > + describing the event that is to be processed. > + > + Each record will have an 'export' key that has a > + structure associated with it that has a 'type' key in > + it. The 'type' key has a string value associated with > + it that defines the type of event that is being > + processed. > + > + The following export 'type' strings are defined: > + > + aggregate: > + The aggregate key has an associated structure > + value that defines a key named 'value' that > + has a string value associated with it that > + represents the hardware aggregate for the > + platform. You need to define "hardware aggregate" here, if you can't go into detail you need a good summary outlining its security relevant properties. > + The hardware aggregate string is expressed as > + the ASCII base16 representation of the > + platform hardware aggregate value. The length > + of the string will be the size of the digest > + produced by the cryptographic hash function > + that has been specified for the security > + modeling namespace of the process generating > + the event. > + > + async_event: > + If the type of the export is async_event there > + will be a key named 'event' that has a structure > + value associated with it. > + > + The structure associated with the 'event' key > + will be identical to the structure generated > + for the 'event' key that is described below. > + > + event: > + If the type of the export is event there will > + be a key named 'event' that has a structure > + value associated with it that contains the > + follow key: value pairs. > + > + pid: NNN > + Where the NNN is the ASCII base 10 > + value of the id of the process that is > + executing the security event that will > + be modeled. Once more, you can't use a PID to safely identify a process. We discussed the PID reuse problem in the previous draft of TSEM and you seem confident that this revision would solve the problem, unfortunately I don't believe that to be the case. Perhaps the code is sound and the documentation is lagging/incorrect, but the doc appears to be consistent enough in this area that I don't believe that to be the case. Before I can spend any more time looking at TSEM I need to understand how it handles PID recycling. I'm also concerned that it appears pathname digests, as opposed to the pathnames themselves, are being used to help uniquely identify security events. Relying on pathnames unique identification can already be a challenge, relying on a hashed pathname without any provisions to manage/mitigate collisions seems like an attack waiting to happen. Please provide some additional explanations as to why this is not a concern. > + process: COMM > + Where COMM is the ASCII representation > + of the name of the process executing > + the event. > + > + type: EVENT_TYPE > + The value field for a type key is the > + name of the security event that is > + being modeled. The list of EVENT_TYPE > + names is defined in the following > + source file: > + > + security/tsem/tsem.c > + > + If the security event is a generically > + modeled event the EVENT_TYPE will be > + generic_event. In this case the CELL > + characteristics for the event will be > + described by a generic_event: key > + > + task_id: HEXID > + The value of the task_id key will the > + ASCII base 16 representation of the > + identity of the task that is executing > + the security handler. The length of > + HEXID will match the size of the > + digest value of the cryptographic hash > + function selected for use by the > + security modeling namespace. > + > + The following documentation file: > + > + Documentation/admin-guide/LSM/TSEM.rst > + > + Describes how the TASK_ID value is > + generated. > + > + There will be a COE key that references a > + value structure that has the same format as > + the COE key that is emitted for a trajectory > + or forensics event. > + > + The record will have a key value that is > + identical to the value associated with the > + 'type' key documented above. The 'type' key > + will have a structure value that contains a > + definition of the event. The definitions for > + the event will be identical to the description > + of the event that is emitted for a trajectory > + or forensics event in the internal TMA > + implementation. > + > + log: > + An export type of log is emitted when an > + untrusted task attempts to execute a security > + event. > + > + There will be a 'log' key in the record that > + references a structure containing the > + following key values: > + > + process: COMM > + The process key has a string value > + associated with it that will contain > + the COMM name of the untrusted process > + that invoked processing of the > + security event. > + > + event: NAME > + The event key has a string value > + associated with that will contain the > + name of the security event hook that > + was called by an untrusted process. > + > + The names for the security events are > + defined in the following source file: > + > + security/tsem/tsem.c > + > + action: TYPE > + The action key has a string value that > + describes the action take by the TSEM > + security hook in response to being > + called by an untrusted process. > + > + This string value will be either LOG > + or DENY. > +SEM is premised on the theory that kernel security architects have > +instrumented the LSM security event hooks to be called from all > +locations, with appropriate descriptive parameters, that are relevant > +to the security posture of the kernel. With respect to modeling, the > +security event hooks are conceptualized as representing the > +independent variables of a basis set that yields a functional > +definition for the security state of an execution trajectory. > + > +SEM can be framed in the context of classic subject/object mandatory > +access controls, by the notion that a unique identity can be generated > +for each element of an access vector matrix, rather than a boolean > +value. In SEM, a security execution trajectory is defined by the set > +of security state coefficients that a process hierarchy (workload) > +generates. This execution trajectory produces a vector of identities, > +whose sum in an appropriate form, yields a functional definition of > +the security state of the system. > + > +Two subordinate identities are combined to yield a security event > +state coefficient. These subordinate identities are referred to as the > +Context Of Execution (COE) and the CELL, which are conceptually > +similar to the subject and object in mandatory access control. The > +COE identity is derived from the parameters that describe the security > +relevant characteristics of a process, while the CELL value is derived > +from the parameters used by a security event hook to describe the > +characteristics of the event. > + > +A security policy is implemented by a modeling algorithm that > +translates COE and CELL event parameters into their respective > +identities. The COE and CELL are combined to yield a security state > +coefficient that uniquely describes the security event in the security > +model. Different security policies and criteria can be developed by > +modifying how the modeling algorithm utilizes the COE and CELL > +characteristics. > + > +Since the security policy is implemented with a modeling algorithm, a > +single platform can support multiple and arbitrary security policies. > +The equivalent of a resource namespace in SEM is referred to as a > +security modeling namespace. > + > +The formation of the security state coefficients from existing kernel > +parameters eliminates the need for the use of extended attributes to > +hold security label definitions. In SEM, a cryptographically signed > +security model definition, designed to be interpreted by a modeling > +algorithm, becomes the bearer's token for the security of the modeled > +workload, rather than information encoded in filesystem security > +attributes. > + > +Trusted Security Event Modeling > +=============================== > + > + "Do you see over yonder, friend Sancho, thirty or forty > + hulking giants? I intend to do battle with them and slay > + them." > + - Don Quixote > + > +In TSEM, the modeling algorithm is implemented in an entity known as a > +Trusted Modeling Agent (TMA), in a 'trusted' environment where > +modeling is immune from modification or alteration by any activity on > +the platform or in a workload. The notion of a TMA provides a > +framework for next generation security co-processors that extend > +functionality beyond what is defined by the concept of a Trusted > +Platform Module (TPM). > + > +In addition to providing an attestation of an execution trajectory, a > +TMA, in contrast to a TPM, has the ability to advise an operating > +system on whether or not an event being modeled is consistent with the > +security model that is being enforced. In this manner, it introduces > +a prospective rather than a retrospective trust model. > + > +TSEM is designed to support Trust Orchestration Systems (TOS). In a > +TOS, the trust orchestrators are supervisory programs that run > +workloads in independent modeling namespaces , enforcing a workload {snip} -- paul-moore.com
On Fri, Aug 11, 2023 at 4:24 PM Dr. Greg <greg@enjellic.com> wrote: > On Tue, Aug 08, 2023 at 01:48:25PM -0500, Serge Hallyn wrote: > > On Mon, Jul 10, 2023 at 05:23:08AM -0500, Dr. Greg wrote: ... > > > +of a model. This allows a TMA to attest to the trust/security status > > > +of a platform or workload by signing this singular value and > > > +presenting it to a verifying party. > > > + > > > +In TSEM nomenclature, this singular value is referred to as the > > > +'state' of the model. The attestation model is to use trust > > > +orchestrators to generate the state value of a workload by unit > > > +testing. This state value can be packaged with a utility or container > > > +to represent a summary trust characteristic that can be attested by a > > > +TMA, eliminating the need for a verifying partner to review and verify > > > +an event log. > > > + > > > +TMA's implement this architecture by maintaining a single instance > > > +vector of the set of security state coefficients that have been > > > +generated. A state measurement is generated by sorting the vector in > > > +big-endian hash format and then generating a standard measurement > > > +digest over this new vector. > > > Are you saying the TMA will keep every meaningful measurement for > > the duration of the workload, so that it can always sort them? > > Correct, every unique security state coefficient. > > The approach isn't unique and without precedent. Roberto Sassu is > using a similar strategy in order generate a time/order independent > PCR value for unlocking TPM sealed keys by parsing RPM and .deb > distribution manifests. > > Paul Moore, in his comments in February to the V1 series, even > seriously questioned why we would expose the classic linear extension > measurement from a TMA. To put my comment from the first revision into the proper context, and with my understanding that TSEM's security model does not consider event ordering/timing, I questioned what TSEM would expose an ordered list of events to userspace in addition to its unordered, sorted list. Either ordering is important to the security model, in which case you expose the ordered list, or it isn't, in which case you expose the list in whatever form is most convenient for the tooling/model; it makes little sense to me to expose both.
On Wed, Jan 03, 2024 at 11:00:33PM -0500, Paul Moore wrote: Good morning, I hope the year is starting well for everyone. > On Jul 10, 2023 "Dr. Greg" <greg@enjellic.com> wrote: > > > > An entry was added to the ABI testing documentation to document > > the files in the TSEM management filesystem. > > > > The file documenting the kernel command-line parameters was > > updated to document the TSEM specific command-line parameters > > > > The primary TSEM documentation file was added to the LSM > > administration guide and the file was linked to the index of LSM > > documentation. > > > > Signed-off-by: Greg Wettstein <greg@enjellic.com> > > --- > > Documentation/ABI/testing/tsem | 828 +++++++++ > > Documentation/admin-guide/LSM/index.rst | 1 + > > Documentation/admin-guide/LSM/tsem.rst | 1526 +++++++++++++++++ > > .../admin-guide/kernel-parameters.txt | 18 + > > 4 files changed, 2373 insertions(+) > > create mode 100644 Documentation/ABI/testing/tsem > > create mode 100644 Documentation/admin-guide/LSM/tsem.rst > Let me start by apologizing for the delay in responding, your > patience was appreciated. Comments below ... No problem, you were sounding pretty jammed up before the holidays, thank you for starting to find the time to look at this. That being said, we have continued to advance TSEM over the last six months based on input from our partners. With the New Year behind us, we were preparing for a V3 release sometime in mid-January if we can stay on schedule. Given that, and the value of your review time, you may want to hold off on a more extensive review until we can get V3 out the door. We have taken down all of your comments below and will incorporate changes and improvement where still relevant. You voiced two major concerns at the end of your e-mail that you wanted clarified before you spent additional time on TSEM, I will skip forward to those so we can reach a better understanding on those fundamental issues. > > diff --git a/Documentation/ABI/testing/tsem b/Documentation/ABI/testing/tsem > > new file mode 100644 > > index 000000000000..cfb013b5f1f4 ... [ Content elided ] ... > > + event: > > + If the type of the export is event there will > > + be a key named 'event' that has a structure > > + value associated with it that contains the > > + follow key: value pairs. > > + > > + pid: NNN > > + Where the NNN is the ASCII base 10 > > + value of the id of the process that is > > + executing the security event that will > > + be modeled. > Once more, you can't use a PID to safely identify a process. Correct, which is why we changed our approach. > We discussed the PID reuse problem in the previous draft of TSEM and > you seem confident that this revision would solve the problem, > unfortunately I don't believe that to be the case. Perhaps the code > is sound and the documentation is lagging/incorrect, but the doc > appears to be consistent enough in this area that I don't believe > that to be the case. Before I can spend any more time looking at > TSEM I need to understand how it handles PID recycling. We cover the threat model and addressed how we responded to it in the TSEM documentation file. We will put a header at the top of the ABI document advocating that the TSEM documentation file be read before the ABI document is consumed. We use the PID infrastructure to locate the process that is waiting on a response from an external trust orchestrator. After that the kernel uses an authentication process to verify that the task being acted on has not been replaced by an alternate task outside the scope of control of the orchestrator for the namespace. In Documentation/admin-guide/LSM/tsem.rst, the discussion is under the following sub-heading: Trust Orchestrator/Process authentication ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Since it is an important issue, I will take the liberty of pasting this documentation section in-line below, so that people don't have to go digging for it and it becomes part of this documentation thread on lore: --------------------------------------------------------------------------- The process identifier values (PID's) that are exported in the security event descriptions are the unique global PID values, not the value as seen through the lens of a PID namespace. PID values are, by default, not considered to be a stable identifier between the kernel and userspace. In the case of TSEM external modeling, the threat model for a namespace is whether or not an adversarial process, running in either the root modeling namespace or another subordinate modeling namespace, can kill a process that is being orchestrated and substitute an alternate process with an identical PID value. The trust orchestrator would then be deluded into setting the trust status of the adversarial process rather than the one that had emitted the security event characteristics that were evaluated. The threat interval is the latency time required for the processing of the security event description by the trust orchestrator and its associated TMA. Exploiting this theoretical race is extremely complex and requires an in depth understanding of the TSEM architecture. Rather than discuss the conditions that must be met and their implications, this discussion will focus on the generic threat model and the mechanisms that TSEM implements in order to mitigate this threat. In short, a process in an adversarial security modeling namespace would desire to execute security events that are barred from its security model with the hope of having them approved by an alternate namespace. In order to exploit the race, an adversarial process would have to force the termination of a process in the target namespace and then fork and exit a process a sufficient number of times in order to have a process under its control match the PID value of the process that was waiting for an orchestration response. Measured modeling latency times for a trust orchestrator running the deterministic Quixote TMA in userspace, on current generation i3 x86_64 hardware, averages 170 micro-seconds. From the perspective of an adversary, there is a requirement to force the termination of the target process and then fork and execute a sufficient number of times to force the PID collision during this time interval. As a generic protection, TSEM in the tsem_task_kill() handler, blocks the notion of 'cross-model' signals, ie. a signal originating from an external modeling namespace. This would require the adversary to reliably force a process termination through a mechanism other than signaling, for example, through the OOM killer whose signal transmission would not be blocked by this policy control. In addition. When a subordinate security modeling namespace is created, the id number of the namespace is registered in the tsem_task structure of the trust orchestrator that is creating the namespace. The TSEM implementation will refuse to honor control plane requests affecting the trust status of a process whose trust orchestrator security namespace id does not match the namespace id of the process that it is being asked to act on. As an additional protection, TSEM uses an authentication strategy that requires a process running in a security modeling namespace to verify that a control request is coming from the trust orchestrator that initiated the namespace the process is running in. As part of the setup of a security modeling namespace, a trust orchestrator is required to provide a hexadecimally encoded authentication key that matches the length of the cryptographic hash function being used to generate security state coefficients in the modeling namespace. This authentication key must be provided by the trust orchestrator for every subsequent control plane request. The lead process that is being transferred to a subordinate security modeling namespace generates a second random key that is hashed with the authentication key provided by the trust orchestrator, using the hash function that has been defined for the security namespace. The resultant digest value is compared to a list of authentication keys for all currently executing namespaces. The selection of the second random key is repeated until a globally unique key is generated. This randomly generated authentication key is stored in the tsem_task structure of the process and propagated to any subsequent processes that are created in the namespace. The hash product of this key and the orchestration authentication key, ie. the globally unique key, is placed in the tsem_task control structure of the orchestration process. When a control plane request is received, the authentication key provided by the trust orchestrator is used to re-generate an authentication key based on the randomly generated namespace key held by the process whose trust status is being updated, this key is compared to the key in the tsem_task structure of the process issuing the orchestration request. The control plane will refuse to honor a control plane request if the call specific key generation process does not produce a key that matches the one that was generated at the time the security namespace was created. --------------------------------------------------------------------------- This implementation remains the same between the V2 and V3 releases. See the following code locations for details: security/tsem/namespace.c:tsem_ns_event_key() security/tsem/namespace.c:generate_task_key() security/tsem/namespace.c:remove_task_key() security/tsem/fs.c:control_COE() > I'm also concerned that it appears pathname digests, as opposed to > the pathnames themselves, are being used to help uniquely identify > security events. Relying on pathnames unique identification can > already be a challenge, relying on a hashed pathname without any > provisions to manage/mitigate collisions seems like an attack > waiting to happen. Please provide some additional explanations as > to why this is not a concern. The V3 release no longer uses the cryptographic digest of the pathname length and path as an independent entity. The V3 release also now includes a device name specification as a component of any pathname specification. That being said, the pathname identification is a component of the input stream that is fed to the namespace specific cryptographic digest function that generates the security state coefficient for an event. So it would seem that your criticism would extend to the very notion of the generation of security state coefficients. To be clear, without getting overtly wonky, TSEM is rather firmly ensconced on the following security predicate: "Given a digest value of an input stream generated by a cryptographically relevant hash function, it is computationally infeasible for an adversary to create a second input stream, different from the first, that generates the same digest value." Is it an error to have operated under this assumption in the construction of TSEM? We can grind into much deeper detail as to why TSEM would make this type of attack difficult, but obtaining agreement on the validity of the above predicate would seem to be the most important first step. > paul-moore.com Thank you again for finding time for this. Let us know if additional clarifications would be helpful. As always, Dr. Greg The Quixote Project - Flailing at the Travails of Cybersecurity https://github.com/Quixote-Project
On Thu, Jan 04, 2024 at 10:54:47AM -0500, Paul Moore wrote: > On Fri, Aug 11, 2023 at 4:24???PM Dr. Greg <greg@enjellic.com> wrote: > > On Tue, Aug 08, 2023 at 01:48:25PM -0500, Serge Hallyn wrote: > > > On Mon, Jul 10, 2023 at 05:23:08AM -0500, Dr. Greg wrote: > > ... > > > > > +of a model. This allows a TMA to attest to the trust/security status > > > > +of a platform or workload by signing this singular value and > > > > +presenting it to a verifying party. > > > > + > > > > +In TSEM nomenclature, this singular value is referred to as the > > > > +'state' of the model. The attestation model is to use trust > > > > +orchestrators to generate the state value of a workload by unit > > > > +testing. This state value can be packaged with a utility or container > > > > +to represent a summary trust characteristic that can be attested by a > > > > +TMA, eliminating the need for a verifying partner to review and verify > > > > +an event log. > > > > + > > > > +TMA's implement this architecture by maintaining a single instance > > > > +vector of the set of security state coefficients that have been > > > > +generated. A state measurement is generated by sorting the vector in > > > > +big-endian hash format and then generating a standard measurement > > > > +digest over this new vector. > > > > > Are you saying the TMA will keep every meaningful measurement for > > > the duration of the workload, so that it can always sort them? > > > > Correct, every unique security state coefficient. > > > > The approach isn't unique and without precedent. Roberto Sassu is > > using a similar strategy in order generate a time/order independent > > PCR value for unlocking TPM sealed keys by parsing RPM and .deb > > distribution manifests. > > > > Paul Moore, in his comments in February to the V1 series, even > > seriously questioned why we would expose the classic linear extension > > measurement from a TMA. > To put my comment from the first revision into the proper context, > and with my understanding that TSEM's security model does not > consider event ordering/timing, I questioned what TSEM would expose > ^^^^ why?? > an ordered list of events to userspace in addition to its unordered, > sorted list. > > Either ordering is important to the security model, in which case you > expose the ordered list, or it isn't, in which case you expose the > list in whatever form is most convenient for the tooling/model; it > makes little sense to me to expose both. As a generic clarification in furtherance of getting everyone on the same page with respect to the focus of our work. TSEM is about providing generic infrastructure for security modeling and anomaly detection that acts at the most precise level of security instrumentation that is available. Secondary to that pursuit, TSEM offers security architects the ability to choose from either a time dependent or a time independent appraisal of a security modeling namespace. The TSEM 'trajectory' file is always time ordered with respect to the first unique occurrence of a security event. In the V3 release, these trajectory entries include a nanosecond timestamp reference, relative to boot, of when the event occurred. The 'measurement' pseudo-file allows a relying party to verify that the trajectory list, as presented, is order/time consistent, if that is what they choose to evaluate. The 'state' pseudo-file allows a relying party to make a decision on whether or not the security status of the system is idempotent, from an event perspective, with a known reference state. It addresses, among other issues, the problem that IMA is currently facing with the fact that handling and examining unconstrained event logs can be problematic from a number of perspectives. Alternately, now in V3, a security model implementator can specify that a security event stream from a modeling namespace be asynchronously exported in its entirety and dealt with in whatever fashion an external evaluator desires. So TSEM doesn't implement or advocate a security model as much as it implements security infrastructure. > paul-moore.com Have a good weekend. As always, Dr. Greg The Quixote Project - Flailing at the Travails of Cybersecurity https://github.com/Quixote-Project
On Wed, Jan 03, 2024 at 11:00:33PM -0500, Paul Moore wrote: > On Jul 10, 2023 "Dr. Greg" <greg@enjellic.com> wrote: > > > > An entry was added to the ABI testing documentation to document > > the files in the TSEM management filesystem. > > > > The file documenting the kernel command-line parameters was > > updated to document the TSEM specific command-line parameters > > > > The primary TSEM documentation file was added to the LSM > > administration guide and the file was linked to the index of LSM > > documentation. > > > > Signed-off-by: Greg Wettstein <greg@enjellic.com> > > --- > > Documentation/ABI/testing/tsem | 828 +++++++++ > > Documentation/admin-guide/LSM/index.rst | 1 + > > Documentation/admin-guide/LSM/tsem.rst | 1526 +++++++++++++++++ > > .../admin-guide/kernel-parameters.txt | 18 + > > 4 files changed, 2373 insertions(+) > > create mode 100644 Documentation/ABI/testing/tsem > > create mode 100644 Documentation/admin-guide/LSM/tsem.rst > Let me start by apologizing for the delay in responding, your patience > was appreciated. Comments below ... In my previous reply I responded to what you considered to be your two major concerns. For clarification purposes I will follow up on the other issues you raised so we can potentially make adjustments in V3. > > diff --git a/Documentation/ABI/testing/tsem b/Documentation/ABI/testing/tsem > > new file mode 100644 > > index 000000000000..cfb013b5f1f4 > > --- /dev/null > > +++ b/Documentation/ABI/testing/tsem > > @@ -0,0 +1,828 @@ > > +What: /sys/kernel/security/tsem > > +Date: July 2023 > > +Contact: Greg Wettstein <greg@enjellic.com> > > +Description: > > + The /sys/kernel/security/tsem directory contains files > > + and directories that implement the control plane for > > + the Trusted Security Event Modeling (TSEM) LSM. > > + > > + The files in this directory hierarchy, with the > > + exception of the aggregate file, when read, reflect > > + the values for the security modeling namespace that > > + the process reading the files is operating in. > > + > > +What: /sys/kernel/security/tsem/id > > +Date: July 2023 > > +Contact: Greg Wettstein <greg@enjellic.com> > > +Description: > > + The id file contains the ASCII base 10 representation > > + of the model domain/namespace identifier that the > > + reading process is operating in. > > + > > + The root security modeling namespace has a value of > > + zero, a non-zero value indicates a modeling namespace > > + subordinate to the root model. > > + > > + Each externally modeled domain will have a file, with > > + this id number, created in the > > + /sys/kernel/security/tsem/ExternalTMA directory that > > + is documented below. > Just making sure you want to use uppercase here. It's your call, > but it tends to go against convention, and changing it after the > code is in a tagged release it painful enough that it should be > considered practically impossible. This applies not just to this > file, but all of the other mixed/upper case TSEM files under /sys. There are only two files with mixed case, we will convert them to the following: /sys/kernel/security/tsem/external_tma /sys/kernel/security/tsem/internal_tma Let us know if you disagree. > > +What: /sys/kernel/security/tsem/aggregate > > +Date: July 2023 > > +Contact: Greg Wettstein <greg@enjellic.com> > > +Description: > > + The aggregate file contains the ASCII base 16 > > + representation of the 256 bit hardware platform > > + aggregate that TSEM is modeling under. The platform > > + aggregate is the linear extension measurement of the > > + Trusted Platform Module PCR registers 0 through 8. > I believe we talked about hash agility previously, but just in case, > you may want to reword the above to provide some flexibility around > the hash algorithm used. On the other hand, if you want to stick > with a single hash algorithm and 256-bit digest length, you might as > well specify the hash algorithm here. TSEM should now have the maximum amount of hash agility available on Linux. From the V2 cover letter enhancements: - Allow cryptographic hash function used for coefficient generation to be configured on a namespace by namespace basis. Which may understate the issue a bit. TSEM can now use any hash function availble in Linux as the compression function for a security modeling namespace. Different namespaces can operate with different hash functions simultaneously. In V3 we will re-word all of the references to SHA256 to indicate that the output value will be the ASCII expression of the digest function specified for the modeling namespace. > I don't want to assume too much about the TSEM design, but I'm > guessing the aggregate is intended to be a deterministic value based > on the PCRs and therefore it seems like there is value in providing > a clear explanation of how it is calculated. The aggregate is the linear extension sum over PCR registers 0 through 8 using the namespace hash function, we will cook up a generic description, although it should be a common enough concept for anyone working on trusted system implementations. > > + On a platform without a TPM this value will be all > > + null bytes. > Just to clarify, are you intending this to be NULL bytes (as > written) or an ASCII base 16 zero value, padded out to the digest > length, similar as to what you might see in the output of the > `tpm2_pcrread` command for a zero-value PCR? Once again, it's your > call, I just wanted to clarify. It will be what would constitute the expression of least surprise, a sequence of ASCII 0's padded to the digest size, the same as a pcrread of a zero-value PCR. > > +What: /sys/kernel/security/tsem/control > > +Date: July 2023 > > +Contact: Greg Wettstein <greg@enjellic.com> > > +Description: > > + The control file is the only writable file in the > > + filesystem and is used by the trust orchestrator's to > > + configure and control the behavior of the TSEM > > + implementation. > I would drop the "only writable file ..." portion above; it may be the > only writable file under /sys/kernel/security/tsem at the moment, but > I imagine there is a good chance that will change over time and the > comment doesn't really add anything important. Will change. > > + The following keyword and arguments are recognized: > > + > > + internal > > + The internal keyword causes an internally > > + modeled domain to be created for the calling > > + process. > > + > > + external > > + The external keyword causes an externally > > + modeled domain to be created for the calling > > + process. > > + > > + A modeling namespace created by these commands > > + accept the following set of key=value pairs > > + that configure the namespace: > I assume whitespace is used as a delimiter? That would be good to > document, both between the key-value-pairs as well as the initial > op/keyword. Yes, arguments are white space delimited, we use argv_split for the parsing of all the control plane directives. > Also, do these key-value-pairs apply to both internal and external > domains? The text seems to indicate that they do, but the way the > document is structured hints that they only apply to the external > domain. Perhaps a sentence in the internal domain description > indicating that all of the external domain configuration parameters > apply to internal domains as well, unless explicitly stated > otherwise. We will take a look at making this more clear. > > + nsref=initial|current > > + The nsref key specifies the namespace > > + that is to be referenced when > > + determining the UID/GID values that > > + define a COE or CELL identity. > Are COE or CELL acronyms? If so, it would be nice to expand them on > first use in the document. COE is an acronym for Context Of Execution, in TSEM the security characteristics of what would be the equivalent of the subject in a MAC. CELL doesn't stand for anything other than CELL, it is a term to reflect the collection of characteristics that describe a security event being modeled, roughly the equivalent of an object in MAC. We use CELL in respect to Turing computability theory in that TSEM is based on the predicate that a unique identity can be generated for each security event that an execution 'head' passes over. The first contribution of wonkiness for today's e-mail... :-) > > + The initial keyword specifies that the > > + initial user namespace be used. The > > + current keyword specifies that the > > + user namespace of the process that is > > + invoking a security event handler > > + (hook) is used. > > + > > + digest=digestname > > + The digest key is used to specify the > > + cryptographic hash function that is to > > + be used in the namespace for the > > + creation of COE and CELL identities. > > + > > + The digestname is the name used by the > > + Linux kernel cryptographic API to > > + identify the hash function. Examples > > + would include sha256, sha3-256, sm3 > > + etc. The source files for the > > + cryptographic hash function in the crypto > > + directory of the kernel source has the > > + names for hash functions implemented > > + in the kernel. > > + > > + The sha256 hash function is the > > + default function for the root modeling > > + domain. This can be modified by the > > + tsem_digest command-line parameter. > > + > > + A hash function, used by the root > > + modeling domain, must be built into > > + the kernel. > > + > > + cache=NN > > + The cache key specifies the size of > > + the caches to be used for holding > > + pointers to structures used for the > > + modeling or export of security events > > + that are called while the invoking > > + process is in atomic context. > > + > > + The value NN is the ASCII base 10 > > + representation of the number of > > + entries in the cache. > > + > > + By default, the root modeling > > + namespace and an externally modeled > > + namespace will have 96 entries. An > > + internally modeled namespace will have > > + 16 entries. > > + > > + key=HEXID > > + The key argument is used to specify > > + the authentication key that will be > > + used by a trust orchestrator to > > + authenticate trust control requests to > > + a process running in the security > > + modeling namespace. > > + > > + The HEXID value is the ASCII base16 > > + encoded key that is to be used. The > > + length of this key, in binary, must be > > + equal to the size of the digest > > + produced by the cryptographic hash > > + function that is being used in the > > + modeling namespace. > > + > > + enforce > > + The enforce keyword causes the modeling > > + domain/namespace of the process to enter > > + enforcing mode. In this mode, a value of > > + -EPERM will be returned for a security event > > + coefficient that does not map into the current > > + set of allowed coefficients for the security > > + model being implemented in the namespace. > > + > > + seal > > + The seal keyword causes the security model > > + being implemented for the namespace to be > > + placed in a sealed state. In this state, the > > + current set of security coefficients is > > + considered to be the only set of valid > > + coefficients for the model. Any subsequent > > + events that map to a coefficient not in the > > + current model will be considered a violation > > + of the model. > > + > > + trusted pid=PID key=HEXID > > + The trusted keyword is used by a trust > > + orchestrator to indicate that the process > > + identified by the PID argument should be > > + allowed to run in trusted status after the > > + modeling of a security event. > I mentioned this quite a few times in my review of the previous > patchset, PIDs are not a safe way to identify a process in the > system. PID reuse/recycling is a real danger and you need to > account for this risk. We will defer that discussion to our previous e-mail where we discussed how this is addressed. > > + The HEXID argument is the authentication key > > + that has been configured by a trust > > + orchestrator for the namespace at the time of > > + its creation. > > + > > + untrusted pid=PID key=HEXID > > + The untrusted keyword is used by a trust > > + orchestrator to indicate that the process > > + identified by the PID argument should be > > + designated as an untrusted process. > > See above, you can't use a PID to safely identify a process. > > > + The HEXID argument is the authentication key > > + that has been configured by a trust > > + orchestrator for the namespace at the time > > + its creation. > > + > > + state value=HEXID > > + The state keyword is used to indicate that the > > + security state coefficient identified by the > > + ASCII base 16 encoded value specified by HEXID > > + should be loaded into the current security > > + model as a valid security event coefficient. > > + > > + pseudonym valid=HEXID > > + The pseudonym keyword is used to indicate that > > + the pathname, identified by the ASCII base 16 > > + encoded value HEXID, should be designated to > > + return a constant digest value for the > > + contents of the file named by the pseudonym. > > + > > + The HEXID value is computed with the following > > + function: > > + > > + HEXID = HF(PATHNAME_LENGTH || PATHNAME) > > + > > + WHERE HF is the cryptographic hash function > > + that has been designated for use by the > > + security modeling namespace. > How do you handle hash collisions? Given that users will likely be > able to create files with arbitrary names, it seems like identifying > files by a hash of their pathname without any way to safely resolve > digest collisions is a problem in waiting. Also addressed in our first e-mail, we will stand by for your comments there. > > + base value=HEXID > > + The base keyword is used to indicate that the > > + ASCII base 16 encoded value HEXID should be > > + registered as the value used to generate > > + security state coefficients for the model > > + implemented in the modeling namespace. > > + > > + The binary length of the value specified by > > + HEXID must match the digest size of the > > + cryptographic hash function specified for use > > + in the security modeling namespace. > > + > > + A model specific base value is designed to be > > + used as a 'freshness' nonce, similar to an > > + attestation nonce, to prove that a model state > > + value or measurement is current and not being > > + replayed. > > + > > +What: /sys/kernel/security/tsem/InternalTMA > > +Date: July 2023 > > +Contact: Greg Wettstein <greg@enjellic.com> > > +Description: > > + > > + This directory will contain directories that will be > > + used to hold files that surface model parameters for > > + Trusted Modeling Agents (TMA's) for internally modeled > > + security namespaces. > > + > > + There is currently only one internal TMA that is > > + surfaced through the following directory: > > + > > + /sys/kernel/security/tsem/InternalTMA/model0 > > + > > + The subsequent descriptions for the files implemented > > + in this directory will use ROOTDIR to represent the > > + above directory for space conservation purposes. > > + > > +What: ROOTDIR/measurement > > +Date: July 2023 > > +Contact: Greg Wettstein <greg@enjellic.com> > > +Description: > > + The measurement file contains the ASCII base 16 > > + representation of the time dependent linear extension > > + value of all the security state coefficients in the > > + model implemented by the namespace of the calling > > + process. > If I remember correctly, one of the motivations for TSEM was to > avoid the time/ordering aspect of traditional attestation approaches > as it can be fragile. Assuming that my memory is correct, and this > still holds true in the revision of the patchset, why are you > continuing to export time/order dependent measurements to userspace? > > Either the ordering is important, in which case TSEM's novelty isn't > useful, or the ordering isn't important and we can remove this sysfs > file. We addressed that in the second e-mail we sent last Friday. As we indicated in that e-mail, TSEM is about implementing infrastructure for building arbitrary mandatory security models. We don't advocate for either a time dependent or time independent model, we leave that up to whoever is implementing a security model to be executed in a modeling namespace by TSEM. Hopefully we have established that there is some small modicum of novelty in TSEM beyond the notion of a time independent measurement of the state state of a workload... > > +What: ROOTDIR/state > > +Date: July 2023 > > +Contact: Greg Wettstein <greg@enjellic.com> > > +Description: > > + The state file contains the ASCII base 16 > > + representation of the functional value of a security > > + modeling namespace. > > + > > + The state value is a time independent representation > > + of the measurement of a security model, and unlike the > > + measurement value, is a time independent > > + representation of the state. > > + > > + This value is designed to be a single value that can > > + be attested to represent whether or not a workload has > > + deviated from a defined security behavior. > Continuing the comment above regarding ROOTDIR/measurement, this > file makes much more sense in the context of TSEM. Once again, we offer both since TSEM is a general purpose security modeling framework. > > +What: ROOTDIR/trajectory > > +Date: July 2023 > > +Contact: Greg Wettstein <greg@enjellic.com> > > +Description: > > + The trajectory file contains a description of the > > + security events that have occurred in a security > > + modeling namespace > > + > > + Each entry in this file represents a single security > > + event and consists of a JSON encoded record with key > > + values that define the characteristics of the event. > > + > > + Each line in a trajectory, or forensics, file will > > + always have the event and COE keys. The event key > > + describes the characteristics of a security event > > + while the COE field describes the Context Of Execution > > + that is requesting execution of a security event. > > + > > + The event key consists of the following > > + characteristic definitions: > > + > > + process: COMM > > + Where COMM is the ASCII representation > > + of the name of the process executing > > + the event. > What happens if a process, either innocently or maliciously, changes > its name (see prctl(PR_SET_NAME))? Would it result in a mismatch of > the security state of a process? The process name isn't incorporated into the security state coefficient, it is included as an aid for developers or security architects who are analysing security event description streams. At the risk of injecting a bit more wonkiness, TSEM approaches security from the perspective of Hegelian epistemology, roughly translated, TSEM security decisions are exclusively experiential, ie. derived from unit testing of a workload. If the process name was included in the composition of a security state coefficient, any subsequent execution of the workload would have to use that name, otherwise it would generate a security model violation. Additionally, TSEM implements a handler for the task_prctl event. If a process in a workload would attempt to use prctl to change its process name, and that was not a modeled event, a security event coefficient would be generated which would be inconsistent with the security model being enforced. > > + type: EVENT_TYPE > > + The value field for a type key is the > > + name of the security event that is > > + being modeled. The list of EVENT_TYPE > > + names is defined in the following > > + source file: > > + > > + security/tsem/tsem.c > > + > > + If the security event is a generically > > + modeled event the EVENT_TYPE will be > > + generic_event. In this case the CELL > > + characteristics for the event will be > > + described by a generic_event: key > I'm guessing EVENT_TYPE is an ASCII string representation? It would > be good to clarify as you have in most (all?) of the other fields > and the omission here raises a red flag. We will clarify, but for future reference all of the control plane output files emit ASCII exclusively. > > + task_id: HEXID > > + The value of the task_id key will the > > + ASCII base 16 representation of the > > + identity of the task that is executing > > + the security handler. The length of > > + HEXID will match the size of the > > + digest value of the cryptographic hash > > + function selected for use by the > > + security modeling namespace. > > + > > + The following documentation file: > > + > > + Documentation/admin-guide/LSM/TSEM.rst > It looks like the file is lowercase ".../tsem.rst". Good catch, we missed that in the release review. > > + Describes how the TASK_ID value is > > + generated. > I would suggest either moving or copying the TASK_ID definition here > so that it is included in the TSEM ABI document. As we mentioned in the first e-mail, we were considering putting a disclaimer at the top of the ABI document that the tsem.rst file should be consumed first as a primer for understanding the ABI. > > + The COE key has the following characteristic keys. > > + Keys that involve discretionary access values > > + (uids/gids) will have their numeric value computed > > + based on the user namespace reference value that is > > + being implemented in the security modeling namespace. > > + > > + uid: NN > > + The ASCII base 10 representation of > > + the numeric value of the discretionary > > + user id of the process that is > > + executing the security event. > > + > > + euid: NN > > + The ASCII base 10 representation of > > + the numeric value of the effective > > + discretionary user id of the process > > + that is executing the security event. > > + > > + euid: NN > > + The ASCII base 10 representation of > > + the numeric value of the effective > > + discretionary user id of the process > > + that is executing the security event. > > + > > + suid: NN > > + The ASCII base 10 representation of > > + the numeric value of the saved user id > > + of the process that is executing the > > + security event. > > + > > + gid: NN > > + The ASCII base 10 representation of > > + the numeric value of the discretionary > > + group id of the process that is > > + executing the security event. > > + > > + egid: NN > > + The ASCII base 10 representation of > > + the numeric value of the discretionary > > + effective group id of the process that > > + is executing the security event. > > + > > + egid: NN > > + The ASCII base 10 representation of > > + the numeric value of the discretionary > > + effective group id of the process that > > + is executing the security event. > > + > > + sgid: NN > > + The base 10 ASCII representation of > > + the numeric value of the saved > > + discretionary group id of the process > > + that is executing the security event. > > + > > + fsuid: NN > > + The base 10 ASCII representation of > > + the numeric value of the discretionary > > + filesystem user id of the process that > > + is executing the security event. > > + > > + fsgid: NN > > + The ASCII base 10 representation of > > + the numeric value of the discretionary > > + filesystem group id of the process > > + that is executing the security event. > > + > > + capeff: 0xNNN > > + The ASCII base 16 representation of > > + the numeric value of effective > > + capabilities of the process that is > > + executing the security event. > > + > > + If the CELL value for a security event includes the > > + definition of a file a file: key value will be > > + included. The following characteristics will be > > + encoded in this field: > > + > > + flags: NN > > + The ASCII base 10 representation of > > + the flags value of the 'struct file' > > + structure that is the source of the > > + file description. > > + > > + uid: NN > > + The ASCII base 10 representation of > > + the discretionary user id of the file. > > + > > + gid: NN > > + The base 10 ASCII representation of > > + the discretionary group id of the > > + file. > > + > > + mode: 0NNN > > + The ASCII base 8 representation of the > > + mode bits of the file. > Does the leading zero followed by three octets imply you don't > record the setuid/setgid/sticky bits? The full value of the mode variable is output, including the setuid/setgid/sticky bits, the NNN is an arguably confusing representation and we will figure out an alternative way to document this. > > + name_length: NN > > + The ASCII base 10 representation of > > + the length of the pathname that will > > + be encoded in the name= characteristic. > To clarify, this is the length of the pathname used during the file > lookup and not the length of the hash digest of the previously > mentioned pathname, yes? As we mentioned previously, this no longer exists in V3. > > + name: NN > > + The ASCII hexadecimal representation > > + of the SHA256 checksum of the pathname > > + of the file that is pre-pended with > > + the little-endian binary value of the > > + length of the pathname. > Hash agility? Maximized in V3... :-) > It isn't clear to me if the length is prepended before or after the > hash, it would be good to clean this up. > > Also, similar to some comments above, how are you handling hash > collisions? As pathnames can be influenced by unprivileged users, this > would appear to be an issue. Addressed in previous e-mail. Succinctly, to our knowledge, there are no computationally feasible 2nd pre-image attacks against modern hash functions that would be used for TSEM. If you have information otherwise, we, and probably the rest of the security industry, would be deeply interested if not concerned. To extend a bit further. The viability of a pathname or security coefficient stream collision attack needs to be assessed with respect to the experiential nature of the TSEM security models. If an adversary was attempting to change pathnames in order to to exploit a collision against an existing security state coefficient the model under which the workload was running would need to reflect the security states that would be needed for the pathname changes, otherwise the workload would be in violation of its model. Without digging too deep, at a minimum, a tsem_inode_create event would be presumably triggered on the creation of a new candidate filename to exploit the collision. > > + s_magic: 0xNN > > + The ASCII base 16 representation of the > > + magic number of the filesystem that > > + contains the file. > > + > > + s_id: NAME > > + The ASCII name of the block device for > > + the filesystem that contains the file. > > + > > + s_UUID: HEX > > + The ASCII base 16 representation of > > + the hexadecimal value of the UUID of > > + the filesystem that contains the file. > > + > > + digest: HEX > > + The ASCII base 16 representation of > > + the SHA256 digest of the file. > Hash agility? > > Is TSEM running a hash over every file included in a file-related > security event? Yes, unless the model developer has tagged the file as having a digest pseudonym. > > + If the event type is the memory mapping of a file a > > + mmap_file key value will be included with > > + the following characteristics: > Still part of the CELL? COE? This doc could benefit from better > explanations of the CELL and COE terms. This would be the CELL, since it characterizes the security event. > > + type: N > > + Where N is an ASCII 0 or 1 to indicate > > + whether or not the mapping is file > > + backed or anonymous. A value of 1 is > > + used to indicate an anonymous mapping. > > + > > + reqprot: NN > > + Where N is ASCII base 10 > > + representation of the protections > > + requested for the mapping. > > + > > + prot: NN > > + Where N is the ASCII base 10 > > + representation of the protections that > > + will be applied to the mapping. > > + > > + flags: NN > > + Where N is the ASCII base 10 > > + representation of the flags that will > > + be used for the memory mapping operation. > You should specify the flags used in the fields above, or refer > readers to the mmap(2) flag definitions if appropriate. In V3 all of the security events are fully parameterized. We will include documentation that the CELL field for each event encodes the arguments to the event. In light of this we will be evaluating how to best express the ABI documentation. > > + If the event type is a socket creation event a > > + socket_create key value will be included with the > > + following characteristics: > > + > > + family: N > > + Where N is the ASCII base 10 > > + representation of the family type of > > + the socket. > > + > > + type: N > > + Where N is the ASCII base 10 > > + representation of the type of socket > > + being created. > > + > > + protocol: N > > + Where N is the ASCII base 10 > > + representation of the protocol family > > + for the socket. > Similar to the mmap flags above, I would refer people to where these > values are defined. The applies to the other socket family/type/proto > fields described elsewhere in this document. That will be part of the ABI review in V3. > > + kern: 0 | 1 > > + Where 0 or 1 is used to indicate > > + whether or not the socket is kernel > > + based. A value of 1 implies it is > > + kernel based. > I'm curious how TSEM would distinguish between different kernel > socket events. I would expect most kernel sockets to share the same > event key (COE/CELL/etc.), is that not the case? In V3 all of the generation of security state coefficient that include a struct sock * argument to the handler include the TASK_ID of the task that created the socket, this causes the security state coefficients to be tied to the corpus of executable code that created the socket. The same is being done with other resource types that are 'created' in a modeling namespace, ie. ipc, inodes etc. > > + If the event type is a socket_connect or a > > + socket_bind, a socket_connect: or a socket_bind: key > > + value will be included that will be characterized > > + based on an encoding of either an IPV4, IPV6, AF_UNIX > > + or a generic socket description. > > + > > + family: N > > + Where N is the ASCII base 10 > > + representation of the family type of > > + the socket. > > + > > + port: N > > + Where N is the base ASCII base 10 > > + representation of the port number that > > + is being used for either an IPV4 or > > + IPV6 socket connection or bind. > > + > > + addr: N | PATH | HEXID > > + In the case of an IPV4 socket the > > + value for the addr key will be the > > + ASCII base 10 representation of the 32 > > + bit IPV4 address being bound or > > + connected to. > > + > > + In the case of an IPV6 connection the > > + value to the key will be the ASCII > > + base 16 representation of the 128 bit > > + address being bound connected. > > + > > + In the case of an AF_UNIX connection > > + the value will be the pathname of the > > + socket in the mount namespace that the > > + process is running in. > > + > > + In the case of any other type of > > + socket the addr value will be the > > + ASCII base 16 representation of the > > + cryptographic digest value of the > > + entire length of the address > > + description. The length of the > > + representation will be the size of the > > + digest produced by the cryptographic > > + hash function that has been specified > > + for the modeling namespace. > > + > > + flow: N > > + For an IPV6 socket the value of the > > + flow key will be the ASCII base 10 > > + representation of the flow identifier > > + assigned to the socket. > > + > > + scope: N > > + For an IPV6 socket the value of the > > + scope key will be the ASCII base 10 > > + representation of the scope identifier > > + assigned to the socket. > What will "flow" and "scope" be for non-AF_INET6 sockets? You need > to specify that here. There will be no 'flow' or 'scope' values for non-AF_INET6 sockets. The JSON encoded security event descriptions are designed to be self-expressive by whatever is interpreting the event stream, ie. if the socket family is AF_INET the interpreter will not look for keys that would express characteristics not expected in an IPV4 socket description. > > + If the event type is a socket_accept a socket_accept > > + key value will be included that characterizes either > > + an IPV4, IPV6 or a generic socket description with the > > + following event descriptions: > > + > > + family: N > > + Where N is the ASCII base 10 > > + representation of the family type of > > + the socket. > > + > > + type: N > > + Where N is the ASCII base 10 > > + representation of the type of the > > + socket being created. > > + > > + port: N > > + Where N is the base ASCII base 10 > > + representation of the port number that > > + is being used for either an IPV4 or > > + IPV6 socket connection or bind. > > + > > + addr: N | PATH | HEXID > > + In the case of an IPV4 socket the > > + value for the addr key will be the > > + ASCII base 10 representation of the 32 > > + bit IPV4 address being bound or > > + connected to. > > + > > + In the case of an IPV6 connection the > > + value to the key will be the ASCII > > + base 16 representation of the 128 bit > > + address being bound connected. > > + > > + In the case of an AF_UNIX connection > > + the value will be the pathname of the > > + socket in the mount namespace that the > > + process is running in. > > + > > + In the case of any other type of > > + socket the addr value will be the > > + ASCII base 16 representation of the > > + cryptographic digest value of the > > + entire length of the address > > + description. The length of the > > + representation will be the size of the > > + digest produced by the cryptographic > > + hash function that has been specified > > + for the modeling namespace. > > + > > +What: ROOTDIR/trajectory_coefficients > > +Date: July 2023 > > +Contact: Greg Wettstein <greg@enjellic.com> > > +Description: > > + The trajectory_coefficients file will output the ASCII > > + base16 representation of each security state > > + coefficient that has been generated by the security > > + modeling namespace of the calling process. > > + > > + The length of each point will be the ASCII > > + representation of the size of the cryptographic hash > > + function that has been specified for the model. > Is this just the ROOTDIR/trajectory JSON in ASCII hex, or something > different? These are the security state coefficients that each event in the trajectory file encodes into under the current model. > > +What: ROOTDIR/trajectory_counts > > +Date: July 2023 > > +Contact: Greg Wettstein <greg@enjellic.com> > > +Description: > > + The trajectory_coefficients file will output the ASCII > > + base10 representation of the number of times each > Unless I'm mistaken, I believe you defined it as base16 above ... ? These are base 10 values that describe how many times each unique security event has been experienced in the model. > > + security state coefficient has been generated by the > > + security modeling namespace of the calling process. > > This looks like an old cut-n-paste error. I'm guessing this file > reports on the number of coefficients in ASCII base10? Correct. > > +What: ROOTDIR/forensics > > +Date: July 2023 > > +Contact: Greg Wettstein <greg@enjellic.com> > > +Description: > > + The forensics file contains the descriptions of > > + security events that are inconsistent with the > > + security model that the security namespace is > > + implementing. Forensics events are generated after a > > + security model is 'sealed' and the events represent > > + security state coefficients that have not already been > > + generated by the model. > > + > > + The format of lines in this file are identical to the > > + output generated by the ROOTDIR/trajectory file > > + that is documented above. > > + > > +What: ROOTDIR/forensics_coefficients > > +Date: July 2023 > > +Contact: Greg Wettstein <greg@enjellic.com> > > +Description: > > + The forensics_coefficients file will output the ASCII > > + base16 representation of each security state > > + coefficient that have been generated by forensics > > + events in the security modeling namespace of the > > + calling process. > > + > > + The length of each point will be the ASCII > > + representation of the size of the cryptographic hash > > + function that has been specified for the model. > > + > > +What: ROOTDIR/forensics_counts > > +Date: July 2023 > > +Contact: Greg Wettstein <greg@enjellic.com> > > +Description: > > + The forensics_counts file will output the ASCII base10 > > + representation of the number of times each security > > + state coefficient, generated by a forensics event, has > > + been generated by the security modeling namespace of > > + the calling process. > > + > > +What: /sys/kernel/security/tsem/ExternalTMA > > +Date: July 2023 > > +Contact: Greg Wettstein <greg@enjellic.com> > > +Description: > > + The ExternalTMA directory is a container directory > > + that hold files that will be used to export the > > + security events, and their associated parameters, for > > + externally modeled security modeling namespaces. > > + > > + The files created in this directory will be named by > > + the base 10 ASCII representation of the id value > > + assigned to the security modeling namespace. See the > > + documentation for the /sys/kernel/security/tsem/id > > + file in this documentation for more details on this > > + value. > > + > > + This file will is a read-only file that can be polled > > + by a userspace trust orchestrator implementation to > > + process security events that are to be modeled by an > > + external Trusted Modeling Agent. > > + > > + Each exported event is a JSON encoded record > > + describing the event that is to be processed. > > + > > + Each record will have an 'export' key that has a > > + structure associated with it that has a 'type' key in > > + it. The 'type' key has a string value associated with > > + it that defines the type of event that is being > > + processed. > > + > > + The following export 'type' strings are defined: > > + > > + aggregate: > > + The aggregate key has an associated structure > > + value that defines a key named 'value' that > > + has a string value associated with it that > > + represents the hardware aggregate for the > > + platform. > You need to define "hardware aggregate" here, if you can't go into > detail you need a good summary outlining its security relevant > properties. As noted above, will consider how to do this. > > + The hardware aggregate string is expressed as > > + the ASCII base16 representation of the > > + platform hardware aggregate value. The length > > + of the string will be the size of the digest > > + produced by the cryptographic hash function > > + that has been specified for the security > > + modeling namespace of the process generating > > + the event. > > + > > + async_event: > > + If the type of the export is async_event there > > + will be a key named 'event' that has a structure > > + value associated with it. > > + > > + The structure associated with the 'event' key > > + will be identical to the structure generated > > + for the 'event' key that is described below. > > + > > + event: > > + If the type of the export is event there will > > + be a key named 'event' that has a structure > > + value associated with it that contains the > > + follow key: value pairs. > > + > > + pid: NNN > > + Where the NNN is the ASCII base 10 > > + value of the id of the process that is > > + executing the security event that will > > + be modeled. > Once more, you can't use a PID to safely identify a process. As suggested previously, this was the subject of our first mail. > paul-moore.com Have a good week. As always, Dr. Greg The Quixote Project - Flailing at the Travails of Cybersecurity https://github.com/Quixote-Project
On Mon, Jan 8, 2024 at 6:43 AM Dr. Greg <greg@enjellic.com> wrote: > On Wed, Jan 03, 2024 at 11:00:33PM -0500, Paul Moore wrote: > > On Jul 10, 2023 "Dr. Greg" <greg@enjellic.com> wrote: > > > > > > An entry was added to the ABI testing documentation to document > > > the files in the TSEM management filesystem. > > > > > > The file documenting the kernel command-line parameters was > > > updated to document the TSEM specific command-line parameters > > > > > > The primary TSEM documentation file was added to the LSM > > > administration guide and the file was linked to the index of LSM > > > documentation. > > > > > > Signed-off-by: Greg Wettstein <greg@enjellic.com> > > > --- > > > Documentation/ABI/testing/tsem | 828 +++++++++ > > > Documentation/admin-guide/LSM/index.rst | 1 + > > > Documentation/admin-guide/LSM/tsem.rst | 1526 +++++++++++++++++ > > > .../admin-guide/kernel-parameters.txt | 18 + > > > 4 files changed, 2373 insertions(+) > > > create mode 100644 Documentation/ABI/testing/tsem > > > create mode 100644 Documentation/admin-guide/LSM/tsem.rst ... > > I don't want to assume too much about the TSEM design, but I'm > > guessing the aggregate is intended to be a deterministic value based > > on the PCRs and therefore it seems like there is value in providing > > a clear explanation of how it is calculated. > > The aggregate is the linear extension sum over PCR registers 0 through > 8 using the namespace hash function, we will cook up a generic > description, although it should be a common enough concept for anyone > working on trusted system implementations. The Linux kernel documentation is used by a wide variety of administrators, users, and developers with varying backgrounds, I would recommend assuming very little about the documentation's audience. This is not to say that you need to explain everything yourself, referring interested readers to established, publicly available sources of background information can be acceptable. > > > + trusted pid=PID key=HEXID > > > + The trusted keyword is used by a trust > > > + orchestrator to indicate that the process > > > + identified by the PID argument should be > > > + allowed to run in trusted status after the > > > + modeling of a security event. > > > I mentioned this quite a few times in my review of the previous > > patchset, PIDs are not a safe way to identify a process in the > > system. PID reuse/recycling is a real danger and you need to > > account for this risk. > > We will defer that discussion to our previous e-mail where we > discussed how this is addressed. Adding a secret key/token/etc. may provide some additional authentication benefits, but it doesn't entirely solve the PID identification issue, it only reduces the likelihood of a process misidentification. We need to do better for new designs/implementations; look at the pidfd work as an example of work that has gone into reducing/eliminating the use of PIDs to identify processes.
On Mon, Feb 05, 2024 at 11:09:28AM -0500, Paul Moore wrote: Hi, I hope the week is starting well for everyone. Sorry for the delay in responding, was involved with a bit of travel. > On Mon, Jan 8, 2024 at 6:43AM Dr. Greg <greg@enjellic.com> wrote: > > On Wed, Jan 03, 2024 at 11:00:33PM -0500, Paul Moore wrote: > > > > + trusted pid=PID key=HEXID > > > > + The trusted keyword is used by a trust > > > > + orchestrator to indicate that the process > > > > + identified by the PID argument should be > > > > + allowed to run in trusted status after the > > > > + modeling of a security event. > > > > > I mentioned this quite a few times in my review of the previous > > > patchset, PIDs are not a safe way to identify a process in the > > > system. PID reuse/recycling is a real danger and you need to > > > account for this risk. > > > > We will defer that discussion to our previous e-mail where we > > discussed how this is addressed. > Adding a secret key/token/etc. may provide some additional > authentication benefits, but it doesn't entirely solve the PID > identification issue, it only reduces the likelihood of a process > misidentification. We agree with you that PID reuse/recycling is a real danger. It is our position that TSEM, for its purposes, properly mitigates this risk. Before doing that, for the benefit of everyone reading along. The threat scenario is that a process waiting for model evaluation of an LSM hook by an external trust orchestrator could be killed and a process with an identical PID substituted. This would result in the trust orchestrator setting the trust status of the wrong process. Big picture overview: - A trust orchestrator enforces a security model that has been previously established through unit testing as valid. Substituting an alternate process with the same PID would result in that process being constrained to only security states that are considered valid. - Once a process has been designated as untrusted, that status cannot be reversed by occupying a known good security state. Thus a process misidentification attack cannot be used to reverse the trust state of an untrusted process. For purposes of further clarification, lets look at the relevant portions of the TSEM code. For an externally modeled domain, the process begins with the export of the security event description by tsem_export_event() in export.c: --------------------------------------------------------------------------- int tsem_export_event(struct tsem_event *ep) { int retn = 0; struct export_event *exp; struct tsem_task *task = tsem_task(current); struct tsem_context *ctx = task->context; exp = allocate_export(ep->locked); if (!exp) { pr_warn("tsem: domain %llu failed export allocation.\n", ctx->id); return -ENOMEM; } exp->type = ep->locked ? EXPORT_ASYNC_EVENT : EXPORT_EVENT; exp->u.ep = ep; tsem_event_get(ep); spin_lock(&ctx->external->export_lock); list_add_tail(&exp->list, &ctx->external->export_list); spin_unlock(&ctx->external->export_lock); if (ctx->external->export_only || ep->locked) { trigger_event(ctx); return 0; } task->trust_status |= TSEM_TASK_TRUST_PENDING; trigger_event(ctx); A TSEM modeled task can exist in one of two states: TRUSTED and UNTRUSTED in combination with TRUST_PENDING. The process trust status gets set to TRUST_PENDING to force it to wait until it is released by the trust orchestrator. The orchestrator is signaled to indicate that a security event is in need of evaluation. The process then waits in the following loop until the trust orchestrator issues a control plane call to set its trust status and clear the TRUST_PENDING state. The PID slot will be maintained and thus unavailable by virtue of the task maintaining a reference to the PID slot while it is sleeping. while (task->trust_status & TSEM_TASK_TRUST_PENDING) { set_current_state(TASK_INTERRUPTIBLE); schedule(); if (fatal_signal_pending(task)) { retn = -EPERM; task->trust_status = TSEM_TASK_UNTRUSTED; } } The only way out of the loop is to either have the TRUST_PENDING status cleared by the orchestrator or to have a fatal signal queued. In the event of the latter condition, the process trust state is set to untrusted for the exit and an error is returned to the trust orchestrator. An error return from a control plane call would be considered an actionable event to shutdown the workload, secondary to it being considered untrusted by virtue of a failure that should not occur. The process itself would be considered untrusted during its exit. Next, lets consider the issues and protections surrounding the initiation of a fatal signal. A security modeling namespace serves as a boundary for a kill signal, unless a cross-model signal generation event has been enabled in the signal initiating namespace or the initiating process has CAP_MAC_ADMIN privileges. Either case admits the notion that such a signal is being administratively allowed from a security perspective. Within a security namespace, for a kill signal to be initiated, it must have a security state coefficient included in the model that is specific to the TASK_ID of the process initiating the signal. The target of the signal must have a specific TASK_ID as well. This gates successful signaling to two binaries of known provenance. Given that the model being enforced is generated from a known good unit test, no adversarial signals would be allowed from within the modeling namespace. That leaves the OOM killer, as has been previously suggested. An adversary would need to deplete memory in a manner that caused the OOM killer to select the process that was sleeping on an evaluation by the trust orchestrator, rather than the adversarial process or processes that were consuming memory. We would also offer the following with respect to the latency challenges associated with a PID misidentification attack. As noted previously, threat latencies with respect to substituting an alternate process with something like the OOM killer would be on the order of 200-300 micro-seconds. A sufficient number of processes would have to be forked during the race window in order to have a process poised to replace the task that is being held for trust evaluation. These forks must occur before the trust orchestrator has a chance to be scheduled and complete processing of the event, which would have the effect of terminating the race window. For purposes of reasoning, here is a sample of average process fork latencies over 32,768 attempts: Intel(R) Xeon(R) Silver 4214R CPU @ 2.40GHz - 8 core - 69.4 micro-seconds Intel(R) Core(TM) i5-6500 CPU @ 3.20GHz - 4 core - 81.3 micro-seconds Intel(R) Core(TM) i5-9400 CPU @ 2.90GHz - 1 core - 132.2 micro-seconds The above timings indicate a requirement for an adversarial process to be within a window of 2-5 PID 'slots' below the target process for an attack to be effective. As noted at the start of this mail, the substituted PID would be constrained to the security policy that the trust orchestrator is implementing. It would thus be limited from initiating any security relevant events that are inconsistent with the security model being enforced. A single failed security event would result in a security state change for the security modeling namespace, that in turn would result in failed attestation of the trust status of the workload or platform. return retn; } --------------------------------------------------------------------------- There are additional quarantees in place that disallow a substituted process from being acted upon by the trust orchestrator for a security modeling namespace. For an externally modeled security event, the process ends with a request by the trust orchestrator, through the control plane file for the security modeling namespace. The file only allows a single open and that open would have been by the trust orchestrator that created the security modeling namespace, thereby precluding an adversarial process from gaining control of the release process. The trust relationship between an orchestrator and the processes in a security modeling namespace is established in the allocate_external() function in namespace.c: --------------------------------------------------------------------------- static struct tsem_external *allocate_external(u64 context_id, const char *keystr) { int retn = -ENOMEM; char bufr[20 + 1]; struct tsem_external *external; struct tsem_task *t_ttask = tsem_task(current); struct tsem_task *p_ttask = tsem_task(current->real_parent); external = kzalloc(sizeof(*external), GFP_KERNEL); if (!external) goto done; retn = generate_task_key(keystr, context_id, t_ttask, p_ttask); if (retn) goto done; The generate_task_key() function is responsible for generating a random trust orchestrator identifier that is unique across all currently active security modeling namespaces. Uniqueness is guaranteed by all facets of namespace creation being gated by the context_id_mutex lock held during the critical section of namespace creation in tsem_ns_create(). Half of the input to the final identifier is provided by the trust orchestrator, with the other half being a random key is generated and attempted until a system unique identifier is demonstrated. The trust orchestrator identifier is copied into the TSEM specific portion of the task structure of the parent of the task that is creating the namespace (p_ttask). This process is the trust orchestrator that forked the current process that is divesting itself, and its children, into a new security modeling namespace. By virtue of this uniqueness gurantee, no other task on the system will have this identifier. spin_lock_init(&external->export_lock); INIT_LIST_HEAD(&external->export_list); init_waitqueue_head(&external->wq); scnprintf(bufr, sizeof(bufr), "%llu", context_id); external->dentry = tsem_fs_create_external(bufr); if (IS_ERR(external->dentry)) { retn = PTR_ERR(external->dentry); external->dentry = NULL; } else retn = 0; done: if (retn) { memset(t_ttask->task_key, '\0', tsem_digestsize()); memset(p_ttask->task_key, '\0', tsem_digestsize()); kfree(external); remove_task_key(context_id); external = ERR_PTR(retn); } else p_ttask->tma_for_ns = context_id; In addition to having a system unique orchestration identifier placed in the trust orchestrator's task structure, the identifier of the namespace, that is guaranteed to not wrap, is also placed in the task control structure of the orchestrator. return external; } --------------------------------------------------------------------------- All of this leads us to the processing of the control plane request by a trust orchestrator to set the trust status of a process whose security event is being modeled. This request is handled by the control_COE() function in fs.c: --------------------------------------------------------------------------- static int control_COE(unsigned long cmd, pid_t pid, char *keystr) { bool wakeup = false; int retn = -ESRCH; u8 event_key[HASH_MAX_DIGESTSIZE]; struct task_struct *COE; struct tsem_task *task; struct tsem_task *tma = tsem_task(current); rcu_read_lock(); COE = find_task_by_vpid(pid); We use the standard kernel infrastructure to find the PID that has been previously put to sleep in the export code. If someone was nefariously attempting to kill PIDs, an actionable error will be registered with the trust orchestor if the task cannot be located. Once again, the only way out of the previously described control section is by either the process receiving a fatal signal or this function clearing the TRUST_PENDING state bit. if (COE != NULL) { task = tsem_task(COE); if (tsem_context(COE)->id != tma->tma_for_ns) { retn = -EINVAL; goto done; } Once the candidate task is located, its security modeling namespace identifier is verified to match that of the trust orchestrator. This denies processes from outside of the security modeling namespace access to this control call. retn = tsem_ns_event_key(task->task_key, keystr, event_key); if (retn) goto done; The trust orchestrator identifier is generated using half of the key re-supplied in the control call by the trust orchestrator itself and the other half that has been re-supplied from the task structure of the process being evaluated. This limits the PID substitution domain to the security modeling namespace that the trust orchestrator holds dominion over. Once again, only security relevant events that the namespace has been tested to are allowed to occur within the namespace. If a PID substitution attack were to be mounted, it would have to be by 'known good' code that was admitted for execution into the modeling namespace. if (memcmp(tma->task_key, event_key, tsem_digestsize())) { retn = -EINVAL; goto done; } The generated key is compared to the key held inside the task control structure of the trust orchestrator and the control is denied if they do not match. Once again, this would be an actionable event to shutdown the workload as being untrusted. if (cmd == TSEM_CONTROL_UNTRUSTED) task->trust_status = TSEM_TASK_UNTRUSTED; if (cmd == TSEM_CONTROL_TRUSTED) { if (tsem_task_trusted(COE)) task->trust_status = TSEM_TASK_TRUSTED; } task->trust_status &= ~TSEM_TASK_TRUST_PENDING; The trust status of the process is set and the TRUST_PENDING state is cleared. As the above code section demonstrates, a process that is untrusted cannot use a PID substitution attack to convert its status to trusted. } retn = 0; wakeup = true; } done: rcu_read_unlock(); if (retn == -EINVAL) pr_warn("tsem: Invalid process release request.\n"); if (wakeup) wake_up_process(COE); The process is turned loose from its loop in export.c:tsem_export_event() with its new trust status. return retn; } --------------------------------------------------------------------------- > We need to do better for new designs/implementations; look at the > pidfd work as an example of work that has gone into > reducing/eliminating the use of PIDs to identify processes. We have a high degree of familiarity with the pidfd work, in fact we use pidfd_open() to establish a stable and immutable relationship between a Quixote trust orchestrator and the lead process in a security modeling namespace, typically runc in a container environment. In TSEM, the issue is that the trust orchestrator may not have a direct relationship with any number of processes that may be running in a security modeling namespace. Processes asynchronously generate events that need to be identified for the trust orchestrator to act on. If we misunderstand pidfd's, or lack understanding of other alternate infrastructure that could be purposed for our needs, we would certainly be interested in your thoughts on an alternate implementation. Otherwise we would enjoy specific comments on how our implementation would be security insufficient in the face of a PID substitution or race attack. > paul-moore.com Have a good day. As always, Dr. Greg The Quixote Project - Flailing at the Travails of Cybersecurity https://github.com/Quixote-Project
diff --git a/Documentation/ABI/testing/tsem b/Documentation/ABI/testing/tsem new file mode 100644 index 000000000000..cfb013b5f1f4 --- /dev/null +++ b/Documentation/ABI/testing/tsem @@ -0,0 +1,828 @@ +What: /sys/kernel/security/tsem +Date: July 2023 +Contact: Greg Wettstein <greg@enjellic.com> +Description: + The /sys/kernel/security/tsem directory contains files + and directories that implement the control plane for + the Trusted Security Event Modeling (TSEM) LSM. + + The files in this directory hierarchy, with the + exception of the aggregate file, when read, reflect + the values for the security modeling namespace that + the process reading the files is operating in. + +What: /sys/kernel/security/tsem/id +Date: July 2023 +Contact: Greg Wettstein <greg@enjellic.com> +Description: + The id file contains the ASCII base 10 representation + of the model domain/namespace identifier that the + reading process is operating in. + + The root security modeling namespace has a value of + zero, a non-zero value indicates a modeling namespace + subordinate to the root model. + + Each externally modeled domain will have a file, with + this id number, created in the + /sys/kernel/security/tsem/ExternalTMA directory that + is documented below. + +What: /sys/kernel/security/tsem/aggregate +Date: July 2023 +Contact: Greg Wettstein <greg@enjellic.com> +Description: + The aggregate file contains the ASCII base 16 + representation of the 256 bit hardware platform + aggregate that TSEM is modeling under. The platform + aggregate is the linear extension measurement of the + Trusted Platform Module PCR registers 0 through 8. + + On a platform without a TPM this value will be all + null bytes. + +What: /sys/kernel/security/tsem/control +Date: July 2023 +Contact: Greg Wettstein <greg@enjellic.com> +Description: + The control file is the only writable file in the + filesystem and is used by the trust orchestrator's to + configure and control the behavior of the TSEM + implementation. + + The following keyword and arguments are recognized: + + internal + The internal keyword causes an internally + modeled domain to be created for the calling + process. + + external + The external keyword causes an externally + modeled domain to be created for the calling + process. + + A modeling namespace created by these commands + accept the following set of key=value pairs + that configure the namespace: + + nsref=initial|current + The nsref key specifies the namespace + that is to be referenced when + determining the UID/GID values that + define a COE or CELL identity. + + The initial keyword specifies that the + initial user namespace be used. The + current keyword specifies that the + user namespace of the process that is + invoking a security event handler + (hook) is used. + + digest=digestname + The digest key is used to specify the + cryptographic hash function that is to + be used in the namespace for the + creation of COE and CELL identities. + + The digestname is the name used by the + Linux kernel cryptographic API to + identify the hash function. Examples + would include sha256, sha3-256, sm3 + etc. The source files for the + cryptographic hash function in the crypto + directory of the kernel source has the + names for hash functions implemented + in the kernel. + + The sha256 hash function is the + default function for the root modeling + domain. This can be modified by the + tsem_digest command-line parameter. + + A hash function, used by the root + modeling domain, must be built into + the kernel. + + cache=NN + The cache key specifies the size of + the caches to be used for holding + pointers to structures used for the + modeling or export of security events + that are called while the invoking + process is in atomic context. + + The value NN is the ASCII base 10 + representation of the number of + entries in the cache. + + By default, the root modeling + namespace and an externally modeled + namespace will have 96 entries. An + internally modeled namespace will have + 16 entries. + + key=HEXID + The key argument is used to specify + the authentication key that will be + used by a trust orchestrator to + authenticate trust control requests to + a process running in the security + modeling namespace. + + The HEXID value is the ASCII base16 + encoded key that is to be used. The + length of this key, in binary, must be + equal to the size of the digest + produced by the cryptographic hash + function that is being used in the + modeling namespace. + + enforce + The enforce keyword causes the modeling + domain/namespace of the process to enter + enforcing mode. In this mode, a value of + -EPERM will be returned for a security event + coefficient that does not map into the current + set of allowed coefficients for the security + model being implemented in the namespace. + + seal + The seal keyword causes the security model + being implemented for the namespace to be + placed in a sealed state. In this state, the + current set of security coefficients is + considered to be the only set of valid + coefficients for the model. Any subsequent + events that map to a coefficient not in the + current model will be considered a violation + of the model. + + trusted pid=PID key=HEXID + The trusted keyword is used by a trust + orchestrator to indicate that the process + identified by the PID argument should be + allowed to run in trusted status after the + modeling of a security event. + + The HEXID argument is the authentication key + that has been configured by a trust + orchestrator for the namespace at the time of + its creation. + + untrusted pid=PID key=HEXID + The untrusted keyword is used by a trust + orchestrator to indicate that the process + identified by the PID argument should be + designated as an untrusted process. + + The HEXID argument is the authentication key + that has been configured by a trust + orchestrator for the namespace at the time + its creation. + + state value=HEXID + The state keyword is used to indicate that the + security state coefficient identified by the + ASCII base 16 encoded value specified by HEXID + should be loaded into the current security + model as a valid security event coefficient. + + pseudonym valid=HEXID + The pseudonym keyword is used to indicate that + the pathname, identified by the ASCII base 16 + encoded value HEXID, should be designated to + return a constant digest value for the + contents of the file named by the pseudonym. + + The HEXID value is computed with the following + function: + + HEXID = HF(PATHNAME_LENGTH || PATHNAME) + + WHERE HF is the cryptographic hash function + that has been designated for use by the + security modeling namespace. + + base value=HEXID + The base keyword is used to indicate that the + ASCII base 16 encoded value HEXID should be + registered as the value used to generate + security state coefficients for the model + implemented in the modeling namespace. + + The binary length of the value specified by + HEXID must match the digest size of the + cryptographic hash function specified for use + in the security modeling namespace. + + A model specific base value is designed to be + used as a 'freshness' nonce, similar to an + attestation nonce, to prove that a model state + value or measurement is current and not being + replayed. + +What: /sys/kernel/security/tsem/InternalTMA +Date: July 2023 +Contact: Greg Wettstein <greg@enjellic.com> +Description: + + This directory will contain directories that will be + used to hold files that surface model parameters for + Trusted Modeling Agents (TMA's) for internally modeled + security namespaces. + + There is currently only one internal TMA that is + surfaced through the following directory: + + /sys/kernel/security/tsem/InternalTMA/model0 + + The subsequent descriptions for the files implemented + in this directory will use ROOTDIR to represent the + above directory for space conservation purposes. + +What: ROOTDIR/measurement +Date: July 2023 +Contact: Greg Wettstein <greg@enjellic.com> +Description: + The measurement file contains the ASCII base 16 + representation of the time dependent linear extension + value of all the security state coefficients in the + model implemented by the namespace of the calling + process. + +What: ROOTDIR/state +Date: July 2023 +Contact: Greg Wettstein <greg@enjellic.com> +Description: + The state file contains the ASCII base 16 + representation of the functional value of a security + modeling namespace. + + The state value is a time independent representation + of the measurement of a security model, and unlike the + measurement value, is a time independent + representation of the state. + + This value is designed to be a single value that can + be attested to represent whether or not a workload has + deviated from a defined security behavior. + +What: ROOTDIR/trajectory +Date: July 2023 +Contact: Greg Wettstein <greg@enjellic.com> +Description: + The trajectory file contains a description of the + security events that have occurred in a security + modeling namespace + + Each entry in this file represents a single security + event and consists of a JSON encoded record with key + values that define the characteristics of the event. + + Each line in a trajectory, or forensics, file will + always have the event and COE keys. The event key + describes the characteristics of a security event + while the COE field describes the Context Of Execution + that is requesting execution of a security event. + + The event key consists of the following + characteristic definitions: + + process: COMM + Where COMM is the ASCII representation + of the name of the process executing + the event. + + type: EVENT_TYPE + The value field for a type key is the + name of the security event that is + being modeled. The list of EVENT_TYPE + names is defined in the following + source file: + + security/tsem/tsem.c + + If the security event is a generically + modeled event the EVENT_TYPE will be + generic_event. In this case the CELL + characteristics for the event will be + described by a generic_event: key + + task_id: HEXID + The value of the task_id key will the + ASCII base 16 representation of the + identity of the task that is executing + the security handler. The length of + HEXID will match the size of the + digest value of the cryptographic hash + function selected for use by the + security modeling namespace. + + The following documentation file: + + Documentation/admin-guide/LSM/TSEM.rst + + Describes how the TASK_ID value is + generated. + + The COE key has the following characteristic keys. + Keys that involve discretionary access values + (uids/gids) will have their numeric value computed + based on the user namespace reference value that is + being implemented in the security modeling namespace. + + uid: NN + The ASCII base 10 representation of + the numeric value of the discretionary + user id of the process that is + executing the security event. + + euid: NN + The ASCII base 10 representation of + the numeric value of the effective + discretionary user id of the process + that is executing the security event. + + euid: NN + The ASCII base 10 representation of + the numeric value of the effective + discretionary user id of the process + that is executing the security event. + + suid: NN + The ASCII base 10 representation of + the numeric value of the saved user id + of the process that is executing the + security event. + + gid: NN + The ASCII base 10 representation of + the numeric value of the discretionary + group id of the process that is + executing the security event. + + egid: NN + The ASCII base 10 representation of + the numeric value of the discretionary + effective group id of the process that + is executing the security event. + + egid: NN + The ASCII base 10 representation of + the numeric value of the discretionary + effective group id of the process that + is executing the security event. + + sgid: NN + The base 10 ASCII representation of + the numeric value of the saved + discretionary group id of the process + that is executing the security event. + + fsuid: NN + The base 10 ASCII representation of + the numeric value of the discretionary + filesystem user id of the process that + is executing the security event. + + fsgid: NN + The ASCII base 10 representation of + the numeric value of the discretionary + filesystem group id of the process + that is executing the security event. + + capeff: 0xNNN + The ASCII base 16 representation of + the numeric value of effective + capabilities of the process that is + executing the security event. + + If the CELL value for a security event includes the + definition of a file a file: key value will be + included. The following characteristics will be + encoded in this field: + + flags: NN + The ASCII base 10 representation of + the flags value of the 'struct file' + structure that is the source of the + file description. + + uid: NN + The ASCII base 10 representation of + the discretionary user id of the file. + + gid: NN + The base 10 ASCII representation of + the discretionary group id of the + file. + + mode: 0NNN + The ASCII base 8 representation of the + mode bits of the file. + + name_length: NN + The ASCII base 10 representation of + the length of the pathname that will + be encoded in the name= characteristic. + + name: NN + The ASCII hexadecimal representation + of the SHA256 checksum of the pathname + of the file that is pre-pended with + the little-endian binary value of the + length of the pathname. + + s_magic: 0xNN + The ASCII base 16 representation of the + magic number of the filesystem that + contains the file. + + s_id: NAME + The ASCII name of the block device for + the filesystem that contains the file. + + s_UUID: HEX + The ASCII base 16 representation of + the hexadecimal value of the UUID of + the filesystem that contains the file. + + digest: HEX + The ASCII base 16 representation of + the SHA256 digest of the file. + + If the event type is the memory mapping of a file a + mmap_file key value will be included with + the following characteristics: + + type: N + Where N is an ASCII 0 or 1 to indicate + whether or not the mapping is file + backed or anonymous. A value of 1 is + used to indicate an anonymous mapping. + + reqprot: NN + Where N is ASCII base 10 + representation of the protections + requested for the mapping. + + prot: NN + Where N is the ASCII base 10 + representation of the protections that + will be applied to the mapping. + + flags: NN + Where N is the ASCII base 10 + representation of the flags that will + be used for the memory mapping operation. + + If the event type is a socket creation event a + socket_create key value will be included with the + following characteristics: + + family: N + Where N is the ASCII base 10 + representation of the family type of + the socket. + + type: N + Where N is the ASCII base 10 + representation of the type of socket + being created. + + protocol: N + Where N is the ASCII base 10 + representation of the protocol family + for the socket. + + kern: 0 | 1 + Where 0 or 1 is used to indicate + whether or not the socket is kernel + based. A value of 1 implies it is + kernel based. + + If the event type is a socket_connect or a + socket_bind, a socket_connect: or a socket_bind: key + value will be included that will be characterized + based on an encoding of either an IPV4, IPV6, AF_UNIX + or a generic socket description. + + family: N + Where N is the ASCII base 10 + representation of the family type of + the socket. + + port: N + Where N is the base ASCII base 10 + representation of the port number that + is being used for either an IPV4 or + IPV6 socket connection or bind. + + addr: N | PATH | HEXID + In the case of an IPV4 socket the + value for the addr key will be the + ASCII base 10 representation of the 32 + bit IPV4 address being bound or + connected to. + + In the case of an IPV6 connection the + value to the key will be the ASCII + base 16 representation of the 128 bit + address being bound connected. + + In the case of an AF_UNIX connection + the value will be the pathname of the + socket in the mount namespace that the + process is running in. + + In the case of any other type of + socket the addr value will be the + ASCII base 16 representation of the + cryptographic digest value of the + entire length of the address + description. The length of the + representation will be the size of the + digest produced by the cryptographic + hash function that has been specified + for the modeling namespace. + + flow: N + For an IPV6 socket the value of the + flow key will be the ASCII base 10 + representation of the flow identifier + assigned to the socket. + + scope: N + For an IPV6 socket the value of the + scope key will be the ASCII base 10 + representation of the scope identifier + assigned to the socket. + + If the event type is a socket_accept a socket_accept + key value will be included that characterizes either + an IPV4, IPV6 or a generic socket description with the + following event descriptions: + + family: N + Where N is the ASCII base 10 + representation of the family type of + the socket. + + type: N + Where N is the ASCII base 10 + representation of the type of the + socket being created. + + port: N + Where N is the base ASCII base 10 + representation of the port number that + is being used for either an IPV4 or + IPV6 socket connection or bind. + + addr: N | PATH | HEXID + In the case of an IPV4 socket the + value for the addr key will be the + ASCII base 10 representation of the 32 + bit IPV4 address being bound or + connected to. + + In the case of an IPV6 connection the + value to the key will be the ASCII + base 16 representation of the 128 bit + address being bound connected. + + In the case of an AF_UNIX connection + the value will be the pathname of the + socket in the mount namespace that the + process is running in. + + In the case of any other type of + socket the addr value will be the + ASCII base 16 representation of the + cryptographic digest value of the + entire length of the address + description. The length of the + representation will be the size of the + digest produced by the cryptographic + hash function that has been specified + for the modeling namespace. + +What: ROOTDIR/trajectory_coefficients +Date: July 2023 +Contact: Greg Wettstein <greg@enjellic.com> +Description: + The trajectory_coefficients file will output the ASCII + base16 representation of each security state + coefficient that has been generated by the security + modeling namespace of the calling process. + + The length of each point will be the ASCII + representation of the size of the cryptographic hash + function that has been specified for the model. + +What: ROOTDIR/trajectory_counts +Date: July 2023 +Contact: Greg Wettstein <greg@enjellic.com> +Description: + The trajectory_coefficients file will output the ASCII + base10 representation of the number of times each + security state coefficient has been generated by the + security modeling namespace of the calling process. + +What: ROOTDIR/forensics +Date: July 2023 +Contact: Greg Wettstein <greg@enjellic.com> +Description: + The forensics file contains the descriptions of + security events that are inconsistent with the + security model that the security namespace is + implementing. Forensics events are generated after a + security model is 'sealed' and the events represent + security state coefficients that have not already been + generated by the model. + + The format of lines in this file are identical to the + output generated by the ROOTDIR/trajectory file + that is documented above. + +What: ROOTDIR/forensics_coefficients +Date: July 2023 +Contact: Greg Wettstein <greg@enjellic.com> +Description: + The forensics_coefficients file will output the ASCII + base16 representation of each security state + coefficient that have been generated by forensics + events in the security modeling namespace of the + calling process. + + The length of each point will be the ASCII + representation of the size of the cryptographic hash + function that has been specified for the model. + +What: ROOTDIR/forensics_counts +Date: July 2023 +Contact: Greg Wettstein <greg@enjellic.com> +Description: + The forensics_counts file will output the ASCII base10 + representation of the number of times each security + state coefficient, generated by a forensics event, has + been generated by the security modeling namespace of + the calling process. + +What: /sys/kernel/security/tsem/ExternalTMA +Date: July 2023 +Contact: Greg Wettstein <greg@enjellic.com> +Description: + The ExternalTMA directory is a container directory + that hold files that will be used to export the + security events, and their associated parameters, for + externally modeled security modeling namespaces. + + The files created in this directory will be named by + the base 10 ASCII representation of the id value + assigned to the security modeling namespace. See the + documentation for the /sys/kernel/security/tsem/id + file in this documentation for more details on this + value. + + This file will is a read-only file that can be polled + by a userspace trust orchestrator implementation to + process security events that are to be modeled by an + external Trusted Modeling Agent. + + Each exported event is a JSON encoded record + describing the event that is to be processed. + + Each record will have an 'export' key that has a + structure associated with it that has a 'type' key in + it. The 'type' key has a string value associated with + it that defines the type of event that is being + processed. + + The following export 'type' strings are defined: + + aggregate: + The aggregate key has an associated structure + value that defines a key named 'value' that + has a string value associated with it that + represents the hardware aggregate for the + platform. + + The hardware aggregate string is expressed as + the ASCII base16 representation of the + platform hardware aggregate value. The length + of the string will be the size of the digest + produced by the cryptographic hash function + that has been specified for the security + modeling namespace of the process generating + the event. + + async_event: + If the type of the export is async_event there + will be a key named 'event' that has a structure + value associated with it. + + The structure associated with the 'event' key + will be identical to the structure generated + for the 'event' key that is described below. + + event: + If the type of the export is event there will + be a key named 'event' that has a structure + value associated with it that contains the + follow key: value pairs. + + pid: NNN + Where the NNN is the ASCII base 10 + value of the id of the process that is + executing the security event that will + be modeled. + + process: COMM + Where COMM is the ASCII representation + of the name of the process executing + the event. + + type: EVENT_TYPE + The value field for a type key is the + name of the security event that is + being modeled. The list of EVENT_TYPE + names is defined in the following + source file: + + security/tsem/tsem.c + + If the security event is a generically + modeled event the EVENT_TYPE will be + generic_event. In this case the CELL + characteristics for the event will be + described by a generic_event: key + + task_id: HEXID + The value of the task_id key will the + ASCII base 16 representation of the + identity of the task that is executing + the security handler. The length of + HEXID will match the size of the + digest value of the cryptographic hash + function selected for use by the + security modeling namespace. + + The following documentation file: + + Documentation/admin-guide/LSM/TSEM.rst + + Describes how the TASK_ID value is + generated. + + There will be a COE key that references a + value structure that has the same format as + the COE key that is emitted for a trajectory + or forensics event. + + The record will have a key value that is + identical to the value associated with the + 'type' key documented above. The 'type' key + will have a structure value that contains a + definition of the event. The definitions for + the event will be identical to the description + of the event that is emitted for a trajectory + or forensics event in the internal TMA + implementation. + + log: + An export type of log is emitted when an + untrusted task attempts to execute a security + event. + + There will be a 'log' key in the record that + references a structure containing the + following key values: + + process: COMM + The process key has a string value + associated with it that will contain + the COMM name of the untrusted process + that invoked processing of the + security event. + + event: NAME + The event key has a string value + associated with that will contain the + name of the security event hook that + was called by an untrusted process. + + The names for the security events are + defined in the following source file: + + security/tsem/tsem.c + + action: TYPE + The action key has a string value that + describes the action take by the TSEM + security hook in response to being + called by an untrusted process. + + This string value will be either LOG + or DENY. diff --git a/Documentation/admin-guide/LSM/index.rst b/Documentation/admin-guide/LSM/index.rst index a6ba95fbaa9f..cebd3b02598d 100644 --- a/Documentation/admin-guide/LSM/index.rst +++ b/Documentation/admin-guide/LSM/index.rst @@ -47,3 +47,4 @@ subdirectories. tomoyo Yama SafeSetID + tsem diff --git a/Documentation/admin-guide/LSM/tsem.rst b/Documentation/admin-guide/LSM/tsem.rst new file mode 100644 index 000000000000..3810dd3b6e6d --- /dev/null +++ b/Documentation/admin-guide/LSM/tsem.rst @@ -0,0 +1,1526 @@ +==== +TSEM +==== + + "This is the story of the wine of Brule, and it shows what + men love is never money itself but their own way, and + that human beings love sympathy and pageant above all + things." + - Hilaire Belloc + The Path to Rome + +TSEM is the Trusted Security Event Modeling system. TSEM is the +kernel infrastructure that provides a platform for implementing +security policies based on either deterministic or machine learning +models. It also provides a framework for implementing Host Based +Intrusion Detection (HIDS) and anomaly detection without the need to +write kernel code or implement kernel loadable modules + +The design and implementation of TSEM is inspired by the notion that +the security behavior of a platform, or a workload, like all other +physical phenomenon, can be mathematically modeled. + +Security, is at once, both a technical and economic problem. One of +the objectives of TSEM is to address inherent and structural economic +barriers to security, by introducing technology that reduces the skill +and time needed to implement a level of security, equivalent to what +can be achieved by mandatory access controls, through unit testing of +an application stack. + +A second objective is to reduce the skill, complexity and +infrastructure needed to create trusted and remotely attestable +platforms and/or workloads. + +To achieve these objectives, TSEM implements the concept of a security +modeling namespace that reduces the complexity of a security model and +allows it to be scoped to the level of a single process hierarchy or a +container. + +TSEM is the Linux kernel component of a security concept introduced by +the Quixote Project, the notion of a Trust Orchestration System (TOS). +The concept of a TOS is to have a system with a minimal Trusted +Computing Base (TCB) that supervises and maintains subordinate +security modeling namespaces in a known state of trust. + +TSEM is implemented as a Linux Security Module (LSM) and is designed +to be self-contained with little or no dependency on kernel +infrastructure, other than the LSM hooks themselves. It can be +stacked in any order with existing LSM's. It is implemented as the +first LSM in the call sequence since it provides infrastructure that +can be used, for example, to validate extended attributes that may be +used by subsequently invoked LSM's. + +TSEM implements its equivalent of mandatory access controls, without a +requirement for extended attributes, filesystem labeling or the need +to protect filesystem metadata against offline attack. A mathematical +defined security model, generated by unit testing of a workload, is the +entity that carries the security guarantee for system or workload. + +TBDHTTRAD +========= + +A quick summary for those interested in experimenting with trust +orchestration and security modeling but are constrained by: 'Too Busy +Don't Have Time To Read Any Documentation'. + +A kernel with TSEM support in its list of enabled LSM's must be +available for use. A TSEM enabled kernel will have the tsem keyword +in the following file: + +/sys/kernel/security/lsm + +For experimentation, or integrating TSEM modeling into a Continuous +Integration/Continous Development (CI/CD) workflow, modeling +can be restricted to subordinate security namespaces by booting a kernel +with the following kernel command-line option: + +tsem_mode=1 + +This disables modeling of the root security namespace and only +implements modeling for subordinate namespaces. + +The Quixote trust orchestration utilities either need to be built or +the statically compiled sample utilities need to be installed. Source +for the userspace utilities and compiled sample programs are available +at the following location: + +ftp://ftp.enjellic.com/pub/Quixote + +After installing the utilities, two shell sessions will be needed with +root privileges in each shell. + +The following directories need to be in the PATH variable of each shell: + +/opt/Quixote/sbin +/opt/Quixote/bin + +Execute the following command to start a process in an independent +security namespace with the modeling being done in the kernel: + +quixote -P -c test -o test.model + +In the second shell session, run the following command to display the +security execution trajectory of the model: + +quixote-console -p test -T + +In the shell session provided by the trust orchestrator, run the +following command: + +grep SOME_STRING /etc/passwd + +Then exit the shell. + +The orchestrator will indicate that the security model definition has +been written to the test.model file. + +Run the following command to execute a shell in an enforced security +model obtained from the previous session: + +quixote -P -c test -m test.model -e + +In the shell that is provided, run the following command: + +cat /etc/passwd + +The command will fail. + +Running the following command in the second shell session will output +forensics on the command that failed: + +quixote-console -p test -F + +Executing additional commands in the trust orchestrated shell will +cause additional entries to be added to the forensics trajectory. + +The test can be repeated using the quixote-us trust orchestrator. +This test will model the security namespace in a userspace process +rather than in the kernel based trusted modeling agent. + +Mandatory Access Controls +========================= + + "If I have seen further it is by standing on the shoulders of + Giants." + - Sir Isaac Newton + +It is assumed that astute readers will be familiar with classic +subject/object based mandatory access controls; or at least astute +enough to use a search engine to develop a modicum of secundem artem +in the discipline. + +Very simplistically, subject/object based mandatory access controls +can be thought of as being implemented with a two dimensional access +vector matrix, with some type of a description of a process (subject) +on one axis and a description of a data sync/source (object), +typically an inode, on the second axis. The descriptions are +commonly referred to as subjects and objects. + +A security policy is developed that assigns a boolean value for each +element of the matrix that specifies whether or not permission should +be granted for the subject to access the object. + +These schemes are frequently referred to as 'mandatory access +controls', since only the kernel has the ability to implement the +labeling and decision processes. In these systems, the root or +administrative user has no ability to affect kernel decision making +with respect to whether or not permission is granted or denied. + +These systems were derived from governmental and military information +classification systems and are capable of delivering security +guarantees appropriate to classified and high sensitivity assets. The +delivery of these security guarantees comes with it a reputation for +complexity and fragility. + +Development of a system wide security policy is a complex process and +administration of such systems is frequently done in an iterative +fashion. The system is monitored for permission denials with +modifications to correct these false denials folded back into the +policy. In many cases, mandatory access control systems are run in +warning rather than enforcing mode and used as an indicator for +potential security violations. + +One of the additional challenges is that the integrity of labels is +fundamental to the ability of these systems to deliver their security +guarantees. This requires that the labeling process be conducted +under security controlled conditions, with the labels subsequently +protected against offline modification by cryptographic integrity +guarantees. + +Mandatory access controls had their origin in centralized multi-user +platforms, and before the now widely accepted, strategy of using +resource compartmentalization (namespaces) to isolate applications +from each other and the system at large. A legitimate technical +argument can be made as to whether or not enforcement of a system wide +security policy is suitable for these environments. + +At the other end of the spectrum, in embedded systems, structural +economic barriers incent very little attention to security, where time +to market is the primary goal. These systems are pushed into the +field, many time for multi-year operational lifetimes, with little +prospect for upgrades or any notion of an iterative tuning process of +a security policy. + +Security Event Modeling +======================= + + "We can no longer speak of the behavior of the particle + independently of the process of observation. As a final + consequence, the natural laws formulated mathematically in + quantum theory no longer deal with the elementary particles + themselves but with our knowledge of them. Nor is it any + longer possible to ask whether or not these particles exist in + space and time objectively ... When we speak of the picture of + nature in the exact science of our age, we do not mean a + picture of nature so much as a picture of our relationships + with nature. ...Science no longer confronts nature as an + objective observer, but sees itself as an actor in this + interplay between man and nature. The scientific method of + analysing, explaining and classifying has become conscious of + its limitations, which arise out of the fact that by its + intervention science alters and refashions the object of + investigation. In other words, method and object can no longer + be separated." + - Werner Karl Heisenberg + +Security Event Modeling (SEM), is an alternative strategy to implement +the security guarantees of mandatory access and integrity controls, in +a manner that is consistent with emerging application development +strategies such as namespaces and CI/CD workflows. + +As was noted at the start of this document, the premise for SEM is +that the security behavior of a platform, or alternatively a workload, +can be modeled like any other physical phenomenon in science and +engineering. + +Inspiration for this came from the primary TSEM author/architect +having trained as a quantum chemist, conducting very early research in +the development of multi-scale modeling strategies for molecules of +size to be of interest to pharmaceutical intents. + +SEM is premised on the theory that kernel security architects have +instrumented the LSM security event hooks to be called from all +locations, with appropriate descriptive parameters, that are relevant +to the security posture of the kernel. With respect to modeling, the +security event hooks are conceptualized as representing the +independent variables of a basis set that yields a functional +definition for the security state of an execution trajectory. + +SEM can be framed in the context of classic subject/object mandatory +access controls, by the notion that a unique identity can be generated +for each element of an access vector matrix, rather than a boolean +value. In SEM, a security execution trajectory is defined by the set +of security state coefficients that a process hierarchy (workload) +generates. This execution trajectory produces a vector of identities, +whose sum in an appropriate form, yields a functional definition of +the security state of the system. + +Two subordinate identities are combined to yield a security event +state coefficient. These subordinate identities are referred to as the +Context Of Execution (COE) and the CELL, which are conceptually +similar to the subject and object in mandatory access control. The +COE identity is derived from the parameters that describe the security +relevant characteristics of a process, while the CELL value is derived +from the parameters used by a security event hook to describe the +characteristics of the event. + +A security policy is implemented by a modeling algorithm that +translates COE and CELL event parameters into their respective +identities. The COE and CELL are combined to yield a security state +coefficient that uniquely describes the security event in the security +model. Different security policies and criteria can be developed by +modifying how the modeling algorithm utilizes the COE and CELL +characteristics. + +Since the security policy is implemented with a modeling algorithm, a +single platform can support multiple and arbitrary security policies. +The equivalent of a resource namespace in SEM is referred to as a +security modeling namespace. + +The formation of the security state coefficients from existing kernel +parameters eliminates the need for the use of extended attributes to +hold security label definitions. In SEM, a cryptographically signed +security model definition, designed to be interpreted by a modeling +algorithm, becomes the bearer's token for the security of the modeled +workload, rather than information encoded in filesystem security +attributes. + +Trusted Security Event Modeling +=============================== + + "Do you see over yonder, friend Sancho, thirty or forty + hulking giants? I intend to do battle with them and slay + them." + - Don Quixote + +In TSEM, the modeling algorithm is implemented in an entity known as a +Trusted Modeling Agent (TMA), in a 'trusted' environment where +modeling is immune from modification or alteration by any activity on +the platform or in a workload. The notion of a TMA provides a +framework for next generation security co-processors that extend +functionality beyond what is defined by the concept of a Trusted +Platform Module (TPM). + +In addition to providing an attestation of an execution trajectory, a +TMA, in contrast to a TPM, has the ability to advise an operating +system on whether or not an event being modeled is consistent with the +security model that is being enforced. In this manner, it introduces +a prospective rather than a retrospective trust model. + +TSEM is designed to support Trust Orchestration Systems (TOS). In a +TOS, the trust orchestrators are supervisory programs that run +workloads in independent modeling namespaces , enforcing a workload +specific security model. Each trust orchestrator is paired with a +'trusted partner TMA', known as a Sancho, that implements the workload +specific modeling algorithm. + +The root of trust for a workload modeling namespace is based on where +the TMA instance is implemented. As an example, the Quixote TOS +implementation currently offers orchestrators for the following TMA +execution localities: + +- Kernel. + +- Userspace process. + +- SGX enclave. + +- Xen stub domain. + +- Micro-controller. + +This partitioning of trust results in the concept of security modeling +namespaces being referred to as internally or externally modeled. A +TMA implementation run in the kernel is referred to as an internally +modeled namespace; TMA's run outside of the kernel are referred to as +an externally modeled namespace. + +The TMA, regardless of locality, is responsible for processing the +characteristics that describe a security event, computing the identity +for the COE and CELL and then combining these two identities to create +a security state coefficient. With respect to modeling theory, the +coefficient is a task specific value representing the event in a +security model. + +TSEM is dispassionate with respect to the type of algorithm that is +implemented. The processing of the security event characteristics and +their conversion to security coefficients, is driven by the security +model/policy that will be implemented for the workload. The +architecture is designed to support security modeling algorithms that +are either deterministic or embrace approximations, stochastic +inference and machine learning algorithms in response to specific +workload, platform or device requirements. + +A security model, to be enforced by a trust orchestrator, is +implemented by providing the TMA with a set of security state +coefficients that are to be observed. A TMA processes the +characteristics of a security event and converts the characteristics +to a security state coefficient that is evaluated against the +coefficients provided to the TMA as the reference security model for a +workload. + +A security event that translates to one of the provided 'good' +coefficients, will cause the TMA to indicate to the trust orchestrator +that the process is to be allowed to run as a trusted process. A +security event that does not map to a known good coefficient, results +in the trust orchestrator designating that the process be labeled as +an untrusted process. + +Trust orchestrators and their associated TMA's, are designed to +support signed security models. This results in the elimination of +the requirement to verify or appraise extended attributes and other +measures currently required to protect labeled security systems +against offline attacks. + +The use of a cryptographic hash function to generate the security +coefficient results in the definition of very specific security +behaviors, that are sensitive to any variation in their +characteristics. Any offline modifications to files will result in a +coefficient that is inconsistent with a signed model provided to a +TMA. + +In order to support the development of TSEM based security models, a +TMA is designed to run in one of three separate modes, referred to as +follows: + +- Free modeling. + +- Sealed. + +- Enforcing. + +In a free modeling configuration, the TMA adds the security state +coefficient for the characteristics of a security event to the current +set of known good states. In addition, the description of the +security event is retained as a member of the security execution +trajectory for the model. This mode is used, in combination with unit +testing of a workload, to generate a security model for subsequent +enforcement. + +Placing a TMA in 'sealed' mode implies that any subsequent security +coefficients, that do not map into a known security state, are to be +considered 'forensic' violations to the security state of the model. + +This mode is designed to provide the ability to either fine tune a +model or provide early warning of a potential attempt to subvert the +security status of a workload. The characteristics of the violating +event are registered in the forensics trajectory of the model for use +in subsequent evaluation of the violating event and/or model +refinement. + +Placing a TMA model in 'enforcing' status implies that the model is in +a sealed state and any subsequent violations to the model will result +in the violating process being placed in untrusted status and a +permissions violation returned to the task invoking the security +event. + +Process and Platform Trust Status +================================= + +A fundamental concept in TSEM is the notion of providing a precise +definition for what it means for a platform or workload to be trusted. +A trusted platform or workload is one where there has not been an +attempt by a process to execute a security relevant event that does +not map into a known security state coefficient. + +The process trust status is a characteristic of the process that is +passed to any subordinate processes that are descendants of that +process. Once a process is tagged as untrusted, that characteristic +cannot be removed from the process. In a 'fruit from the poisoned +vine' paradigm, all subordinate processes created by an untrusted +process are untrusted as well. + +On entry into each TSEM security event handler, the trust status of a +process is checked before an attempt to model the event is made. An +attempt to execute a security event by an untrusted process will cause +the event, and its characteristics, to be logged. The return status +of the hook will be determined by the enforcement state of the model. +A permission denial is only returned if the TMA is running in +enforcing mode. + +If the platform running the TSEM LSM has a TPM, the hardware aggregate +value is computed at the time that TSEM is initialized. This hardware +aggregate value is the linear extension sum over Platform +Configuration Registers (PCR's) 0 through 7. This is the same +aggregate value that is computed by the Integrity Measurement +Architecture (IMA) and is the industry standard method of providing an +evaluation measurement of the hardware platform state. + +Internally modeled namespaces have the hardware aggregate measurement +included as the first event in the security model. Externally modeled +namespaces export the hardware aggregate value to the TMA for +inclusion as the first event of the model maintained by the external +TMA. + +The root security model extends each security state coefficient into a +PCR. The default PCR is 11 but is configurable through the kernel +configuration process. The use of a separate PCR from IMA allows +hardware based TSEM measurements to coexist with IMA measurement +values. This hardware measurement value is designed to allow +attestation to the hardware state that the root model is running in. + +TSEM is designed to support a philosophy where the root security +namespace will be a minimum Trusted Computing Base implementation that +will only be running trust orchestrators. Subordinate modeling +namespaces are non-hierarchical so as to decrease model complexity in +the subordinate namespaces in order to support a single functional +value describing the security status of a modeling namespace. + +The Linux TSEM Implementation +============================= + + "Sometimes the questions are complicated and the answers are + simple." + - Dr. Seuss + +The Linux TSEM implementation is deliberately simplistic and consists +of the following two generic components: + +- Modeling namespace and security event export functionality. + +- Internal trusted modeling agent. + +The modeling namespace and export functionality is designed to be +generic infrastructure that allows security namespaces to be created that +are either internally or externally modeled. The TSEM implementation +does not pose any constraints on what type of modeling can or should +be implemented in these namespaces. + +On the theory that security event handlers represent all of the +security relevant action points in the kernel, any security or +integrity model can be implemented using the TSEM infrastructure. For +example, basic IMA functionality could be implemented by a TMA that +maps the digests of files accessed, or mapped executable, by the root +user as the security state coefficients. + +A primary intent of the Linux TSEM implementation is to provide a +generic method for implementing security policy in userspace rather +than the kernel. This is consistent with what has been the historic +understanding in Linux architecture, that policy decisions should be +delegated, when possible, to userspace rather than to kernel based +implementations. + +The model is extremely simplistic; a TMA interprets a security event +and its characteristics and advises whether or not the kernel should +designate the process as trusted or untrusted after event processing +is complete. + +The following sections discuss various aspects of the infrastructure +used to implement this architecture. + +Internal vs external modeling +----------------------------- + +When a TSEM modeling namespace is created, a designation is made as to +whether the namespace is to be internally or externally modeled. + +In an internally modeled namespace, the security event handlers pass the +event type and its characteristics to the designated internal trusted +modeling agent. The agent provides the permission value for the +security event handler to return as the result of the event and sets +the trust status of the process executing the event. + +In an externally modeled namespace, the event type and parameters are +exported to userspace for processing by a trust orchestrator with an +associated TMA. The trust orchestrator communicates the result of the +modeling back to the kernel to support the setting of the process +trust status. + +The exception to this model are for security event handlers that are +called in atomic, ie. non-sleeping context. The export of these +security event descriptions are done asynchronously in order to avoid +having the TSEM implementation attempt to sleep in atomic context +while the userspace trust orchestrator is scheduled for execution. + +It is up to the trust orchestrator and its security policy to +determine how it handles events that violate the security model being +enforced. The Quixote trust orchestrators shut down the entire +workload running in the security namespace if an asynchronously +modeled event violates the security model being enforced and the model +is running in enforcing mode. + +Internally modeled domains are able to provide immediate interception +and modification of the trust status of a process that is violating +the security model. This has implications for the root security +namespace that is running on a system with a TPM, since the security +event coefficients are logged to the Platform Configuration Register +that is being used by TSEM. + +Issuing the TPM transaction would cause the process to attempt to +sleep while it waits for the TPM transaction to complete. In order to +address this issue the TPM transactions are deferred to an ordered +workqueue for execution. The use of an ordered workqueue maintains +the time dependency of the security coefficients being registered. + +In order to handle modeling of security events in atomic context the +TSEM implementation maintains caches (magazines) of structures that +are needed to implement the modeling and export of events. The size +of this cache can be configured independently for each individual +security modeling namespace that is created. The default +implementation is for a cache size of 16 for internally modeled +namespaces and 96 for externally modeled namespaces. + +By default the root security namespace uses a cache size of 96. This +value can be configured by the 'tsem_cache' kernel command-line +parameter to an alternate value. + +Trust Orchestrator/Process authentication +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The process identifier values (PID's) that are exported in the +security event descriptions are the unique global PID values, not the +value as seen through the lens of a PID namespace. + +PID values are, by default, not considered to be a stable identifier +between the kernel and userspace. In the case of TSEM external +modeling, the threat model for a namespace is whether or not an +adversarial process, running in either the root modeling namespace or +another subordinate modeling namespace, can kill a process that is +being orchestrated and substitute an alternate process with an +identical PID value. + +The trust orchestrator would then be deluded into setting the trust +status of the adversarial process rather than the one that had emitted +the security event characteristics. The threat interval is the +latency time required for the processing of the security event +description by the trust orchestrator and its associated TMA. + +Exploiting this theoretical race is extremely complex and requires an +in depth understanding of the TSEM architecture. Rather than discuss +the conditions that must be met and their implications, this +discussion will focus on the generic threat model and the mechanisms +that TSEM implements in order to mitigate this threat. + +In short, a process in an adversarial security modeling namespace would +want to execute security events that are barred from its security +model with the hope of having them approved by an alternate namespace. + +In order to exploit the race, an adversarial process would have to +force the termination of a process in the target namespace and then +fork and exit a process a sufficient number of times in order to have +a process under its control match the PID value of the process that +was waiting for an orchestration response. + +Measured modeling latency times for a trust orchestrator running the +deterministic Quixote TMA in userspace, on current generation 3.x +x86_64 hardware, averages 170 micro-seconds. In a worst case +scenario from the perspective of an adversary, there would be a need +to force the termination of the target process and then fork and +execute a sufficient number of times to force the PID collision +during this time interval. + +As a generic protection, TSEM in the tsem_task_kill() handler, blocks +the notion of 'cross-model' signals, ie. a signal originating from an +external modeling namespace. This would require the adversary to +reliably force a process termination through a mechanism other than +signaling, for example, through the OOM killer whose signal +transmission would not be blocked by this policy control. + +When a subordinate security modeling namespace is created, the id +number of the namespace is registered in the tsem_task structure of +the trust orchestrator that is creating the namespace. The TSEM +driver will refuse to honor control plane requests affecting the trust +status of a process whose trust orchestrator security namespace id +does not match the id of the process that it is being asked to act on. + +As an additional protection, TSEM uses an authentication strategy that +allows a process running in a security modeling namespace to verify +that a control request is coming from the trust orchestrator that +initiated the namespace the process is running in. As part of the +setup of a security modeling namespace, a trust orchestrator is +required to provide a hexadecimally encoded authentication key that +matches the length of the cryptographic hash function being used to +generate security state coefficient in the modeling namespace. This +authentication key must be provided by the trust orchestrator for +every subsequent control plane request. + +The process that is being transferred to a subordinate security +modeling namespace generates a second random key that is hashed with +the authentication key provided by the trust orchestrator, using the +hash function that has been defined for the security namespace. The +resultant digest value is compared to a list of authentication keys +for all currently executing namespaces. The selection of the second +random key is repeated until a globally unique key is generated. + +This randomly generated authentication key is stored in the tsem_task +structure of the process and propagated to any subsequent processes +that are created in the namespace. The hash product of this key and +the orchestration authentication key, ie. the globally unique key, is +placed in the tsem_task control structure of the orchestration +process. + +When a control plane request is received, the authentication key +provided by the trust orchestrator is used to re-generate an +authentication key based on the randomly generated namespace key held +by the process whose trust status is being updated and compared to the +key in the tsem_task structure of the processing issuing the +orchestration call. The control plane will refuse to honor a control +plane request if the call specific key does not match the key that was +generated at the time the security namespace was created. + +Explicit vs generic modeling +---------------------------- + +In addition to the COE characteristics, TMA's have the ability to +include the parameters that characterize the CELL of the security +event into the generation of the security state coefficient for the +event. The inclusion of specific CELL characteristics is considered +explicit modeling of the event. + +TMA's also have the ability to consider only the COE characteristics +and the type of the event. This is referred to as generic modeling of +the event. + +In the current Linux TSEM implementation, the security event handlers +differentiate, primarily due to current numerical resolution +requirements of the models being implemented, some events to be +generically modeled. For these events, in addition to the COE +characteristics and task identity, a default event specific CELL value +is used in the computation of the security state coefficient. + +As was noted in the section on 'internal vs external modeling', the +most common violation of trust is the initial execution of a binary or +access to a file. The inclusion of events, as generically modeled, +allows the capture of security behaviors that are inconsistent with a +proscribed security model, even if full characterization of the event +is not implemented. + +As a further example. If security workload unit testing has not +included the ability of the workload to issue a request for creating +and installing a BPF program, the mere request to do so is considered +sufficient to place the workload in an untrusted state. + +In the following ABI document: + +Documentation/ABI/testing/tsemfs + +Documentation for the following control plane interface: + +/sys/kernel/security/tsem/InternalTMA/model0/trajectory + +Documents the security event parameters that are available for +modeling by both internally and externally modeled namespaces. + +Event modeling +-------------- + +The generation of security state coefficients is a functional process +that uses a cryptographic hash function for the creation of the +various identity coefficient that make up the expression of the +security state coefficient. + +TSEM can use any cryptographic hash function available to the Linux +kernel for this purpose. The hash function to be used for a security +modeling namespace is specified as a parameter to the namespace +creation process. + +By default, the root security namespace uses SHA256. This value can +be modified through the tsem_digest kernel command-line parameter. + +Since TSEM is active before the kernel has the ability to load +modules, the root modeling domain must be a cryptographic hash +function that is statically compiled into the kernel. By default the +TSEM configuration selects for the presence of the SHA256 hash +function. + +TSEM security event modeling is based on the following functional +definition for a security event coefficient: + +Coeff = HF(HF(EVENT_ID) || TASK_ID || HF(COE) || HF(CELL)) + + Where: + Coeff = A security state coefficient that is equal + in length to the digest value of the + cryptographic hash function in use for the + modeling namespace. + + || = Concatenation operator. + + HF = Security namespace specific hash function. + + EVENT_ID = ASCII name of event. + + TASK_ID = The process specific identity of the + executable code that is initiating modeling + of the security event. + + COE = Characteristics of the context of execution + of the event. + + CELL = Characteristics of the event that is being + modeled. + +Workload or platform specific security state coefficient definitions +are generated by a TMA, using whatever COE or CELL characteristics +that are considered relevant for the model being implemented, to +determine whether or not an event should lead to the process being +considered trusted or untrusted. + +The TASK_ID component of the function above is important with respect +to the generation of the security state coefficients. The notion of a +task identity serves to link the concepts of system integrity and +security access control + +The TASK_ID is defined by the following function: + +TASK_ID = HF(HF(EVENT) || NULL_ID || HF(COE) || HF(CELL)) + + Where: + TASK_ID = The executable identity of the process + expressed as a digest value of length + equal to the cryptographic hash function + the modeling namespace is using. + + || = Concatenation operator. + + EVENT = The string "bprm_set_creds". + + NULL_ID = A buffer a set of null bytes equal to the + digest size of the hash function being + used for the namespace. + + COE = Characteristics of the context of execution + calling the bprm_creds_for_exec LSM hook. + + CELL = The characteristics of the file provided + by the linux_binprm structure passed to + the security bprm_set_creds handler. + +An informed reader will quickly conclude, correctly, that the TASK_ID +function generates an executable specific security coefficient for the +bprm_creds_for_exec security hook. The function is the same as the +standard security state coefficient; with the exception that the task +identity is replaced with a 'null id', consisting of the number of +null bytes in the digest size of the namespace specific hash function. + +One of the CELL characteristics, used in the computation of the task +identity, is the digest of the executable file. Modifying an +executable, or attempting to execute a binary not considered in the +security model, will result in an alteration of the task identity that +propagates to the generation of invalid state coefficients. + +The task identity is saved in the TSEM specific task structure and is +used to compute the state coefficients for any security events that +the task subsequently executes. As noted in the previous paragraph, +incorporating the TASK_ID into the computation of security state +coefficients results in the security state coefficient values becoming +specific to the corpus of executable code that initiated a process. +This affords a very high degree of specificity with respect to the +security models that can be implemented. + +As was demonstrated in the TBDHTTRAD section, TSEM will discriminate +the following commands as different events/coefficients in a security +model: + +cat /etc/shadow + +grep something /etc/shadow + +while read input +do + echo $input; +done < /etc/shadow + +An important, and perhaps subtle issue to note, is how these events +result in the change of process trust status. In the first two cases, +if access to the /etc/shadow file is not permitted by the operative +security model, the cat and grep process will become untrusted. + +In the third example, the shell process itself would become untrusted. +This would cause any subsequent attempts to execute a binary to be +considered untrusted events, even if access to the binary is a +permitted coefficient in the model. + +Since the modeling operates at the level of a mandatory security +control, these permission denials would occur even if the process is +running with root privilege levels. This is secondary to the notion +that security and trust status are invested in the trust orchestrator +and ultimately the TMA. + +From a hardware perspective, this is important with respect to the +notion of a TMA being a model for a successor to the TPM. From a +system trust or integrity perspective, a TPM is designed to provide a +retrospective assessment of the actions that have occurred on a +platform. A verifying party uses the TPM event log and a PCR based +summary measurement, to verify what actions have occurred on the host, +in order to allow a determination of whether or not the platform +should be 'trusted'. + +In contrast, a TSEM/TMA based system enforces, on a real time basis, +that a platform or workload remains in a trusted state. Security +relevant actions cannot be conducted unless the TMA authorizes the +actions as being trusted. + +This is particularly important with respect to embedded systems. A +TPM based architecture would not prevent a system from having its +trust status altered. Maintaining the system in a trusted state would +require attestation polling of the system, and presumably, executing +actions if the platform has engaged in untrusted behavior. + +Conversely, a trust orchestrated software implementation enforces that +a system or workload remain in a security/trust state that it's +security model was unit tested to. + +Security model functional definitions +------------------------------------- + +Previously, classic trusted system implementations supported the +notion of the 'measurement' of the system. The measurement is the +value of a linear extension function of all the security relevant +actions recorded by a trust measurement system such as IMA. + +In TPM based trust architectures, this measurement is maintained in a +PCR. A measurement value is submitted to the TPM that extends the +current measurement using the following formula: + +MEASUREMENT = HASH(CURRENT || NEW) + + Where: + MEASUREMENT = The new measurement value to be maintained + in the register for the system. + + || = Concatenation operator. + + HASH = A cryptographic hash function supported + by the TPM device. + + CURRENT = The current measurement value. + + NEW = A new measurement value to be added to + the current measurement. + +In TPM1 based systems, the HASH function was SHA1. Due to well +understood security concerns about the cryptographic vitality of this +function, TPM2 based systems provide additional HASH functions with +stronger integrity guarantees, most principally SHA related functions +with longer digest values such as SHA256, SHA384 and SM3. + +The use of a cryptographic function produces a non-commutative sum +that can be used to verify the integrity of a series of measurements. +With respect to security modeling theory, this can be thought of as a +'time-dependent' measurement of the system. Stated more simply, the +measurement value is sensitive to the order in which the measurements +were made. + +In systems such as IMA, the measurement value reflects the sum of +digest values of what are considered to be security critical entities, +most principally, files that are accessed, based on various policies. + +In TSEM based TMA's, the measurement of a modeling namespace is the +sum of the security state coefficients generated by the operative +security model being enforced. As previously noted, on systems with a +TPM, the root modeling namespace measurement is maintained by default +in PCR 11 or the PCR that was selected at kernel configuration time. + +The challenge associated with classic integrity measurements is the +time dependent nature of using a non-commutative summing function. +The almost universal embrace of SMP based hardware architectures, in +addition to standard kernel task scheduling issues, makes the +measurement values non-deterministic. This requires a verifying party +to evaluate an event log, verified by a measurement value, to +determine whether or not the system is in a security appropriate +state. + +TSEM addresses this issue by implementing a strategy designed to +produce a single functional value that represents the security state +of a model. This allows a TMA to attest to the trust/security status +of a platform or workload by signing this singular value and +presenting it to a verifying party. + +In TSEM nomenclature, this singular value is referred to as the +'state' of the model. The attestation model is to use trust +orchestrators to generate the state value of a workload by unit +testing. This state value can be packaged with a utility or container +to represent a summary trust characteristic that can be attested by a +TMA, eliminating the need for a verifying partner to review and verify +an event log. + +TMA's implement this architecture by maintaining a single instance +vector of the set of security state coefficients that have been +generated. A state measurement is generated by sorting the vector in +big-endian hash format and then generating a standard measurement +digest over this new vector. + +Any security event that generates an associated state coefficient that +is not in the model will resulted in a perturbed state function value. +That perturbed value would be interpreted by a verifying party as an +indication of an untrusted system. + +Since the TMA maintains the security event descriptions in time +ordered form, the option to provide a classic event log and +measurement are preserved and available. Extensive experience in the +development of TSEM modeled systems has demonstrated the superiority +of state value interpretation over classic measurement schemes. + +A TMA may choose to incorporate a 'base nonce' into a security model +that it is implementing, this base nonce is designed to serve in a +manner similar to an attestation nonce. If used, the trust +orchestrator is responsible for negotiating a random base nonce with a +verifying party at the time of initialization of a modeling namespace +and providing it to the TMA. + +The TMA uses the base nonce to extend each security event coefficient +that is generated by the model. This causes the state and measurement +values of the model to become dependent on this base nonce, a process +that can be used to defeat a replay attack against the security model. + +Control plane +------------- + +Both primary functions of TSEM: security modeling namespace management +and the internal TMA modeling implementation, are controlled by +pseudo-files in the securityfs filesystem. The following directory +is the top level implementation directory for the TSEM control plane: + +/sys/kernel/security/tsem + +The following file documents, in detail, the interfaces provided by +the filesystem: + +Documentation/ABI/testing/tsemfs + +This filesystem is primarily intended for use by trust orchestrators +to create and manage security modeling namespaces. + +The files are process context sensitive. Writing to the control file, +or reading from the informational files, will act on or reference the +security namespace that the accessing process is assigned to. + +The following files and directories are provided in the root directory +of the TSEM control plane and implement global controls for the TSEM +LSM: + + id + control + aggregate + +The 'id' file is used to determine the modeling namespace that the +process is running in. The namespace id value of 0 is reserved for +the root modeling namespace, a non-zero value indicates that the process +is running in a subordinate modeling namespace. + +The TSEM implementation is controlled by the only writable file, which +is the 'control' file. + +The following keywords are used by trust orchestrators to place the +process writing to the file in an internally or externally modeled +security namespace: + + internal + external + +Each argument accepts key=value pairs that configure the namespace. +The following key values are currently accepted: + + nsref + digest + cache + key + +The 'nsref' keyword takes one of the following two values: + + initial + current + +The initial argument indicates that the UID/GID values for the COE or +the CELL characteristics are derived from the initial user namespace. +This is the default characteristic if the nsref key is not specified. + +The current argument indicates that the UID/GID values are derived +from the user namespace that the process is running in, when the +request is made to model an event. + +The 'digest' keyword is used to specify the cryptographic hash +function that is to be used to create the functional values for the +security state coefficients for the namespace. The value to this +keyword is the name by which the hash function is defined by the +cryptographic API in the kernel. + +Examples of suitable strings are as follows: + + sha256 + sha3-256 + sm3 + +Definitions for the names of the cryptographic hashes can be found in +the source files for the various cryptographic hash functions in the +'crypto' directory of the Linux source tree. + +The 'cache' keyword is used to specify the size of the caches used to +hold pointers to data structures used for the modeling of security +events or the export of the security event to external trust +orchestrators. These pre-allocated structures are used to service +security event hooks that are called while the process is running in +atomic context and thus cannot sleep or allocate memory. + +The argument to these keyword is a numeric value specifying the +number of structures that are to be held in reserve for the namespace. + +By default the root modeling namespace and externally modeled +namespaces have a default value of 96 entries. An internally modeled +namespace has a default value of 16 entries. + +The 'key' keyword is used to specify the authentication key that is to +be used to support the authentication of trust control requests from a +trust orchestrator to processes running in a security modeling +namespace. The argument to this keyword is the ASCII base16 +representation of the key that is to be used. The length of the key +must be equal to the size of the digest function defined for the +namespace. + +The following keywords and arguments are used by trust orchestrators +to set the trust status of a process after the processing of a +security event by an external TMA: + + trusted pid=PID key=HEXID + untrusted pid=PID key=HEXID + + PID is the process identifier that is provided to the TMA in + the security event description. HEXID is the base16 ASCII + representation of the authentication key that the security + modeling namespace was configured with when the namespace was + created. + +By default a modeling namespace runs in free modeling mode. The modeling +mode is changed by writing the following keywords to the control file: + + seal + enforce + +The following keyword and argument are used to load a security model +into an internal modeling namespace: + + state value=HEXID + + Where HEXID is the ASCII base 16 representation of a security + state coefficient that represents a valid security event in the + model. + + After writing a series of state values the trust orchestrator + writes the 'seal' keyword to the control file to complete + creation of a security model. Writing the 'enforce' keyword + to the control file will result in that model being enforced. + + A security model for a namespace is loaded by writing the + valid security coefficients for a model file to the control + plane. This will result in the 'trajectory' file having no + event descriptions for a sealed model, since the event + description vector is only populated when a new state + coefficient is added to the model. + + Since the state state coefficients are generated with a + cryptographic hash function, the first pre-image resistance + characteristics of the function prevents a security model + description from disclosing information about the + characteristics of the workload. + +The following keyword and argument is used to set a base nonce for the +internal TMA: + + base value=HEXID + + Where HEXID is the ASCII base 16 representation of a value + that each measurement is to be extended with before being + committed as a measurement value for the model. + +The following keyword and argument is used to create a file digest +pseudonym for the internal TMA: + + pseudonym value=HEXID + + Where HEXID is the ASCII base 16 representation of a file + digest pseudonym that is to be maintained by the model. See + the ABI documentation for how the argument to this verb is + generated. + +The 'aggregate' file is used by trust orchestrators for internally +modeled namespaces to obtain the hardware measurement value for +inclusion in a security model. A trust orchestrator for an externally +modeled namespace can capture this value, since it is exported as the +first event that occurs in a security modeling namespace. + +The following two directories are implemented in the top level TSEM +control directory in order to support interfaces to internally and +externally modeled namespaces: + + ExternalTMA + InternalTMA + +The ExternalTMA directory holds a file, that is created when the +request to create an externally model security namespace is made, and +are named for the id number of the security modeling namespace. The +descriptions for security events that occur in the context of the +namespace are exported in JSON format to the external trust +orchestrator that is managing the namespace. + +The InternalTMA directory is a container directory that holds +directories for the control of each internal TMA that is implemented +in the kernel. + +There is currently only a single kernel based TMA that is managed +through the following directory: + +/sys/kernel/security/tsem/InternalTMA/model0 + +The following files are implemented for this model: + + measurement + state + + trajectory + trajectory_coefficients + trajectory_counts + + forensics + forensics_coefficient + forensics_counts + +The 'measurement' file outputs the classic linear extension value of +the security state coefficients that are generated in the context of +the security modeling namespace. This value is time dependent and can +be used to verify the order of the security events that occurred in +the model + +The 'state' file outputs a time independent functional value of +security state of the modeling namespace. This value and its +generation and motivation are discussed in the 'Security model +functional definitions' section of this document. + +The 'trajectory' file outputs the description of each security event +recorded by the model in time dependent form. The ABI documentation +file contains a complete description of the output that is generated +by this file and the 'forensics' file described below. + +The 'trajectory_coefficients' file outputs the set of security state +coefficients in the model. These coefficients are the values of the +event descriptions that are output in the 'trajectory' file. + +The 'trajectory_counts" file outputs the number of times that each +security state coefficient, output by the 'trajectory_coefficients' +file, has been experienced in the security namespace. This value can +be used to verify that a security sensitive event has occurred or for +statistical inference as to the anomaly status of the namespace. + +The 'forensics' file outputs the description of security events that +have occurred when the namespace security model is running in a sealed +state. These events are useful for characterizing a security +intrusion that has occurred or for refinement of a security model. + +The 'forensics_coefficients' file outputs the security state +coefficients that are generated by the forensics events that have +been captured by the model and available through the 'forensics' file. + +The 'forensics_counts" file outputs the number of times that each +security state coefficient output by the 'forensics_coefficients' file +has been experienced in the security namespace. This value can can be +used for statistical inference as to the anomaly status of the +namespace. + +Trust orchestrators +=================== + +In security modeling, the need for a trust orchestrator is embodied in +Heisenberg's reflections on quantum mechanical modeling. A modeled +system cannot model itself without affecting the functional value of +the security model being implemented. An external entity is needed to +setup, configure and monitor the state of a modeled system, in a +manner that does affect the state of the modeled system itself. + +After creating and configuring a security modeling namespace, the +orchestrator is responsible for executing and monitoring a process +that is run in the context of the namespace. The trust orchestrator +is also responsible for providing access to the status of the security +model being implemented by the TMA. + +Trust orchestrators for externally modeled namespaces, have an +associated TMA that is responsible for implementing the security model +for a namespace. The TMA represents the the root of trust for the +modeled namespace. The TMA advises the trust orchestrator as to what +the trust status for a process should be set to, based on the modeling +of the security event characteristics that are presented to it by the +trust orchestrator. + +In a trust orchestration architecture, secondary to their integral +role in maintaining the trust state of the system, the trust +orchestrators are the highest value security asset running on the +system. In order to support this, the Linux TSEM implementation +implements a new security capability, CAP_ML, only trust orchestrators +are designed to run with this capability. + +The CAP_ML capability is defined as a capability that allows the +ability of it's holder to use namespace creation and security modeling +to define the trust status of a system. + +Trust orchestrators are designed to drop the CAP_ML capability before +forking the process that will be responsible for launching a modeled +workload. This provides an architecture where the root of trust for +the system can be predicated on a small body of well audited +orchestration utilities, that can be linked to a hardware root of +trust implemented by a TPM or a hardware based TMA. + +Quixote +======= + + "He is awkward, past his prime and engaged in a task beyond his + capacities." + - Don Quixote's able mount Rocinante + +The Quixote Trust Orchestration System, released in concert with TSEM, +is an implementation of a trust orchestration environment that +embodies the characteristics described above. It provides all off the +basic functionality needed to build and run security architectures +based on TSEM using either internal or external TMA implementations. + +It is anticipated that Quixote would not be the only such system to +take advantage of TSEM. Given the burgeoning capability set of +systemd, it would be an architecturally valid concept to have systemd, +or other system init equivalents, gain the ability to launch critical +system services in security modeled environments. + +The source code for Quixote, and TSEM patches for some LTS kernels are +available at the following URL: + +ftp://ftp.enjellic.com/pub/Quixote + +The build of Quixote is somewhat formidable, given that it spans the +range from system programming though SGX programming and into embedded +micro-controller systems. In order to facilitate experimentation, +binaries statically compiled against MUSL libc are provided that have +virtually no system dependencies, other than a TSEM enabled kernel. + +Sample utilities +---------------- + +The Quixote TSEM implementation implements a separate trust +orchestration utility for each TMA environment, nee Sancho partner, +that is supported: + +quixote -> TMA run in the kernel for internally modeled namespaces. + +quixote-us -> TMA run in a userspace process. + +quixote-xen -> TMA run in a Xen based stub domain. + +quixote-sgx -> TMA run in an SGX enclave. + +quixote-mcu* -> TMA run in a micro-controller implementation. + +* = See discussion below. + +Each utility runs in one of two modes: process or container + +In process mode, a shell process is run as the workload process in a +modeling namespace. This mode is selected with the -P command-line +option. + +In container mode, the default, the OCI runc utility is run as the +workload process, with a 'bundle' argument that specifies a directory +that contains a JSON container definition for a directory hierarchy in +the bundle directory. The /var/lib/Quixote/Magazine directory +contains the bundle directories. + +The -c command-line option selects container mode, the argument to the +option specifies the bundle directory for the runc utility. + +In order to support the creation of security models, each utility +supports the -o command-line option to specify that a security model +description be output when the modeled workload terminates. The model +is written to the name of the file supplied via the command-line +option. + +If the -t command-line option is also specified, the security +execution trajectory, rather than a model consisting of security state +coefficients, is written to the output file. This trajectory +represents the description of the security events that were modeled. +This trajectory can be converted to security state coefficients with +the generate-states utility that is also provided in the utilities +package. + +The -m command-line option is used to specify a model that is to be +loaded into the TMA and optionally enforced. By default the security +model output with the -o command-line option will place the TMA in a +sealed modeling state. Any security events that are non-compliant +with the model will be registered as forensics events. + +Adding the -e command-line option, with the '-m FILENAME' option, will +cause the loaded model to be enforced. Any forensic events will cause +a permission denial to be returned to the caller of a TSEM LSM hook +implementation. + +The Quixote package also includes the quixote-console utility, for +interrogating the model state of both external and internal TMA's. +The following command-line options request output of the following +characteristics of the model: + +-C -> The current execution trajectory coefficient counts. + +-E -> The log of denied events. + +-F -> The current forensics execution trajectory. + +-M -> A definition for the current security model. + +-P -> The current security state coefficients. + +-S -> The state value of the model. + +-T -> The current security execution trajectory. + +Executing the utility, without these arguments, will cause a +command-line version of the utility to be presented that takes the +following arguments: + +show trajectory + +show coefficients + +show counts + +show forensics + +show forensics_coefficients + +show forensics_counts + +show state + +show model + +quit + +It is important to note that any of the values output, represent the +current state of the model and do not reflect a cumulative model of +the workload. Capturing a complete workload model requires the use of +the -m command-line argument to the trust orchestrators to capture a +model that is representative of the entire execution trajectory of the +workload after it completes. + +As an example, the following security model definition represents the +execution and termination of a shell session run on a system with a +hardware TPM: + +aggregate de2b9c37eb1ceefa4bcbc6d8412920693d3272f30eb5ba98d51d2f898d620289 +state 97b29769580b412fbf55e326a98d6a1b97c6ebf446aaf78ea38c884e954ca5b2 +state 7c435854b4fa421175ec0a5d3ca7c156480913d85c03155ea3305afa56c9717d +state 554d9f62693d522c9a43acf40780065f99cea3d67ca629ac4eaab4e22d4e63c2 +state 1b228046c4c2e7aa14db9a29fcff6f718f4f852afbfb76c8a45af7bf0485f9ce +state 24fd04b10e2b5016e0061952f3bdea959e0fa80a55ff0f4e8e13f9f72ede7498 +state da6038511db71b08c49a838d178ed055e0b7bfc42548b4c2d71eca046e9a222e +state 94b24ad4c8902f8ecb578a702408e8458e72c0774c402c3bd09ec5f390c4d0ae +state 5ffa5a2a38f42d89ae74a6d58be8b687c1baed9746d9c6a7ae3c632a2e7c082f +state a2e309d84bd4a52466c22779a622254c65ad1208583d70113751c4624baa7804 +state e93ceb0b1bf3cd58373a9e9ab4aca11a507782bbfde395ff68f8bfaf1678ed43 +state bf42388d63887368605fac9816134bc67314762c3a97b440cc48c5a30c07fdb9 +state eaa342599d682d63be4b64e159b98f21d85f0133ef5b28588e444ad12e446bf6 +state 2b9c86bc34202504c398c2f177d1dcf807b2f267c160bf8ebda863a9b427917f +state 686fc3c958f2e4f2ce3b2c6a2cb3fff44ccc4db98869bd377b14e557a5191231 +state 613c39fd2a58413b32f448c13ea4d6bc38b77966dfc5560e39e4b37d2b2f5675 +state 70e276bfd7c20262cd9c9f5b09a922f11d16d1e3a602e8005d68e9ed6afc9b5d +state 456aaedc5c1fc63f852ee97ae9561aba2a06c416154ecb9d7a1bf9d9a8c9c064 +state 97507c4c91af4a9b34b4d66118f6cc0ba1f8b55b8bb6e623dcafe27b100aea07 +state ea635c48031f81140b3561ed2291a3b1790a302e6adf5244320593b08a5af924 +state 2fd6a4d6ea1869a193926e998fbdf855916b510257d379762f48a1df63a810d4 +state 9c4cb7ef4848be1e29f9eb35fadaf5bfdc1fa3cbb22b6407cbd31b7088257026 +state 66640cbf9ae772515070f8613182b6852bf46220df0833fbe6b330a418fad95b +state 6b0d1890cbd78c627e23d7a564e77a5ee88fb20e0662ce5e66f3727ebf75fa1d +state bd28fa43b34850591fdf6fb2aa5542f33c21c20ee91b4bc2034e199b4e09edc1 +state 04425354419e53e6e73cde7d61856ff27763c2be01934e9990c1ae9f8d2a0b6e +state 2650d86382f6404367b7fdeec07f873b67b9ce26caef09d035b4dff09fce04d5 +state df2f91f5fd84ca4621092420eaf1b0a3743b328a95e3f9e0b7b1281468462aa2 +state c730c66ecfabe99480e61a7f25962582ca7bb6f2b17983048e77adde1fe7f72b +state 0fc937b71d0067fcc2c2f37c060763de250b3142e621174ffedc1b2520cdf6fd +state 7f267400a3ccf462c77ae5129799558c2c62d8bc5b388882caec813ab4cf7b7f +seal +end + +As was previously discussed, the model should be cryptographically +secure against the elucidation of the security events that resulted in +the described security states. + +The Quixote userspace implementation also contains utilities for +generating signed versions of these security models. + +* MCU TMA's +----------- + +One of the objectives of TSEM/Quixote is to explore architectures for +trusted systems that extend beyond what is provided by the TPM model +for security co-processors. The MCU based reference implementations +allow experimentation with hardware based TMA's. + +The Quixote TSEM utilities include TMA implementations for the +following following ARM32 based micro-controller platforms: + +STM32L496 + +STM32L562 + +NRF52840-DK + +NRF52840-DONGLE + +The STM32L496 platform, in addition to the base TMA implementation, +includes support for a CAT1-M based cellular modem. This demonstrates +the ability of an external TMA to conduct remote, out-of-band, +signaling of security violations for modeled platforms/workloads and +the downloading of security models outside the context of the platform +itself. + +The STM32L562 platform is a low power MCU designed for security +focused IOT implementations. It includes hardware hashing, hardware +asymmetric encryption and Trust Zone support. + +Of primary interest may be the NRF52840-DONGLE implementation. This +is a 'USB fob' form factor board that GOOGLE uses as the basis for +their OpenSK security key implementation. This form factor allows the +development and experimentation with easily deployable hardware based +TMA implementations. + +The NRF52840-DONGLE architecture was chosen by the NLnet sponsored +'FobNail' project, that is developing a hardware based attestation +server: + +https://fobnail.3mdeb.com/ + +The Fobnail projects discusses the notion of their architecture +expanding to provide protection for a Linux system at large. +Quixote/TSEM, running on the NRF52840-DONGLE micro-controller, is a +demonstration of such an implementation. + +=============== +Closing Remarks +=============== + + "Sometimes it is the people no one can imagine anything of who + do the things no one can imagine. + - Alan Turing + +While this document is of some length and detail, it hopefully +fulfills its obligation to provide sufficient prose for the +justification of the security model that TSEM addresses, and in +combination with trust orchestrators, implements. + +The MAINTAINERS file has contact information for feedback, patches +and/or questions regarding TSEM and its reference TOS implementation. + + The Quixote Team - Flailing at the Travails of Cybersecurity + + With all due respect to Miguel de Cervantes Saavedra. + + From the glacial moraine lake country of West-Central Minnesota. + + LocalWords: TSEM Brule Hilaire Belloc attestable namespace TOS TCB LSM LSM's + LocalWords: filesystem metadata TBDHTTRAD tsem Continous workflow namespaces + LocalWords: userspace quixote secundem artem inode boolean multi incent SEM + LocalWords: analysing workflows COE TMA TPM orchestrators SGX Xen TMA's PCR's + LocalWords: IMA PCR namesapces ie workqueue PID's PID OOM ABI SHA bprm creds + LocalWords: linux binprm SMP endian tsemfs ExternalTMA HEXID pre Rocinante de + LocalWords: systemd init LTS MUSL libc xen sgx mcu OCI runc JSON eb ceefa ba + LocalWords: bcbc fbf ebf aaf ec afa acf cea eaab aa fcff afbfb af ce fd bdea + LocalWords: ede da bfc eca ecb bd ae ffa baed ceb cd aca bbfde bfaf fac bc ef + LocalWords: fdb eaa dcf ebda fc cb fff ccc dfc bfd afc aaedc ee aba bb dcafe + LocalWords: aea adf fbdf df fadaf bfdc cbb cbd cbf fbe fb fdf edc cde fdeec + LocalWords: caef dff fce eaf ecfabe adde fe fcc ffedc cdf ccf caec STM NRF DK + LocalWords: IOT USB GOOGLE OpenSK deployable NLnet FobNail Fobnail Saavedra + LocalWords: Cybersecurity hexadecimally BPF Coeff securityfs nsref UID GID sm + LocalWords: API sha crypto InternalTMA HIDS pid FILENAME diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 9e5bab29685f..0e6640a78936 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -6468,6 +6468,24 @@ with CPUID.16h support and partial CPUID.15h support. Format: <unsigned int> + tsem_mode= [TSEM] Set the mode that the Trusted Security Event + Modeling LSM is to run in. + Format: 1 + 1 -- Disable root domain modeling. + + tsem_cache= [TSEM] Define the size of the caches used to hold + pointers to structures that will be used to model + security events occurring in the root modeling + namespace that are called in atomic context. + Format: <integer> + Default: 96 + + tsem_digest= [TSEM] Define the cryptographic hash function that + will be used to create security event coefficients + for in the root modeling namespace. + Format: {name of the cryptographic hash function} + Default: sha256 + tsx= [X86] Control Transactional Synchronization Extensions (TSX) feature in Intel processors that support TSX control.
An entry was added to the ABI testing documentation to document the files in the TSEM management filesystem. The file documenting the kernel command-line parameters was updated to document the TSEM specific command-line parameters The primary TSEM documentation file was added to the LSM administration guide and the file was linked to the index of LSM documentation. Signed-off-by: Greg Wettstein <greg@enjellic.com> --- Documentation/ABI/testing/tsem | 828 +++++++++ Documentation/admin-guide/LSM/index.rst | 1 + Documentation/admin-guide/LSM/tsem.rst | 1526 +++++++++++++++++ .../admin-guide/kernel-parameters.txt | 18 + 4 files changed, 2373 insertions(+) create mode 100644 Documentation/ABI/testing/tsem create mode 100644 Documentation/admin-guide/LSM/tsem.rst