[PATCH v4 2/14] Add TSEM specific documentation.

[Paul Moore]

On Thu, Jan 16, 2025 at 11:47 PM Dr. Greg <greg at enjellic.com> wrote:
> On Mon, Jan 13, 2025 at 08:29:47PM -0500, Paul Moore wrote:
> > On Aug 26, 2024 Greg Wettstein <greg at enjellic.com> wrote:
> > >
> > > An entry was added to the ABI testing documentation to document the API
> > > definitions for the TSEM ontrol plane.
> > >
> > > The file documenting the kernel command-line parameters was
> > > updated to document the TSEM specific parameters that are
> > > implemented.
> > >
> > > The primary TSEM documentation file was added to the LSM
> > > administration guide and the file was linked to the index of LSM
> > > documentation.
> > >
> > > ---
> > >  Documentation/ABI/testing/tsem                | 2420 +++++++++++++++++
> > >  Documentation/admin-guide/LSM/index.rst       |    1 +
> > >  Documentation/admin-guide/LSM/tsem.rst        | 1680 ++++++++++++
> > >  .../admin-guide/kernel-parameters.txt         |   29 +
> > >  4 files changed, 4130 insertions(+)
> > >  create mode 100644 Documentation/ABI/testing/tsem
> > >  create mode 100644 Documentation/admin-guide/LSM/tsem.rst

...

> > > +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 in locations
> > > +before security sensitive operations are conducted, with appropriate
> > > +descriptive parameters, that are considered 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
>
> > Please define the CELL acronym here as I believe it is the first use of
> > "CELL" in this document.
>
> FWIW, CELL isn't an acronym, it is a metaphor.

My mistake.  I know how hard naming can be, so if you feel like "CELL"
is the best choice here I'm not going to object, however, I think it
is worth a mention that in our acronym heavy industry any term that is
presented in all caps is often seen as an acronym and not a metaphor.

> > > +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:
> > > +
> > > +- Security modeling namespace and security event export functionality.
> > > +
> > > +- Internal trusted modeling agent implementation.
> > > +
> > > +The security 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.
>
> > In order to keep the peace among different LSMs, we try very hard to
> > avoid language along the lines of "LSM A could be implemented by LSM
> > B".  Please refrain from such language, especially in documentation
> > that lives within the kernel.
>
> We were not suggesting superiority or replacement, our apologies to
> the community if the above would be perceived as such.

My recommendation is to simply avoid any mention of other LSMs.  Not
only does it avoid any unforeseen negative comparisons, it also
encourages the documentation to fully explain the LSM without having
to rely on an understanding of another, which could result in its own
set of problems.

> In fact, the upcoming V5 release and its associated userspace tools,
> have a proof of concept implementation of TOMOYO as a TSEM loadable
> module, as a further indication of its ability to lowering the
> barriers to the development of alternative or customized security
> architectures.

Ignoring any technical issues for a moment, I would strongly suggest
against that approach for the reasons given above.  I can appreciate
that your intent is likely to demonstrate the capabilities of TSEM,
but doing so by emulating an existing LSM sets a bad precedent and I
will not view it positively.

> > > +Internal vs external modeling
> > > +-----------------------------
> > > +
> > > +When a TSEM security 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 in this model.  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.
>
> > I understand your desire to simply pass off the non-blocking/async
> > access control hole as a security policy issue, but it seems to me
> > that this is a fundamental flaw with an externally modeled TSEM
> > namespace.  If an externally modeled namespace was configured with
> > an enforcing policy, it doesn't appear that there is a mechanism for
> > TSEM to properly enforce that policy as there is an unbounded delay
> > between the undesired access and a denial verdict being processed by
> > the kernel.
> >
> > Unless you can resolve this somehow, and I'm not sure how, I would
> > suggest dropping external/userspace trust orchestrators.  They
> > simply don't seem able to reliably implement their security
> > policies.
>
> An important issue.
>
> Some reflections on why we would, respectfully, disagree.
>
> A business assessment of the current security market suggests that the
> mindset in security has changed from prevention to detection.  TSEM is
> about providing kernel infrastructure to enable better solutions for
> the detection model.

I believe the LSM can support both the enforcement of security policy
and the observation of security relevant events on a system.  In fact
most of the existing LSMs do both, at least to some extent.

