new file mode 100644
@@ -0,0 +1,2420 @@
+This file contains descriptions of output generated by the TSEM
+control plane files and the role of the only write-only file in the
+control plane.
+
+It is highly recommended that the following document be read in order
+to fully understand the rationale and functioning of these files:
+
+Documentation/admin-guide/LSM/tsem.rst
+
+What: /sys/kernel/security/tsem
+Date: March 2024
+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: March 2024
+Contact: Greg Wettstein <greg@enjellic.com>
+Description:
+ The id file outputs the ASCII base 10 representation
+ of the security modeling namespace 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 security namespace will have a
+ file, with this id number, created in the
+ /sys/kernel/security/tsem/external_tma that is
+ documented below.
+
+What: /sys/kernel/security/tsem/aggregate
+Date: March 2024
+Contact: Greg Wettstein <greg@enjellic.com>
+Description:
+ The aggregate file contains the ASCII base 16
+ representation of the Trusted Platform Module (TPM)
+ based hardware aggregate measurement. The hardware
+ aggregate measurement is the linear extension sum,
+ using the digest function chosen for the root modeling
+ namespace, of PCR registers 0 through 8
+
+ The hardware aggregate measurement is a common concept
+ in trusted systems and is used to verify the integrity
+ and known good state of the hardware environment
+ leading up to the boot of the operating system.
+
+ The size of the measurement is equal in length to the
+ ASCII Base16 representation of the cryptographic
+ digest function being used for the root security
+ modeling namespace. For example, if the default
+ sha256 digest function is being used, the aggregate
+ measurement will be 64 ASCII hexadecimal characters.
+
+ On a platform without a TPM this value will be all
+ ASCII 0 values.
+
+What: /sys/kernel/security/tsem/control
+Date: March 2024
+Contact: Greg Wettstein <greg@enjellic.com>
+Description:
+ The control file is the only writable file in the
+ filesystem and is used by 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 namespace to be created for the
+ calling process.
+
+ external
+ The external keyword causes an externally
+ modeled namespace to be created for the
+ calling process.
+
+ A modeling namespace created by either of these
+ directives accepts the following key=value pairs that
+ configure the namespace:
+
+
+ model=MODULE_NAME
+ The model key specifies the name of a security
+ model that is to be used to conduct the event
+ processing for a security modeling namespace.
+
+ If the standard build practice of using the
+ KBUILD_MODNAME CPP define to set the name of
+ the security model the model name will match
+ the name of the module, as displayed by the
+ lsmod command. There is no requirement that
+ the security model name match the module name.
+
+ nsref=initial|current
+ The nsref key specifies the namespace that is
+ to be referenced when determining the UID/GID
+ values used to characterize a COE or CELL
+ mapping.
+
+ The initial keyword specifies that the initial
+ user namespace is to be used. The current
+ keyword specifies that the user namespace of
+ the process that is invoking a security event
+ handler is used.
+
+ The default is to use the initial user
+ namespace.
+
+ digest=digestname
+ The digest key value is used to specify the
+ cryptographic hash function that is to be used
+ for the generation of the security state
+ coefficients for the LSM events being modeled.
+
+ The digestname value 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 various cryptographic hash functions 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 namespace.
+ This can be modified by the tsem_digest
+ command-line parameter.
+
+ A hash function, used by the root modeling
+ namespace, 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
+ representation of the 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 security modeling namespace.
+
+ enforce
+ The enforce keyword causes the modeling
+ 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 specify that a process being
+ woken up after model evaluation of a security
+ event should be allowed to run in trusted
+ status.
+
+ The pid argument is used to locate the process
+ that is sleeping on the modeling event.
+
+ The HEXID argument is the authentication key
+ that was 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 specify that a process being
+ woken up after model evaluation should be
+ placed in untrusted status.
+
+ The pid argument is used to locate the process
+ that is sleeping on the modeling event.
+
+ The HEXID argument is the authentication key
+ that was configured by a trust orchestrator
+ for the namespace at the time of 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.
+
+ The HEXID value will be the length of the
+ digest value of the cryptographic hash
+ function specified for the security modeling
+ namespace.
+
+ pseudonym value=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 and || implies
+ concatenation of the byte stream fed to the
+ hash function.
+
+ 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.
+
+ lock
+ This command is only valid when loadable
+ module support is available in the kernel.
+
+ When executed this command blocks any further
+ TSEM models from being registered. In
+ addition the reference count on all currently
+ registered modeling modules is increased so
+ that it is impossible to remove currently
+ loaded models.
+
+What: /sys/kernel/security/tsem/internal_tma
+Date: March 2024
+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/internal_tma/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: March 2024
+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.
+
+ This value is similar in concept to measurement values
+ generated by TPM PCR's. In the case of TSEM, it can
+ be used to validate the order integrity of the
+ security state coefficients output in the
+ trajectory_coefficients file documented below.
+
+What: ROOTDIR/state
+Date: March 2024
+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. This value is
+ designed to be a single value that represents whether
+ or not a workload has deviated from a defined set of
+ known good behaviors.
+
+What: ROOTDIR/trajectory
+Date: March 2024
+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 keys
+ and associated values or structures that define the
+ characteristics of the event.
+
+ Examples and descriptions of the JSON structures are
+ provided at the end of this document.
+
+What: ROOTDIR/trajectory_coefficients
+Date: March 2024
+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: March 2024
+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: March 2024
+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: March 2024
+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: March 2024
+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/external_tma
+Date: March 2024
+Contact: Greg Wettstein <greg@enjellic.com>
+Description:
+ The external_tma is a container directory that holds
+ files that will be used to export JSON encoded security
+ event descriptions 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
+ obtain security events that are to be modeled by a
+ Trusted Modeling Agent implementation associated with
+ the trust orchestrator.
+
+ Each exported event is a JSON encoded record
+ describing an event that is to be externally
+ processed. The encoding for these events are included
+ below.
+
+
+JSON Security Event Description Encoding:
+
+Methodology:
+------------
+
+The security event descriptions maintained by the internal TMA and
+that are exported to external trust orchestrator's are encoded in
+JavaScript Object Notation (JSON). This section of the document will
+describe the encoding strategy that is used.
+
+An encoding strategy was used where each non-structure key value is
+encoded as a JSON string type. In the case of numeric values it is
+the responsibility of the TMA to convert the string value into an
+appropriate numeric value for the generation of the mapping values
+that contribute to a security state coefficient.
+
+The JSON string encodings for numeric values follow the conventions
+used by the strtol() and/or strtoll() functions to interpret how to
+convert a string encoded numeric value into an appropriate numeric
+binary type when the conversion function is called with the 'special'
+value of 0 for the base argument.
+
+The following nomenclature will be define the value member for numeric
+types:
+
+ 0MM: A base 8 ASCII value.
+ NN: A base 10 ASCII value.
+ 0xHEX A base 16 ASCII value.
+
+The MM, NN and HEX labels above do not imply a length of the numeric
+string but are used instead to imply that numeric digits of the
+specified type will follow.
+
+When the documentation below specifies a value name of DIGEST it is
+referring to a string value containing the base 16 hexadecimal
+encoding of a cryptographic digest value. The length of the value
+will be equal to the ASCII hexadecimal encoding length of a digest
+value for the cryptographic compression function that is in effect for
+the security modeling namespace. A DIGEST value will NOT be preceded
+by the 0x prefix for these values.
+
+A value name of ASCII implies an ASCII string.
+
+
+Event descriptions:
+-------------------
+
+Each TSEM supported LSM event handler (hook) encodes a description of
+the characteristics of an event in the following general form:
+
+{"event": {}, "COE": {}, "CELL": {}}
+
+Where the event key is used to label a structure that characterizes
+the event type. The COE key labels a structure that characterizes the
+Context Of Execution that is executing the event and the CELL key
+labels a structure that defines the characteristics of the security
+event that an LSM handler/hook is invoked with.
+
+The CELL label used above is a generic label for documentation
+purposes. The "CELL" label in an actual security event description
+will be replaced with one of the following currently supported event
+type descriptions:
+
+ task_kill
+ task_setpgid
+ task_getpgid
+ task_getsid
+ task_setnice
+ task_setioprio
+ task_getioprio
+ task_prlimit
+ task_setrlimit
+ task_setscheduler
+ task_getscheduler
+ task_prctl
+ file_open
+ mmap_file
+ file_ioctl
+ file_lock
+ file_fcntl
+ file_receive
+ unix_stream_connect
+ unix_may_send
+ socket_create
+ socket_connect
+ socket_bind
+ socket_accept
+ socket_listen
+ socket_socketpair
+ socket_sendmsg"
+ socket_recvmsg
+ socket_getsockname
+ socket_getpeername
+ socket_setsockopt
+ socket_shutdown
+ ptrace_traceme
+ kernel_module_request
+ kernel_load_data
+ kernel_read_file
+ sb_mount
+ sb_umount
+ sb_remount
+ sb_pivotroot
+ sb_statfs
+ move_mount
+ shm_associate
+ shm_shmctl
+ shm_shmat
+ sem_associate
+ sem_semctl
+ sem_semop
+ syslog
+ settime
+ quotactl
+ quota_on
+ msg_queue_associate
+ msg_queue_msgctl
+ msg_queue_msgsnd
+ msg_queue_msgrcv
+ ipc_permission
+ key_alloc
+ key_permission
+ netlink_send
+ inode_create
+ inode_link
+ inode_unlink
+ inode_symlink
+ inode_mkdir
+ inode_rmdir
+ inode_mknod
+ inode_rename
+ inode_setattr
+ inode_getattr
+ inode_setxattr
+ inode_getxattr
+ inode_listxattr
+ inode_removexattr
+ inode_killpriv
+ tun_dev_create
+ tun_dev_attach_queue
+ tun_dev_attach
+ tun_dev_open
+ bpf
+ bpf_map
+ bpf_prog
+ ptrace_access_check
+ capable
+ capget
+ capset
+
+
+Event encoding:
+---------------
+
+The 'event' label encodes a value structure of the following form:
+
+ "event": {
+ "context": "NN",
+ "number": "NN",
+ "process": "ASCII",
+ "type": "ASCII",
+ "ttd": "NN",
+ "p_ttd": "NN",
+ "task_id": "DIGEST",
+ "p_task_id": "DIGEST",
+ "ts": "NN"
+ {
+
+Where the value type for the individual keys is as follows:
+
+ context: A 64-bit numeric value representing the identity
+ number of the security modeling namespace that
+ generated the event.
+
+ number: A 64-bit numeric value representing the sequence
+ number of the event in the security modeling
+ namespace that generated the event.
+
+ process: The name of the process (current->comm) that
+ is invoking the security handler.
+
+ type: One of the security event description names
+ noted above.
+
+ ttd: A 64-bit numeric value incremented each time
+ a TASK_ID is generated by the bprm_committed_creds
+ handler. This value is used to separate unique
+ invocations of an executable corpus of code.
+
+ p_ttd: The ttd value of the parent process of the process
+ generating the event. This value and the ttd
+ value can be used to reproduce the order of
+ execution of executable code on a platform or
+ in a security modeling namespace.
+
+ task_id: The TASK_ID of the process executing the event.
+
+ p_task_id: The TASK_ID of the parent process of the process
+ executing the event.
+
+ ts: The timestamp for when the security event occurred.
+ The timestamp value is in monotonic nanoseconds
+ since the hardware platform was booted.
+
+
+Context Of Execution encoding:
+------------------------------
+
+The 'COE' label encodes a structure of the following form:
+
+ "COE": {
+ "uid": "NN",
+ "euid": "NN",
+ "suid": "NN",
+ "gid": "NN",
+ "egid": "NN",
+ "sgid": "NN",
+ "fsuid": "NN",
+ "fsgid": "NN",
+ "capeff": "0xHEX"
+ }
+
+ Which describes the credentials of the process that is
+ executing the event. The reference for the numeric values of
+ the discretionary access control values is either the initial
+ user namespace or the user namespace that the security
+ modeling namespace is running in.
+
+ The namespace reference is a selectable feature when the
+ security modeling namespace is created. The root security
+ modeling namespace always uses the initial user namespace.
+
+ It is assumed that anyone developing security models will be
+ familiar with the common definitions for the uid, gid
+ etc. labels.
+
+ The 'capeff' label is the effective capability set possessed
+ by a process when the security event is executed.
+
+
+CELL (event description) encoding:
+----------------------------------
+
+The 'CELL' label encodes multiple different structures depending on
+the security event that is being encoded. An understanding of the
+various LSM security event hooks and their arguments is recommended
+prerequisite for anyone wishing to develop security models using these
+event descriptions.
+
+The CELL event descriptions frequently have subordinate JSON
+structures embedded in them. In some cases only a single instance of
+a structure is used for that event type, in which case the definition
+of that structure will be included inline with the description of the
+event itself.
+
+The following general event subordinate parameter descriptions are
+used:
+
+The 'creds' structure is used to define the standard discretionary
+access based security credentials for a process:
+
+ creds {
+ "uid": "NN",
+ "euid": "NN",
+ "suid": "NN",
+ "gid": "NN",
+ "egid": "NN",
+ "sgid": "NN",
+ "fsuid": "NN",
+ "fsgid": "NN",
+ "capeff": "0xHEX",
+ "securebits:" "NN"
+ }
+
+ As in the case for the COE encoding standard knowledge of
+ discretionary access controls is assumed with the capeff label
+ being previously described.
+
+ securebits: A numeric value containing bit specific fields
+ that a file capability enabled kernel will use
+ to invoke special handling of capabilities for
+ the root user id.
+
+
+The 'perm' structure is used to describe the IPC permissions for
+shared memory primitives such as shared memory regions, message
+queues, semaphores etc.:
+
+ "perm": {
+ "uid": "NN",
+ "gid": "NN",
+ "cuid": "NN",
+ "cgid": "NN",
+ "mode": "0MM",
+ "owner": "DIGEST"
+ }
+
+ uid: The user id requesting permission for access to the
+ memory area.
+
+ gid: The group id requesting permission for access to
+ the memory area.
+
+ cuid: The alternate user id requesting permission for
+ access to the memory area.
+
+ cgid: The alternate group id requesting permission for
+ access to the memory area.
+
+ mode: The permissions being requested for access.
+
+ owner: The TASK_ID of the process requesting access
+ to the memory area.
+
+
+The 'inode' structure is used to describe an inode structure used in
+a security event description:
+
+ "inode": {
+ "uid": "NN",
+ "gid": "NN",
+ "mode": "0MM,
+ "s_magic": "0xHEX",
+ "s_id": "ASCII",
+ "s_uuid": "HEX"
+ }
+
+ uid: The user id that owns the inode.
+
+ gid: The group id that owns the inode.
+
+ mode: The discretionary access control permissions
+ for the inode.
+
+ s_magic: The magic number of the filesystem that the
+ inode is in.
+
+ s_id: The informational name from the superblock
+ of the filesystem the inode is in.
+
+ s_uuid: The UUID of the filesystem the inode is in.
+
+
+The 'inode' structure is used to describe an inode structure used in
+a security event description:
+
+ "inode": {
+ "uid": "NN",
+ "gid": "NN",
+ "mode": "0MM,
+ "s_magic": "0xHEX",
+ "s_id": "ASCII",
+ "s_uuid": "HEX"
+ }
+
+
+The 'path' structure is used to describe a path definition for an
+inode:
+
+ "path": {
+ "dev": {
+ "major": "NN",
+ "minor": "NN"
+ },
+ "instance": "NN", /* Optional. */
+ "owner": "DIGEST", /* Optional. */
+ "pathname": "ASCII"
+ }
+
+ dev: A structure used to encapsulate the major and minor
+ numbers of the device that the filesystem is based
+ on. This structure will not be included if the
+ path is not on a block device.
+
+ instance: This key/value pair is only reported for an
+ inode that is created in the context of the
+ security modeling namespace that is reporting
+ the path description.
+
+ If reported, the instance value is the
+ instance count of an inode created under the
+ containing directory by the TASK_ID of the
+ process creating the inode.
+
+ owner: As with the instance key, this key/value pair
+ is only reported for an inode created in the
+ context of the security modeling namespace
+ that is reporting the path description.
+
+ If reported, the DIGEST value is the TASK_ID
+ of the process that created the inode.
+
+ pathname: The pathname of the file.
+
+
+The 'dentry' structure is used to describe a dentry argument:
+
+ "dentry": {
+ "inode": {},
+ "path": {}
+ }
+
+ inode: A JSON inode structure that describes the backing
+ inode for the dentry. In some instances a
+ dentry does not have an inode defined, in which
+ case this key/value structure will be omitted
+ from the security event description.
+
+ path: A JSON path structure describing the pathname
+ implemented by the dentry.
+
+
+The 'file' structure is used to describe a file structure used in
+a security event description:
+
+ "file": {
+ "flags": "NN",
+ "inode": {},
+ "path": {}
+ "digest": "DIGEST"
+ }
+
+ flags: The f_flags member of the file structure describing
+ how the file was opened.
+
+ inode: A structure describing the inode that is backing
+ the file. The definition of the inode structure will
+ be included after the descriptions of the inode based
+ security handlers.
+
+ path: A structure describing the path to the file.
+
+ digest: The cryptographic digest of the file. For files
+ on a pseudo-filesystem or files that are created in
+ the context of a security modeling namespace this
+ value will be the 'zero-value' digest for the
+ hash function being used in the security modeling
+ namespace.
+
+
+The 'sb' structure is used to describe a filesystem superblock.
+
+ "sb": {
+ "dev_name", "ASCII",
+ "path", {},
+ "type", "ASCII",
+ "flags", "NN"
+ }
+
+ dev_name: The device name that the filesystem is mounted
+ on.
+
+ path: A JSON path description describing where the
+ the superblock is mounted.
+
+ type: An ASCII string describing the mounted filesystem.
+
+ flags: The mount flags for the mountpoint.
+
+
+The 'sock' structure is used to describe a socket that is used in
+a security event description:
+
+ sock {
+ "family": "NN",
+ "type": "NN",
+ "protocol": "NN",
+ "owner": "DIGEST"
+ }
+
+ family: A numeric value describing the protocol family
+ that the socket is to be created for, ie. AF_UNIX,
+ AF_INET etc.
+
+ type: The type of communications the socket is to
+ be used for, ie. SOCKET_STREAM, SOCKET_DGRAM.
+
+ protocol: An optional protocol to be used with the socket.
+
+
+The 'addr' structure is used is an enclosing structure to hold
+subordinate structures that describe the address of a socket. The
+addr field will contain a subordinate structure that is specific to
+the address type:
+
+ addr {
+ "af_inet": {}
+ "af_inet6": {}
+ "af_unix": {}
+ "af_other": {}
+ }
+
+The 'af_inet' structure defines an IPV4 network address:
+
+ "af_inet": {
+ "port": "NN",
+ "address": "NN
+ {
+
+ port: The port number of the address.
+
+ address: The 32-bit IPV4 address.
+
+The 'af_inet6' structure defines an IPV6 network address:
+
+ "af_inet6": {
+ "port": "NN",
+ "flow": "NN",
+ "scope": "NN",
+ "address": "HEXID"
+ }
+
+ port: The port number of the address.
+
+ flow: The IPV6 flow specifier.
+
+ scope: The IPV6 scope designator.
+
+ address: The 128 bit IPV6 address in ASCII hexadecimal.
+
+The 'af_unix' structure a UNIX domain address:
+
+ "af_unix": {
+ "address": "ASCII"
+ }
+
+ address: The path to the filesystem object representing
+ the socket.
+
+The 'af_other' structure is used to define a socket address other
+than one of the three above:
+
+ "af_other": {
+ "address": "DIGEST"
+ }
+
+ address: The DIGEST value is the cryptographic digest
+ value over the sa_data member of the
+ sockaddr structure.
+
+
+Event Specific Encodings:
+-------------------------
+
+The 'task_kill' event models a request to send a signal to a target
+task:
+
+ "task_kill": {
+ "target": "DIGEST",
+ "sig": "NN",
+ "cross_ns": "NN"
+ }
+
+ target: The TASK_ID of the process that the signal is
+ being sent to.
+
+ sig: The number of the signal being sent.
+
+ cross_ns: A boolean flag variable of 0 or 1 indicating
+ whether or not the signal will be crossing a
+ security modeling namespace boundary.
+
+
+The 'task_setpgid' event models a request to set the process group id
+of a task:
+
+ "task_setpgid": {
+ "task": "DIGEST",
+ "source": "DIGEST"
+ }
+
+ task: The TASK_ID of the process whose process group
+ id is to be set.
+
+ source: The TASK_ID of the process whose process group
+ id the target task is to be placed into.
+
+
+The 'task_getpgid' event describes a request to obtain the process
+group id of a task:
+
+ "task_getpgid": {
+ "task": "DIGEST",
+ }
+
+ task: The TASK_ID of the process whose process group
+ id is to be obtained.
+
+
+The 'task_getsid' event describes a request to obtain the session id of
+a task.
+
+ "task_getsid": {
+ "task": "DIGEST",
+ }
+
+ task: The TASK_ID of the process whose session id is
+ to be obtained.
+
+
+The 'task_setnice' event describes a request to set the execution
+priority of a task.
+
+ "task_setnice": {
+ "task": "DIGEST",
+ "nice": "NN"
+ }
+
+ task: The TASK_ID of the process whose priority is
+ to be set.
+
+ nice: The numerical priority value to be set.
+
+
+The 'task_setioprio' event describes a request to set the io priority
+of a task.
+
+ "task_setioprio": {
+ "task": "DIGEST",
+ "ioprio": "NN"
+ }
+
+ task: The TASK_ID of the process whose I/O priority is
+ to be set.
+
+ ioprio: The numerical priority value to be set.
+
+
+
+The 'task_getioprio' event describes a request to get the io priority
+of a task.
+
+ "task_getioprio": {
+ "task": "DIGEST"
+ }
+
+ task: The TASK_ID of the process whose I/O priority is
+ to be obtained.
+
+
+The 'task_prlimit' event describes a request to get or set resource
+limits for a task
+
+ "task_prlimit": {
+ "cred": {}
+ "tcred": {}
+ }
+
+ cred: A credential structure, defined below, that
+ describes the credentials of the task that
+ is requesting the right to set resource limits
+ for a task.
+
+ tcred: A credential structure that describes the
+ credentials of the task whose resource limits
+ are to queried.
+
+
+The 'task_setrlimit' event describes a request to set a new resource
+limit for a task.
+
+ "task_setrlimit": {
+ "task": "DIGEST"
+ "new_rlim": {
+ "resource": "NN",
+ "current": "NN",
+ "max": "NN"
+ }
+ }
+
+ task: The TASK_ID of the process whose resource limit
+ is to be set.
+
+ new_rlim: A structure with the following key values that
+ describes the resource limit being set:
+
+ resource: The numeric identifier for the
+ resource being set.
+
+ current: The current numeric value of
+ the resource.
+
+ max: The new numeric value for the
+ resource.
+
+
+The 'task_setscheduler' event describes a request to set a new scheduler
+type for a task.
+
+ "task_setscheduler": {
+ "task": "DIGEST"
+ }
+
+ task: The TASK_ID of the process whose scheduler is
+ to be set.
+
+
+The 'task_getscheduler' event describes a request to obtain the type of
+process scheduler that is set for a task.
+
+ "task_getscheduler": {
+ "task": "DIGEST"
+ }
+
+ task: The TASK_ID of the process whose scheduler
+ type is to be queried.
+
+
+The 'task_prctl' event describes a request to perform a process control
+operation on the task that is executing the event.
+
+ "task_prctl": {
+ "option": "NN",
+ "arg2": "NN",
+ "arg3": "NN",
+ "arg4": "NN",
+ "arg5": "NN
+ }
+
+ option: The type of process control operation that is
+ to be performed.
+
+ arg2-5: A total of four numeric values that describe
+ the process control operation.
+
+
+The 'file_open' event describes a request to open a file.
+
+ "file_open": {
+ "file": {}
+ }
+
+ file: A structure describing the file that is to be opened.
+ This structure is used as a parameter in multiple
+ events and will be documented later.
+
+
+The 'file_ioctl' event describes a request to issue an ioctl call against
+a file.
+
+ "file_ioctl": {
+ "file": {},
+ "cmd": "NN
+ }
+
+ file: The description of the file that the ioctl call is
+ to be issued against.
+
+ prot: The numeric value of the argument specifying the memory
+ protections that are to be implemented.
+
+ flags: The flags argument specifying the type of mapping to be
+ implemented. See the mmap(2) manpage for information
+ about the protection and flags argument to the mmap
+ system call.
+
+
+The 'file_lock' event describes a request for permission to issue a
+lock operation against the specified file.
+
+ "file_lock": {
+ "file": {},
+ "cmd": "NN"
+ }
+
+ file: The description of the file that the lock is to be
+ placed on.
+
+ cmd: The numeric coding of the lock operation that is to
+ be performed.
+
+
+The 'file_fcntl' event describes a request for permission to issue a
+perform a file operation on the designated file.
+
+ "file_fcntl": {
+ "file": {},
+ "cmd": "NN"
+ }
+
+ file: The description of the file that the file operation is
+ to be conducted on.
+
+ cmd: The numeric coding of the type of file operation that
+ is to be performed.
+
+
+The 'file_receive' event describes a request for permission to receive
+an open file descriptor though an InterProcess Communications (IPC)
+call.
+
+ "file_receive": {
+ "file": {},
+ }
+
+ file: The description of the file whose file descriptor is to
+ be received.
+
+
+The 'unix_stream_connect' event describes a request for permission to
+establish a UNIX domain stream connection. This request for
+permission is for AF_UNIX sockets that are not enumerated using the
+traditional filename model.
+
+ "unix_stream_connect": {
+ "sock": {},
+ "other": "{}"
+ }
+
+ sock: A JSON socket structure describing the socket that is
+ to be connected to a second socket. A socket description
+ structure is used by other socket operations and its
+ characteristics will be documented later.
+
+ other: A JSON socket structure describing the socket that is
+ to be connected to.
+
+
+The 'unix_may_send' event describes a request for permission to send
+a datagram from an originating socket to a destination socket. This
+permission check is associated with the non-filename based sockets
+described above.
+
+ "unix_may_send": {
+ "sock": {},
+ "other": "{}"
+ }
+
+ sock: A structure describing the socket that is originating
+ the datagram.
+
+ other: A structure describing the socket that is to receive
+ the datagram.
+
+
+The 'socket_create' event describes a request for permission to create
+a networking socket.
+
+ "socket_create": {
+ "family": NN,
+ "type": "NN",
+ "protocol": "NN",
+ "kern": "NN"
+ }
+
+ family: A numeric value describing the protocol family
+ that the socket is to be created for, ie. AF_UNIX,
+ AF_INET etc.
+
+ type: The type of communications the socket is to
+ be used for, ie. SOCKET_STREAM, SOCKET_DGRAM.
+
+ protocol: An optional protocol to be used with the socket.
+
+ kern: A boolean value used to indicate whether or
+ not the socket is kernel based.
+
+
+The 'socket_connect' event describes a request for permission to
+create connect a socket to a remote endpoint address.
+
+ "socket_connect": {
+ "sock": {},
+ "addr": {}
+ }
+
+ sock: A JSON socket description of the socket making
+ the connection request.
+
+ addr: A JSON socket structure describing the connection
+ endpoint address.
+
+
+The 'socket_bind' event describes a request for permission to bind a
+socket to a network endpoint address.
+
+ "socket_bind": {
+ "sock": {},
+ "addr": {}
+ }
+
+ sock: A JSON socket description of the socket making
+ the request.
+
+ addr: A JSON address description describing the address
+ that is being bound to.
+
+
+The 'socket_accept' event describes a request for permission for a
+socket to accept a connection from a remote address.
+
+ "socket_accept": {
+ "sock": {},
+ "addr": {}
+ }
+
+ sock: A JSON socket description of the socket making
+ the request.
+
+ addr: A JSON address description of the address being
+ accepted by the socket.
+
+
+The 'socket_listen' event describes a request for permission for a
+socket to listen for a connection.
+
+ "socket_listen": {
+ "sock": {},
+ "backlog": "NN"
+ }
+
+ sock: A JSON socket description of the socket making
+ the request to listen.
+
+ backlog: The maximum number of entries that will be
+ allowed to be queued waiting for acceptance.
+
+
+The 'socket_socketpair' event describes a request for permission to
+create a pair of connected sockets.
+
+ "socket_socketpair": {
+ "socka": {},
+ "sockb": {}"
+ }
+
+ socka: A JSON socket description of the first socket in
+ the pair.
+
+ sockb: A JSON socket description of the second socket in
+ the pair.
+
+
+The 'socket_sendmsg' event describes a request for permission to
+send a message over a socket.
+
+ "socket_sendmsg": {
+ "sock": {},
+ "addr": {}"
+ }
+
+ sock: A JSON socket description of the socket sending
+ the message.
+
+ addr: A JSON address description defining the address
+ to which the message is being sent.
+
+
+The 'socket_recvmsg' event describes a request for permission to
+receive a message over a socket.
+
+ "socket_recvmsg": {
+ "sock": {},
+ "addr": {}"
+ }
+
+ sock: A JSON socket description of the socket receiving
+ the message.
+
+ addr: A JSON address description the address from which
+ the message is being received.
+
+
+The 'socket_getsockname' event describes a request for permission to
+read the address of a socket.
+
+ "socket_getsockname": {
+ "sock": {}
+ }
+
+ sock: A JSON socket description of the socket whose
+ address is to be read.
+
+
+The 'socket_getpeername' event describes a request for permission to
+read the address of the socket's peer.
+
+ "socket_getpeername": {
+ "sock": {}
+ }
+
+ sock: A JSON socket description of the socket the
+ peer address is to be obtained from.
+
+
+The 'socket_setsockopt' event describes a request for permission to
+set an option on a socket.
+
+ "socket_setsockopt": {
+ "sock": {},
+ "level": "NN",
+ "optname": "NN"
+ }
+
+ sock: A JSON socket description of the socket whose
+ options are to be set.
+
+ level: The protocol level at which the option will be
+ set.
+
+ optname: The numeric coding of the option that will be set.
+
+
+The 'socket_shutdown' event describes a request for permission to shutdown
+a socket.
+
+ "socket_shutdown": {
+ "sock": {},
+ "how": "NN"
+ }
+
+ sock: A JSON socket description of the socket that is
+ to be shutdown.
+
+ how: A numeric code specifying how send and receives
+ on the socket are to be handled by the shutdown.
+
+
+The 'ptrace_traceme' event describes a request for permission for the
+parent process to trace the process that is executing the security
+handler.
+
+ "ptrace_traceme": {
+ "source": "DIGEST"
+ }
+
+ source: The TASK_ID of the process requesting tracing
+ permissions.
+
+
+The 'kernel_module_request' event describes a request for permission
+to load a kernel module.
+
+ "kernel_module_request": {
+ "kmod_name": "ASCII"
+ }
+
+ kmod_name: The name of the kernel module being requested.
+
+
+The 'kernel_load_data' event describes a request for permission to
+load data into the kernel
+
+ "kernel_load_data": {
+ "id": "NN",
+ "contents": "NN"
+ }
+
+ id: A numeric identifier value representing the
+ type of data to be loaded.
+
+ contents: A flag variable indicating if post data
+ loading will be used.
+
+
+The 'kernel_read_file' event describes a request for permission for the
+kernel to load a file specified by userspace.
+
+ "kernel_read_file": {
+ "file": {},
+ "contents": "NN"
+ }
+
+ file: A JSON description of the file to be read.
+
+ id: A numeric identifier value representing the
+ type of data to be loaded.
+
+
+The 'sb_mount' event describes a request for permission to mount a
+filesystem.
+
+ sb_mount {
+ "dev_name": "ASCII",
+ "path": {}
+ "type": "ASCII",
+ "flags": "NN"
+ }
+
+ dev_name: The name of the device that is to be mounted.
+
+ path: A JSON path description describing where the
+ device is to be mounted.
+
+ type: The type of filesystem to be mounted.
+
+ flags: The mount flags to be implemented.
+
+
+The 'sb_umount' event describes a request to unmount a filesystem.
+
+ "sb_umount": {
+ "mnt", {},
+ "flags", "NN"
+ }
+
+ mnt: A JSON dentry structure defining the mount point
+ that is to be unmounted.
+
+ flags: A numerical value specifying the flags passed
+ to the unmount command.
+
+
+The 'sb_remount' event describes a request for permission to remount a
+filesystem.
+
+ "sb_remount": {
+ "sb": {}
+ "dentry": {},
+ "fstype": "ASCII",
+ "s_flags": "NN"
+ }
+
+ sb: A JSON superblock structure describing the
+ mountpoint that is to be remounted.
+
+ dentry: A JSON dentry structure describing the mountpoint
+ that is to be remounted.
+
+ fstype: The name of the filesystem being remounted.
+
+ s_flags: The superblock flags describing the mount.
+
+
+The 'sb_pivotroot' event describes a request for permission to pivot
+the root filesystem to a new mount point.
+
+ "sb_pivotroot": {
+ "old_path": {},
+ "new_path": {}
+ }
+
+ old_path: A JSON path structure specifying the location
+ from which the root filesystem is to be moved.
+
+ new_path: A JSON path structure specifying the location
+ to which the root filesystem is to be moved.
+
+
+The 'sb_statfs' event describes a request for permission to access
+filesystem statistics.
+
+ "sb_statfs": {
+ "dentry": {},
+ }
+
+ dentry: A JSON dentry structure describing the superblock
+ location for the request.
+
+
+The 'move_mount' event describes a request for permission to move a
+mount from one location to another.
+
+ "move_mount": {
+ "from_path": {},
+ "to_path": {}
+ }
+
+ from_path: A JSON path structure describing the location from
+ where the mount is to be moved from.
+
+ to_path: A JSON path structure describing the location to
+ where the mount is to be moved to.
+
+
+The 'shm_associate' event structure describes a request for permission
+to access an existing shared memory region.
+
+ "shm_associate": {
+ "perm": {},
+ "shmflg": "NN"
+ }
+
+ perm: A JSON IPC permissions structure describing the
+ permissions of the shared memory region.
+
+ shmflg: A numeric flag describing the shared memory
+ operations being requested.
+
+
+The 'shm_shmctl' event structure describes a request for permission to
+execute a command on a SYSV shared memory region.
+
+ "shm_shmctl": {
+ "perm": {},
+ "cmd": "NN"
+ }
+
+ perm: A JSON IPC permissions structure describing the
+ permissions of the shared memory region.
+
+ cmd: The command whose permission is to be checked.
+
+
+The 'shm_shmat' event structure describes a request for permission to
+attach to a shared memory region.
+
+ "shm_shmat": {
+ "perm": {},
+ "shmflg": "NN"
+ }
+
+ perm: A JSON IPC permissions structure describing the
+ permissions of the shared memory region.
+
+ shmflg: The shared memory attachment command being
+ requested.
+
+
+The 'sem_associate' event structure describes a request for permission
+to attach to an existing shared memory semaphore.
+
+ "sem_associate": {
+ "perm": {},
+ "shmflg": "NN"
+ }
+
+ perm: A JSON IPC permissions structure describing the
+ permissions of the semaphores that the
+ association request is being requested for.
+
+ semflg: The semaphore operations flag.
+
+
+The 'sem_semctl' event structure describes a request for permission
+to execute a control operation on a shared memory semaphore.
+
+ "sem_semctl": {
+ "perm": {},
+ "cmd": "NN"
+ }
+
+ perm: A JSON IPC permissions structure describing the
+ permissions of on the semaphore that the control
+ command is being requested on.
+
+ cmd: The semaphore command that is being requested.
+
+
+The 'sem_semop' event structure describes a request for permission to
+request an operation on a semaphore set.
+
+ "sem_semctl": {
+ "perm": {},
+ "nsops": "NN",
+ "alter": "NN"
+ }
+
+ perm: A JSON IPC permissions structure describing the
+ permissions of the semaphore set that the
+ operation is being requested on.
+
+ nsops: The number of operations to be performed.
+
+ alter: The changes that are to be made.
+
+
+The 'syslog' event structure describes a request for permission to
+access the kernel message buffers or change console logging.
+
+ "syslog": {
+ "type": NN
+ }
+
+ type: The action that is being requested.
+
+
+The 'settime' event structure describes a request for permission to
+access the kernel message buffers or change console logging.
+
+ "settime": {
+ "ts": {
+ "seconds", "NN",
+ "nsecs", "NN"
+ },
+ "tz": {
+ "minuteswest", "NN",
+ "dsttime", "NN"
+ }
+ }
+
+ ts: If the call to the security_settime handler was
+ to set the time this structure will be present.
+
+ seconds: The time in seconds to set.
+
+ nsecs: The time in nano-seconds to be set.
+
+ tz: If the call to the security_settime handler was
+ to set the timezone this structure will be present.
+
+ minuteswest: The offset of the timezone.
+
+ dsttime: A flag variable to indicate if daylight savings
+ time is to be set.
+
+
+The 'quotactl' event structure describes a request for permission to
+control manipulate filesystem quotas.
+
+ "quotactl": {
+ "cmds": "NN",
+ "type": "NN",
+ "id": "NN",
+ "sb", {}
+ }
+
+ cmds: The quota commands to be enforced.
+
+ type: The type of quota to be enforced.
+
+ id: The quota version to be enforced.
+
+ sb: A JSON superblock structure describing the
+ filesystem on which the quota command is to
+ operate on.
+
+
+The 'quota_on' event structure describes a request to enable quotas
+for a filesystem.
+
+ "quota_on": {
+ "dentry": {}
+ }
+
+ dentry: A JSON dentry description describing the
+ mountpoint that quotas are to be enabled on.
+
+
+The 'msg_queue_associate' event structure describes a request to
+access a previously defined message queue.
+
+ "msg_queue_associate": {
+ "perm": {}
+ "msgflg": "NN"
+ }
+
+ perm: A JSON IPC permissions structure describing the
+ permissions of the message queue that association
+ is being requested for.
+
+ msgflg: A numeric flag indicating the operation that is
+ being requested.
+
+
+The 'msg_queue_msgctl' event structure describes a request to execute
+a control operation on a shared memory message queue region.
+
+ "msg_queue_msgctl": {
+ "perm": {}
+ "cmd": "NN"
+ }
+
+ perm: A JSON IPC permissions structure describing the
+ permissions of the shared memory message queue
+ region that the control command is being
+ requested on.
+
+ cmd: A numeric flag indicating the control operation
+ that is to be executed.
+
+
+The 'msg_queue_msgsnd' event structure describes a request to send a
+message over a shared memory message queue.
+
+ "msg_queue_msgsnd": {
+ "perm": {}
+ "msqflg": "NN"
+ }
+
+ perm: A JSON IPC permissions structure describing the
+ permissions of the shared memory message queue
+ region that the message is being sent on.
+
+ msqflg: A numeric coding of the operation that is to
+ be performed.
+
+
+The 'msg_queue_msgrcv' event structure describes a request to receive
+a message over a shared memory message queue.
+
+ "msg_queue_msgrcv": {
+ "perm": {}
+ "target": "DIGEST"
+ "type": "NN",
+ "mode":
+ }
+
+ perm: A JSON IPC permissions structure describing the
+ permissions of the shared memory message queue
+ region that the message is being received on.
+
+ target: The TASK_ID of the process that is to receive
+ the message.
+
+ type: The type of message that is to be received.
+
+ mode: The operations flag for the message.
+
+
+The 'ipc_permission' event structure describes a request to check if
+SYSV IPC access is to be allowed.
+
+ "ipc_permission": {
+ "perm": {}
+ "target": "DIGEST"
+ "type": "NN",
+ "mode": "NN"
+ }
+
+ ipcp: A JSON IPC permissions structure describing the
+ permissions on the SYSV shared memory region that
+ is to be checked.
+
+ flag: The access permissions being requested.
+
+
+The 'key_alloc' event structure describes a request for permission to
+allocate and initialize a kernel key structure.
+
+ "key_alloc": {
+ "creds": {},
+ "flags": "NN"
+ }
+
+ creds: A JSON credentials structure describing the
+ the access controls for the key structure
+
+ flags: A numeric control constant describing how the
+ key is to be created.
+
+
+The 'key_permission' event structure describes a request for
+permission to execute a control operation on a kernel key structure.
+
+ "key_permission": {
+ "key_refs": {
+ "possessed": "NN",
+ "uid": "NN",
+ "gid": "NN",
+ "flags": "NN"
+ }
+ "creds": {},
+ "perm", "NN"
+ }
+
+ key_refs: A JSON structure describing the key to be
+ accessed.
+
+ possessed: A flag indicating whether or not the key is
+ possessed by a process.
+
+ uid: The user id that owns the key.
+
+ gid: The group id that owns the key.
+
+ flags: Flags describing the state of the key.
+
+ creds A credentials structure describing the task that
+ is requesting access to the key.
+
+ perm: The permissions that are being requested on the
+ key.
+
+
+The 'netlink_send' event structure describes the permissions that are
+to be set on a netlink socket.
+
+ "netlink_send": {
+ "sock": {},
+ "uid": "NN",
+ "gid": "NN"
+ "portid": "NN",
+ "dst_group": "NN",
+ "nsid_set": "NN",
+ "nsid": "NN"
+ }
+
+ sock: A JSON socket description structure describing
+ the socket over which the message is to be sent.
+
+ uid: The user id that the message is to be sent to.
+
+ gid: The group id that the message is to be sent to.
+
+ portid: The port identifier of the
+
+ dst_group: The destination group for the message.
+
+ nsid_set: A flag variable indicating that the nsid value
+ is valid.
+
+ nsid: The namespace identifier.
+
+
+The 'inode_create' event structure describes a request to create an
+inode.
+
+ "inode_create": {
+ "dir": {},
+ "dentry": {},
+ "mode": "0MM"
+ }
+
+ dir: A JSON inode description describing the directory
+ the inode is to be created under.
+
+ dentry: A JSON dentry description describing the location
+ where the inode is to be created.
+
+ mode: The permissions to be assigned to the inode.
+
+
+The 'inode_link' event structure describes a request to link an inode
+to a new location.
+
+ "inode_link": {
+ "old_dentry": {},
+ "dir": {},
+ "new_dentry": {}
+ }
+
+ old_dentry: A JSON dentry description describing the current
+ location of the inode.
+
+ dir A JSON inode description describing the parent
+ directory under which the inode link will be
+ created.
+
+ new_dentry: A JSON dentry description describing the location
+ of the new link.
+
+
+The 'inode_unlink' event structure describes a request to delete an
+inode.
+
+ "inode_unlink": {
+ "dir": {},
+ "dentry": {}
+ }
+
+ dir: A JSON inode structure describing the parent
+ directory from which the inode is to be removed.
+
+ dentry: A JSON dentry description describing the inode
+ to be removed.
+
+
+The inode_symlink event structure describes a request to delete an inode.
+
+ "inode_symlink": {
+ "dir": {},
+ "dentry": {},
+ "old_name": "ASCII"
+ }
+
+ dir: A JSON inode structure describing the parent
+ directory in which the link is to be created.
+
+ dentry: A JSON dentry description describing the inode
+ that is to be created as the link.
+
+ old_name: The name of the existing filename to be linked.
+
+
+The 'inode_mkdir' event structure describes a request to create an
+directory.
+
+ "inode_mkdir": {
+ "dir": {},
+ "dentry": {},
+ "mode": "0MM"
+ }
+
+ dir: A JSON inode structure describing the parent
+ directory in which the directory is to be created.
+
+ dentry: A JSON dentry description describing the directory
+ inode that is to be created.
+
+ mode: The permissions to be assigned to the new directory.
+
+
+The 'inode_rmdir' event structure describes a request to remove a
+directory inode.
+
+ "inode_rmdir": {
+ "dir": {},
+ "dentry": {},
+ }
+
+ dir: A JSON inode structure describing the parent
+ directory of the directory being removed.
+
+ dentry: A JSON dentry description describing the directory
+ inode that is to be removed.
+
+ mode: The permissions to be assigned to the new directory.
+
+
+The 'inode_mknod' event structure describes a request to remove a directory
+inode.
+
+ "inode_mknod": {
+ "dir": {},
+ "dentry": {},
+ "mode": "0MM",
+ "dev": {
+ "major": "NN",
+ "minor": "NN"
+ }
+ }
+
+ dir: A JSON inode structure describing the directory
+ under which the device node is being created.
+
+ dentry: A JSON dentry description describing the location
+ of the device node inode.
+
+ mode: The permissions to be assigned to the device node.
+
+ dev: A JSON structure describing the device node
+ characteristics:
+
+ major: The major number of the device to be
+ created.
+
+ minor: The minor number of the device to be
+ created.
+
+
+The 'inode_rename' event structure describes a request to rename an
+inode.
+
+ "inode_rename": {
+ "old_dir": {},
+ "old_dentry": {},
+ "new_dir": {},
+ "new_dentry": {}
+ }
+
+ old_dir: A JSON inode structure describing the parent
+ directory of the inode to be renamed.
+
+ old_dentry: A JSON dentry description describing the location
+ of the inode to be renamed.
+
+ new_dir: A JSON inode structure describing the parent
+ directory of the new location of the inode.
+
+ new_dentry: A JSON dentry description describing the new
+ inode location.
+
+
+The 'inode_setattr' event structure describes a request to set the
+attributes of an inode.
+
+ "inode_setattr": {
+ "dentry": {},
+ "attr": {
+ "valid": "NN",
+ "mode": "0MM",
+ "uid": "NN",
+ "gid": "NN",
+ "size": "NN
+ }
+ }
+
+ dentry: A JSON dentry structure describing the inode
+ whose characteristics are to be set.
+
+ attr: A JSON structure describing the characteristics
+ that will be set:
+
+ valid: A numeric encoding of what characteristics
+ of the inode should be set.
+
+ mode: If requested, the permissions that are to
+ be set.
+
+ uid: If requested, the new user id to be set.
+
+ gid: If requested, the new group id to be set.
+
+ size: If requested, the new size of the file.
+
+
+
+The 'inode_getattr' event structure describes a request to obtain the
+attributes of an inode.
+
+ "inode_getattr": {
+ "path": {}
+ }
+
+ path: A JSON path structure describing the path to
+ the inode whose attributes are to be retrieved.
+
+
+The 'inode_setxattr' event structure describes a request to set the
+extended attributes of an inode.
+
+ "inode_setxattr": {
+ "dentry": {},
+ "name": "ASCII",
+ "value": "BASE64",
+ "flags": "NN"
+ }
+
+ dentry: A JSON dentry structure describing the inode
+ whose extended attributes are to be set.
+
+ name: The name of the attribute to be set.
+
+ value: The value of the attribute to be set encoded
+ as a Base64 ASCII string.
+
+ flags: The operations flag for how to set the attribute.
+
+
+The 'inode_getxattr' event structure describes a request to get the
+extended attributes of an inode.
+
+ "inode_getxattr": {
+ "dentry": {},
+ "name": "ASCII",
+ }
+
+ dentry: A JSON dentry structure describing the inode
+ whose extended attributes are to be requested.
+
+ name: The name of the attribute whose value is to
+ be requested.
+
+
+The 'inode_listxattr' event structure describes a request to list the
+extended attributes attached to an inode.
+
+ "inode_listxattr": {
+ "dentry": {}
+ }
+
+ dentry: A JSON dentry structure describing the inode
+ whose extended attributes are to be listed.
+
+
+The 'inode_removexattr' event structure describes a request to remove
+an extended attributes attached to an inode.
+
+ "inode_removexattr": {
+ "dentry": {},
+ "name": "ASCII"
+ }
+
+ dentry: A JSON dentry structure describing the inode
+ whose extended attribute are to be removed.
+
+ name: The name of the extended attribute that is to
+ be removed.
+
+
+The 'inode_killpriv' event structure describes a request to remove
+privileges from an inode.
+
+ "inode_killpriv": {
+ "dentry": {}
+ }
+
+ dentry: A JSON dentry structure describing the inode
+ whose privileges are to be removed.
+
+
+The 'tun_dev_create' event structure describes a request to create a
+TUN network device.
+
+ "tun_dev_create": {
+ }
+
+ No parameters are processed for this request.
+
+
+The 'tun_dev_attach_queue' event structure describes a request to
+attach a TUN device queue.
+
+ "tun_dev_attach_queue": {
+ }
+
+ No parameters are processed for this request.
+
+
+The 'tun_dev_attach' event structure describes a request to attach to
+a TUN device.
+
+ "tun_dev_attach": {
+ "sock": {}
+ }
+
+ sock: A JSON socket description structure describing
+ the socket requesting access to the TUN device.
+
+
+The 'tun_dev_open' event structure describes a request to open a
+network TUN device.
+
+ "tun_dev_open": {
+ }
+
+ No parameters are processed for this request.
+
+
+The 'bpf' event structure describes a request to use the BPS system
+call.
+
+ "bpf": {
+ "cmd": "NN",
+ "attr": {
+ "size": "NN"
+ }
+ }
+
+ cmd: The BPF command that is being requested.
+
+ attr: A JSON structure describing the attributes for
+ the command:
+
+ size: The size of the BPF attribute description
+ that will be passed to the BPF call.
+
+
+The 'bpf_map' event structure describes a request for permission to
+access a BPF map.
+
+ "bpf_map": {
+ "map": {
+ "map_type": "NN",
+ "fmode": "NN"
+ }
+ }
+
+ map: A JSON description structure used to describe the
+ map that will be accessed.
+
+ fmode: The permissions to be used for accessing the
+ map.
+
+
+The 'bpf_prog' event structure describes a request for permission to
+access a BPF program.
+
+ "bpf_prog": {
+ "prog": {
+ "type": "NN",
+ "attach_type": "NN"
+ }
+ }
+
+ prog: A JSON description structure used to describe the
+ program that access is being requested to.
+
+ type: The type of program being described.
+
+ attach_type: The type of attachment to be used for the
+ program.
+
+
+The 'capable' event structure describes a request to check if a
+process has a specific capability.
+
+ "capable": {
+ "cap": "NN",
+ "opts": "NN"
+ }
+
+ cap: The capability being requested.
+
+ opts: The options directing how the check is to be
+ performed.
+
+
+The 'capget' event structure describes a request to return the
+capability sets that a process has.
+
+ "capget": {
+ "target": "DIGEST",
+ "effective": "0xHEX",
+ "inheritable": "0xHEX",
+ "permitted": "0xHEX"
+ }
+
+ target: The TASK_ID of the process whose capability masks
+ are to be checked.
+
+ effective: The effective capabilities of the process.
+
+ inheritable: The inheritable capabilities of the process.
+
+ permitted: The permitted capabilities of the process.
+
+
+The 'capset' event structure describes a request to set the
+capabilities of a target process.
+
+ "capset": {
+ "effective": "0xHEX",
+ "inheritable": "0xHEX",
+ "permitted": "0xHEX"
+ }
+
+ effective: The effective capabilities to be set.
+
+ inheritable: The inheritable capabilities to be set.
+
+ permitted: The permitted capabilities to be set.
+
+
+Security event export encodings:
+--------------------------------
+
+External trust orchestrator's read security events from the control
+plane file created for an externally modeled security namespace.
+
+The encoding of the event is in the following form:
+
+{"export": {}, "event": {}}
+
+Where the event structure is the previously described event structure
+with the following additional key:
+
+ pid: The process identifier (PID) of the task that
+ generated the event.
+
+ The primary TSEM documentation file documents why
+ this value can be safely used in this context.
+
+
+The 'export' structure encodes the characteristics type of the
+exported event.
+
+ "export:" {
+ "type": "ASCII",
+ "TYPE": {}
+ }
+
+The 'export' structure is a self-describing structure where the ASCII
+string that serves as the value of the 'type' key will serve as the
+key value that describes the payload structure of the event, ie. the
+TYPE key will be substituted with the ASCII string.
+
+The following payload labels are defined:
+
+ event
+ async_event
+ aggregate
+ log
+
+The event and async_event payload labels both resolve to the
+previously documented 'event' payload. The use of different labels
+for the event is to provide a means for a trust orchestrator to know
+the context that the process was running in when the event was
+generated.
+
+The 'aggregate' structure defines the hardware boot measurement
+described previously in this documentation.
+
+ "aggregate": {
+ "value": "DIGEST"
+ }
+
+ value: The hardware aggregate measurement.
+
+
+The 'log' structure is used to describe a security event that was
+requested while the task was running in untrusted status after a
+security model violating event:
+
+ "log": {
+ "process": "ASCII",
+ "event": "ASCII",
+ "action": "ASCII"
+ }
+
+ process: The process name (current->comm) that invoked
+ the event.
+
+ event: The CELL description name of the event that
+ was requested.
+
+ action: A string value indicating how the event was
+ enforced, either DENY or LOG.
@@ -47,3 +47,4 @@ subdirectories.
tomoyo
Yama
SafeSetID
+ tsem
new file mode 100644
@@ -0,0 +1,1680 @@
+====
+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 LSM based infrastructure that provides a platform for
+implementing model based mandatory access controls. TSEM is model
+agnostic and is designed to support deterministic, quasi-deterministic
+and machine learning models.
+
+TSEM also provides a framework for implementing Host Based Intrusion
+Detection (HIDS) and anomaly interdiction systems without the need to
+write kernel code or implement kernel loadable modules or BPF
+programs.
+
+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 assist in achieving these objectives, TSEM implements the concept
+of a security modeling namespace that reduces the scope and hence
+complexity of a security model and allows it to be limited to the
+level of a single process hierarchy or a container.
+
+TSEM is the Linux kernel component of a new security architecture
+introduced by the Quixote Project, the notion of a Trust Orchestration
+System (TOS). The Quixote Project provides a complete implementation
+of the userspace tools and utilities that are used in combination
+with the TSEM LSM.
+
+The Trusted Computed Base (TCB) for a platform or a subordinate
+workload is maintained and enforced by a Trust Orchestrator (TO).
+Paired with a Trust Orchestrator is a Trusted Modeling Agent (TMA)
+that maps the description of a security event into a security state
+coefficient.
+
+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 mandatory access controls, without a requirement for
+extended attributes, filesystem labeling or the need to protect
+filesystem metadata against offline attack. A mathematically defined
+security model, generated by unit testing of a workload, is the
+bearer's token that carries the security guarantee for a system or
+workload.
+
+TBDHTTRAD
+=========
+
+A quick summary for those interested in experimenting with trust
+orchestration and security modeling but are constrained by the concept
+of: '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 modeling namespaces by booting a
+kernel with the following kernel command-line option:
+
+tsem_mode=no_root_modeling
+
+This disables modeling of the root security modeling namespace and
+only implements modeling for subordinate security 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:
+
+https://github.com/Quixote-Project
+
+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 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
+similar to the subject and object in mandatory access control. The
+COE identity is derived from the parameters that describe the security
+relevant characteristics (ie. credentials) 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 such things as 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 security 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 security 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 or
+filesystem metadata 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 the following three modes:
+
+- 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
+compilation 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
+modeling namespace will be a minimum Trusted Computing Base
+implementation that will only be running trust orchestrators and any
+other infrastructure needed to support running workloads in
+subordinate security namespaces.
+
+The subordinate security modeling namespaces are designed to decrease
+model complexity in order to support a single functional value
+describing the 'known good' security state of a subordinate security
+workload. Subordinate security modeling namespaces are
+non-hierarchical, ie. a security modeling namespace cannot itself
+parent an additional security 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:
+
+- 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.
+
+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 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.
+
+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 command 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 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.
+
+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.
+
+The suggested threat model would be that the orchestrator would set
+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 first focus on the generic threat model and its
+generic utility to an adversary followed by a treatment of 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.
+
+A process waiting for the external modeling of a security event
+description can only be placed back into run state by two methods:
+reception of a fatal signal or the TRUST_PENDING status bit being
+cleared from its TSEM specific task control structure by a trust
+orchestrator.
+
+If a process being evaluated receives a fatal signal, its trust status
+will be set to untrusted and an error will be returned to the trust
+orchestrator. The error would cause a trust violation to be
+registered for the workload. In addition, the evaluation of the event
+would be terminated, so a replacement process would not receive an
+incorrect trust assessment for an event that was initiated by its
+predecessor.
+
+The second issue that limits the utility of a PID substitution attack
+is that from the point of substitution forward it would place the
+replacement process in the context of the security model that the
+trust orchestrator is enforcing. As a result, a substituted process
+would not be allowed to exhibit any security behaviors inconsistent
+with the model being enforced.
+
+If an attempt to exploit this race would be considered, 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 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 security 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 namespace identifier 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 an ASCII hexadecimally encoded authentication key
+that matches the length of a digest value of cryptographic hash
+function being used to generate security state coefficient in the
+security 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. The generated
+authentication key is compared to the key in the tsem_task structure
+of the process issuing the orchestration call. The control plane will
+refuse to honor a control plane request if the call specific key that
+is generated does not match the key generated at the time the security
+namespace was created.
+
+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.
+
+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, in contrast to standard
+digest based controls, 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.
+
+The integration of the PTASK_ID in the generation of the security
+state coefficients causes the coefficients to be dependent on the
+chain of execution of executable code. This concept generates
+extremely specific security coefficients that yield the high
+sensitivity of TSEM based security models.
+
+For example, consider the following chain of execution:
+
+init/systemd -> sshd -> bash
+
+init/systemd -> getty -> bash
+
+Even if the COE characteristics (credentials) of the two bash
+processes are identical, the security coefficients generated by the
+two bash shells will be different. This is secondary to the fact that
+the TASK_ID of the two bash processes will be different by virtue of
+the fact that the first bash process will have a PTASK_ID that
+represents the TASK_ID of the ssh process, while the second process
+will have a PTASK_ID that represents the TASK_ID of the getty process.
+
+This generative functions provides a framework for modeling that
+yields very precise tracking of security relevant events. This is
+significant with respect to detecting and addressing adversarial
+techniques such as Living Off The Land (LOTL).
+
+Since the modeling operates at the level of a mandatory security
+control, these permission denials would occur even if the process is
+running with classic 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 = 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.
+
+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 security 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 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. 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. 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.
+
+The structures that are used by security events generated in atomic
+context are replenished by work requests submitted to the high
+priority system workqueue. The refill latency will also affect the
+magazine sizes that are needed.
+
+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 length of the ASCII base16 representation of the
+digest value of the cryptographic digest function defined for the
+security modeling 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. The length of the ASCII representation of HEXID must
+ equal the size of the base16 ASCII representation of a digest
+ value for the cryptographic hash function selected for the
+ security modeling namespace.
+
+By default a security modeling namespace runs in free modeling mode.
+The modeling mode is changed by writing the following keywords to the
+control file:
+
+ seal
+ enforce
+
+The seal value is used to specify that any further security state
+coefficients are to be considered outside the bounds of a desired
+security model. The security event descriptions that generate these
+coefficients will be considered forensics events for the model.
+
+The enforce key is used to specify that invalid security events
+generate permission denials as the return value for the LSM security
+event handler that generates the invalid events.
+
+The following keyword and argument are used to load a security model
+into an internal TMA modeling implementation:
+
+ 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. The length of the HEXID string must be equal to
+ the size of the ASCII base 16 representation of the digest
+ value of the cryptographic hash function defined for the
+ security modeling namespace.
+
+ 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 place
+ the defined model in enforcing mode.
+
+ Defining a security model to be enforced will affect the
+ output of the 'trajectory' file. The 'trajectory' file will
+ have no event descriptions for a sealed model, since the event
+ description list is only populated when a new state
+ coefficient is added to the model.
+
+ In a sealed model the security event descriptions will be
+ surfaced in the 'forensics' file instead to indicate they are
+ violations against the security model being enforced.
+
+ 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, a-priori, about the
+ desired 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 security state event mapping is to be extended with
+ before being committed as a security state coefficient value
+ for the model. The size of the HEXID string must equal the
+ size of the ASCII base 16 representation of a digest value of
+ the cryptographic hash function defined for the security
+ modeling namespace.
+
+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 size of the HEXID string must equal the size of the ASCII
+ base 16 representation of a digest value of the cryptographic
+ hash function defined for the security modeling namespace.
+
+The following keyword is used to lock the current TSEM modeling
+configuration:
+
+ lock
+
+This command is only valid when loadable module support is available
+in the kernel. When executed this command blocks any further TSEM
+models from being registered. In addition the reference count on all
+currently registgered modeling modules is increased so that it is not
+possible to remove currently loaded modules.
+
+The following two directories are implemented in the top level TSEM
+control directory in order to support interfaces to internally and
+externally modeled namespaces:
+
+ external_tma
+ internal_tma
+
+The external_tma directory holds a file, that is created when the
+request to create an externally modeled namespace is made. The filename
+is the ASCII base 10 representation of 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 through
+this file to the external trust orchestrator that is controlling the
+security modeling namespace.
+
+The internal_tma 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/internal_tma/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 the time independent functional value of
+security state of the security 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 match the entries of
+the event descriptions that are output in the 'trajectory' file.
+
+The security state coefficients can be paired with the security state
+descriptions with the following shell command, where DIR is the path
+to the individual files:
+
+paste DIR/trajectory_coefficients DIR/trajectory
+
+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 modeling 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 an
+event.
+
+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 associated with the orchestrator.
+
+Trust orchestrators for externally modeled namespaces, have an
+associated external 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. The CAP_MAC_ADMIN capability must be held by a trust
+orchestrator in order to access the TSEM control plane.
+
+Trust orchestrators are designed to drop the CAP_MAC_ADMIN capability
+before forking the process that will be responsible for launching a
+security 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
+implements the characteristics described in the previous section. 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.
+
+Source code, in GIT form, for all Quixote and TSEM components are
+available at the Quixote project site:
+
+https://github.com/Quixote-Project
+
+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,
+Quixote projects 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-export* -> Utility for exporting security event descriptions.
+
+quixote-mcu** -> TMA run in a micro-controller implementation.
+
+* = See discussion below.
+
+Each modeling utility runs in one of two modes: process or container
+
+In process mode, a shell process is run as the workload process in a
+security 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 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, a 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 option 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 output is 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.
+
+Quixote Export Utility
+----------------------
+
+The quixote-export utility is used to implement security modeling
+namespaces that are running in 'export only' mode. In this mode the
+security event descriptions for a security modeling namespace are
+exported asynchronously and do not wait approval. This utility and
+modeling mode can be used to implement kernel native security
+surveillance systems.
+
+The root security modeling namespace can be placed in 'export only'
+mode through the following kernel command-line option:
+
+tsem_mode=root_export_only
+
+The supplied quixote-export utility operates in a manner similar to
+the trust orchestrators for externally modeled namespaces.
+
+Workloads can be run in either 'cartridge' or 'process' modes that are
+specified with the -C or -P command-line options.
+
+Processing of events from the root security modeling namespace is
+specified with the -R command-line option.
+
+By default the quixote-export utility will run in 'one-shot' mode
+where all of the buffered security event descriptions are read and
+output, after which the utility terminates.
+
+Specifying the -f command-line option places the utility in 'follow'
+mode where the utility will first output all of the buffered security
+event descriptions and then wait for subsequent descriptions to be
+generated. This mode can be terminated by issuing a CNTRL-C key
+sequence to the utility.
+
+The -q command-line option is used to specify the queuing factor or
+the number of events that will be held by the export utility before
+flushing the events to the output device. This increases the
+efficiency of the utility and decreases the impact the export utility
+has on the security modeling namespace that it is running in, see the
+discussion of the 'Heisenberg' effect in security modeling. The
+default queue size is 100 entries.
+
+By default the security event descriptions are written to standard
+out. The -o command-line option can be used to specify that the
+events are to be written to a file.
+
+The quixote-export utility has native support for exporting security
+event descriptions as MQTT encoded messages. This facilitates the use
+of cloud based assets for security monitoring/surveillance. MQTT mode
+is specified with the -b command-line option. The argument to the -b
+option is the hostname of an MQTT broker that is to receive the
+encoded security event descriptions.
+
+In MQTT broker mode the -t command-line option is used to specify a
+'topic' that the descriptions are to published to in the target
+broker.
+
+An important issue that should be noted with 'export only' mode is
+that security event descriptions are buffered in the kernel until read
+by an export orchestrator. These events are not subject to
+'uniqueness' compression, as is the case with internally modeled
+namespaces, this can result in large kernel descriptions, particularly
+during the boot of a kernel whose root security modeling namespace is
+configured for export only mode.
+
+In addition there are no latency delays since the security event
+descriptions are asynchronously exported. This may require an
+increase in the kernel event magazine sizes in order to avoid security
+failures caused by the inability to allocate structures for security
+events running in atomic context.
+
+** 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.
@@ -6856,6 +6856,35 @@
with CPUID.16h support and partial CPUID.15h support.
Format: <unsigned int>
+ 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 generate the security event
+ coefficients in the root modeling namespace.
+ Format: {name of the cryptographic hash function}
+ Default: sha256
+
+ tsem_lock [TSEM] Lock the TSEM model state so that no kernel
+ module based security models can be registered.
+
+ tsem_mode= [TSEM] Set the mode that the Trusted Security Event
+ Modeling LSM is to run in.
+ Format: <string>
+ no_root_modeling - Disable root security namespace
+ modeling
+ root_export_only - Do not model the root security
+ modeling namespace, only export
+ the security event descriptions.
+
tsx= [X86] Control Transactional Synchronization
Extensions (TSX) feature in Intel processors that
support TSX control.