diff --git a/Documentation/ABI/testing/tsem b/Documentation/ABI/testing/tsem
new file mode 100644
index 000000000000..d88a1994294d
--- /dev/null
+++ b/Documentation/ABI/testing/tsem
@@ -0,0 +1,2386 @@
+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:
+
+		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.
+
+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": {
+	        "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:
+
+	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.
diff --git a/Documentation/admin-guide/LSM/index.rst b/Documentation/admin-guide/LSM/index.rst
index a6ba95fbaa9f..cebd3b02598d 100644
--- a/Documentation/admin-guide/LSM/index.rst
+++ b/Documentation/admin-guide/LSM/index.rst
@@ -47,3 +47,4 @@ subdirectories.
    tomoyo
    Yama
    SafeSetID
+   tsem
diff --git a/Documentation/admin-guide/LSM/tsem.rst b/Documentation/admin-guide/LSM/tsem.rst
new file mode 100644
index 000000000000..7331ead13d9a
--- /dev/null
+++ b/Documentation/admin-guide/LSM/tsem.rst
@@ -0,0 +1,1657 @@
+====
+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=1
+
+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:
+
+	nsref
+	digest
+	cache
+	key
+
+The 'nsref' keyword takes one of the following two values:
+
+	initial
+	current
+
+The initial argument indicates that the UID/GID values for the COE 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 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=2
+
+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.
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index bb884c14b2f6..d54654a69606 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -6785,6 +6785,30 @@
 			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_mode=	[TSEM] Set the mode that the Trusted Security Event
+			Modeling LSM is to run in.
+			Format: <unsigned int>
+			1 -- Disable root security namespace modeling.
+			2 -- Only export security event descriptions from
+			     the root security modeling namespace.
+
 	tsx=		[X86] Control Transactional Synchronization
 			Extensions (TSX) feature in Intel processors that
 			support TSX control.