However, while logging of security events likely needs to be
asynchronous for performance reasons, enforcement of security policy
likely needs to be synchronous to have any reasonable level of
assurance.  You are welcome to propose LSMs which provide
observability functionality that is either sync, async, or some
combination of both (? it would need to make sense to do both ?), but
I'm not currently interested in accepting LSMs that provide
asynchronous enforcement as I don't view that as a "reasonable"
enforcement mechanism.

> > > +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 32 for internally modeled
> > > +namespaces and 128 for externally modeled namespaces.
> > > +
> > > +By default the root security namespace uses a cache size of 128.  This
> > > +value can be configured by the 'tsem_cache' kernel command-line
> > > +parameter to an alternate value.
>
> > I haven't looked at the implementation yet, but I don't understand
> > both why a kmem_cache couldn't be used here as well as why this
> > implementation detail is deemed significant enough to be mentioned
> > in this high level design document.
>
> TSEM does use kmem_cache allocations for all of its relevant data
> structures.
>
> The use of a kmem_cache, however, does not solve the problem for
> security event handlers that are required to run in atomic context.
> To address the needs of those handlers you need to serve the
> structures out of a pre-allocated magazine that is guaranteed to not
> require any memory allocation or sleeping locks.

This still seems somewhat suspicious as there are a couple of GFP
flags that allow for non-blocking allocations in all but a few cases,
but I'll defer further discussion of that until I get to the code.  In
my opinion, there are still enough red flags in these documentation
reviews to keep me from investing the time in reviewing the TSEM code.

Regardless, I stand by my previous comment that discussion of these
caches may be a bit more detail that is needed in this document, but
of course that is your choice.  It's a balancing act between providing
enough high level detail to satisfy users and reviewers, and producing
a document that is so verbose that the time required to properly
review it is prohibitive.

> > > +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 security modeling
> > > +namespace or another subordinate security modeling namespace, can kill
> > > +a process that is being orchestrated and substitute an alternate
> > > +process with an identical PID value.
>
> > We've talked about this previously, but given my current
> > understanding of TSEM, one of my concerns is the presence of user
> > controlled data in a TSEM security event.  This could include PIDs,
> > task->comm values, and potentially others (I haven't gone through
> > the full CELL list yet).
>
> Point one: we don't use task->comm values, or PID's, in the generative
> models.

Yet a PID is still exported to an external orchestrator.

> > > +Event modeling
> > > +--------------
> > > +
> > > +The generation of security state coefficients is a functional process
> > > +that uses a cryptographic hash function for the creation of the
> > > +individual identity mappings that contribute to the generation 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) || PTASK_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
> > > +                      security modeling namespace.
> > > +
> > > +           HF       = Security namespace specific hash function.
> > > +
> > > +           ||       = Concatenation operator.
> > > +
> > > +           EVENT_ID = The ASCII name of event.
> > > +
> > > +           PTASK_ID = The TASK_ID of the parent process of the
> > > +                      process represented by TASK_ID.
> > > +
> > > +           TASK_ID  = The process specific identity of the
> > > +                      executable code that is calling the security
> > > +                      event handler.
> > > +
> > > +           COE      = Characteristics of the context of execution
> > > +                      of the event.
> > > +
> > > +           CELL     = Characteristics of the LSM event that is being
> > > +                      modeled.
> > > +
> > > +Workload or platform specific security state coefficient definitions
> > > +are generated by a TMA, using the COE or CELL characteristics that are
> > > +considered relevant for the model being implemented.  These
> > > +coefficients are used 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) || PTASK_ID || 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 security modeling namespace is using.
> > > +
> > > +           HF        = Security namespace specific hash function.
> > > +
> > > +           ||        = Concatenation operator.
> > > +
> > > +           EVENT     = The string "bprm_committed_creds".
> > > +
> > > +           PTASK_ID  = The TASK_ID of the parent process of the
> > > +                       process whose TASK_ID is being generated.
> > > +
> > > +           NULL_ID   = A buffer 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_committed_creds LSM hook.
> > > +
> > > +           CELL      = The characteristics of the file provided
> > > +                       by the linux_binprm structure passed to
> > > +                       the security_bprm_committed_creds handler.
> > > +
> > > +An attentive reader will quickly conclude, correctly, that the TASK_ID
> > > +function generates an executable specific security coefficient for the
> > > +bprm_committed_creds security hook.  The generative function for the
> > > +TASK_ID 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.
>
> > Presumably an attacker could craft a malicious executable (or
> > influence the CELL value if it incorporates user controlled values)
> > that collides with the digest of a known and trusted application.
>
> An incredibly important issue, so apologies for a more lengthy reply
> on this issue.
>
> More precisely, the objective for an adversary would be to generate
> the same security coefficient for a specific security event type using
> an alternative ensemble of operating system relevant characteristics
> for the event.
>
> The generative functions for the COE, CELL, task identities and
> ultimately the security state coefficients, are based on industry
> standard cryptographic hash functions.  The attack scenario suggested
> above would represent a major failure in the second pre-image
> resistance characteristics of these industry standard security
> primitives.
>
> The ability to decept these security primitives, in such a manner,
> would represent a crisis for the entire technology industry.

Look around, it is happening now.  Of course the level of risk varies
tremendously based on the application and yes, the chosen hash
function.  However, given the composition of TSEM's CELL value in some
events, and the importance of a hashed event value in TSEM's
policy/model enforcement, it seems like this is something that one
would want to address.

> > > +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 = HF(CURRENT || NEW)
> > > +
> > > +   Where:
> > > +           MEASUREMENT = The new measurement value to be maintained
> > > +                         in the register for the system.
> > > +
> > > +           HF          = A cryptographic hash function supported
> > > +                         by the TPM device.
> > > +
> > > +           ||          = Concatenation operator.
> > > +
> > > +           CURRENT     = The current measurement value.
> > > +
> > > +           NEW         = A new measurement value to be added to
> > > +                         the current measurement.
> > > +
> > > +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 or memory that is mapped
> > > +executable, based on various policies.
> > > +
> > > +In TSEM based TMA's, the measurement of a security modeling namespace
> > > +is the sum of the unique security state coefficients generated by the
> > > +security model being enforced.  As previously noted, on systems with a
> > > +TPM, the root security 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 or
> > > +trusted state.
> > > +
> > > +TSEM addresses this issue by implementing a strategy designed to
> > > +produce a single functional value that represents the functional
> > > +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 functional 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 unique security state coefficients that have been
> > > +experienced in a security modeling namespace.  The state measurement
> > > +is generated by sorting the security state coefficient vector in
> > > +big-endian hash format and then generating a standard linear extension
> > > +measurement over this new vector.
>
> > There are cases where ordering of events is important when assessing
> > the security state of the system, e.g. disabling/enabling security
> > features.  In these cases where ordering is necessary to attest the
> > security state of the system, is there some middle ground, or does
> > an admin need to revert to a "classic" orderered measurement?
>
> If the time order of two security critical events is important, the
> only thing that can be done is to evalute which event occurred first.
>
> TSEM now facilitates this by including nanosecond timestamp
> measurements of when each event occurred, see the 'ts' key value in
> the JSON 'event' description structure.
>
> Someone wishing to appraise the security status of a time dependent
> TSEM model would verify that the timestamps on the two event
> descriptions are ordered properly.

In those cases I do have to wonder if most of TSEM's advantages are now lost.

> > > +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 don't disagree that working with the pre-sorted measurement is far
> > easier, I just wonder how many systems would be able to give up on
> > the event ordering to have the simplified modeling.  Surely we will
> > all have different experiences here, but I'm not sure the pre-sorted
> > measurement approach would have been acceptable in many of the
> > projects I've worked on over the years.
>
> Three general observations.
>
> Roberto's work on Integrity Digest Caches would suggest that other
> groups feel that non-temporal assessments are of value.

The integrity digest caching functionality isn't a security policy,
it's a cache that improves integrity measurements/verifications in
some use cases.  It's an implementation improvement, not a security
model.

> The 'real' world consists of shades of grey.  In earlier reviews you
> questioned why TSEM was delivering ordered as well as unordered
> measurement trajectories.  The reason we provide both is to support
> the grey world we must function in.

My argument was that TSEM was putting forth unordered measurements as
a solution to all that ails existing ordered measurement solutions, so
it made little sense to include ordered measurements if the TSEM
solution was superior.  I think the reality is that unordered
measurements look appealing on paper, and perhaps even have a few use
cases that can leverage these benefits without having to worry about
the downsides, but they aren't going to be a reasonable solution for a
large number of use cases.  This raises a question of why include
both?  The unordered approach may be novel, but is it applicable
enough to warrant the added complexity?

> > > +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 in the kernel source tree documents, in detail,
> > > +the interfaces provided by the filesystem:
> > > +
> > > +Documentation/ABI/testing/tsem
> > > +
> > > +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 modeling namespace that the accessing process is assigned to.
> > > +
> > > +The following files are provided in the root directory of the TSEM
> > > +control plane and implement global controls for the TSEM LSM:
> > > +
> > > +   aggregate
> > > +   id
> > > +   control
> > > +
> > > +The 'aggregate' file is used by trust orchestrators for internally
> > > +modeled namespaces to obtain the hardware measurement value for
> > > +inclusion in a security model.
>
> > So I'm clear on this, internally modeled namespaces still access the
> > hardware measurement directly from inside the kernel, yes?  In the
> > interally modeled case this is simply available as a reference, and
> > the in-kernel TMA doesn't call out to userspace to access this value,
> > yes?
>
> Correct.
>
> > > +A trust orchestrator for an externally
> > > +modeled namespace capture this value as the first event generated by a
> > > +security modeling namespace.
> > > +
> > > +The 'id' file is used to determine the security modeling namespace
> > > +that the process is running in.  The namespace id value of 0 is
> > > +reserved for the root security modeling namespace, a non-zero value
> > > +indicates that the process is running in a subordinate security
> > > +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:
> > > +
> > > +   model
> > > +   nsref
> > > +   digest
> > > +   cache
> > > +   key
> > > +
> > > +The 'model' keyword takes as an argument the name of a loadable module
> > > +that will be used to implement the event processing for a security
> > > +modeling namespace.  If the module has not already been loaded, TSEM
> > > +will attempt to dynamically load the module.
>
> > I'm still sorting out the stuff in the docs and haven't gotten to
> > the implementation yet, but just so we're clear on the details about
> > TSEM modules, TSEM shouldn't attempt to sidestep the LSM framework
> > as TOMOYO did recently and we later had to revert.
>
> We were active in those discussions and are on record with respect to
> supporting the notion that LSM's should not attempt to sidestep the
> LSM infrastructure.
>
> TSEM operates entirely within the LSM framework.  TSEM loadable
> modules were implemented in order to allow shaping of the event
> mapping to allow multiple types of models to be implemented.

Another area where one might question the tradeoff between complexity
and capability.

> > Considering that TSEM is likely to want to be active before enough
> > of a userspace exists to load a module (see the previous sections on
> > hash functions), it seems like the best option is to simply include
> > all of the desired internal TMAs in the kernel at build time.
>
> Our experience in building solutions in this space is to have a very
> minimal orchestration environment running in the root modeling
> namespace that sets up the host and is modeled by the default
> deterministic TMA.
>
> The orchestration environment then runs containerized workloads in
> independent modeling namespaces that benefit from the availability of
> multiple models, including the simple export of security events for
> external EDRS evaluation.
>
> > > +If the standard practice
> > > +is followed of using the KBUILD_MODNAME CPP define to set the name of
> > > +the security model, the argument to the model keyword will be that
> > > +name, a value that will match the name that is displayed by the lsmod
> > > +command.  It should be noted that there is no requirement that the
> > > +security model name match the name of the module generated by the
> > > +build process.
> > > +
> > > +The 'nsref' keyword takes one of the following two values:
> > > +
> > > +   initial
> > > +   current
> > > +
> > > +The initial argument indicates that the UID/GID values for the COE and
> > > +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 internal 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 in order to allocate memory.
> > > +
> > > +The argument to this keyword is a numeric value specifying the number
> > > +of structures that are to be held in reserve for the namespace.
> > > +
> > > +By default the root security modeling namespace and externally modeled
> > > +namespaces have a default value of 128 entries.  An internally modeled
> > > +namespace has a default value of 32 entries.  The size requirements of
> > > +these caches can be highly dependent on the characteristics of the
> > > +modeled workload and may require tuning to the needs of the platform
> > > +or workload.
>
> > Presumably TSEM provides usage statistics somewhere so admins can
> > monitor and tune as desired?  If so, it seems like it would be a
> > good idea to add a reference here.
>
> We have trended toward the Linus philosophy of reducing the need to
> worry about properly tuning knobs.

I agree that generally speaking the less tuning knobs to get wrong,
the better.  However, that assumes a system that can adjust itself as
necessary to ensure a reasonable level of operation.  If TSEM can not
dynamically adjust itself you should consider exposing those tunables.

-- 
paul-moore.com