+++ /dev/null
-=========================================
-Linux Secure Attention Key (SAK) handling
-=========================================
-
-:Date: 18 March 2001
-:Author: Andrew Morton
-
-An operating system's Secure Attention Key is a security tool which is
-provided as protection against trojan password capturing programs. It
-is an undefeatable way of killing all programs which could be
-masquerading as login applications. Users need to be taught to enter
-this key sequence before they log in to the system.
-
-From the PC keyboard, Linux has two similar but different ways of
-providing SAK. One is the ALT-SYSRQ-K sequence. You shouldn't use
-this sequence. It is only available if the kernel was compiled with
-sysrq support.
-
-The proper way of generating a SAK is to define the key sequence using
-``loadkeys``. This will work whether or not sysrq support is compiled
-into the kernel.
-
-SAK works correctly when the keyboard is in raw mode. This means that
-once defined, SAK will kill a running X server. If the system is in
-run level 5, the X server will restart. This is what you want to
-happen.
-
-What key sequence should you use? Well, CTRL-ALT-DEL is used to reboot
-the machine. CTRL-ALT-BACKSPACE is magical to the X server. We'll
-choose CTRL-ALT-PAUSE.
-
-In your rc.sysinit (or rc.local) file, add the command::
-
- echo "control alt keycode 101 = SAK" | /bin/loadkeys
-
-And that's it! Only the superuser may reprogram the SAK key.
-
-
-.. note::
-
- 1. Linux SAK is said to be not a "true SAK" as is required by
- systems which implement C2 level security. This author does not
- know why.
-
-
- 2. On the PC keyboard, SAK kills all applications which have
- /dev/console opened.
-
- Unfortunately this includes a number of things which you don't
- actually want killed. This is because these applications are
- incorrectly holding /dev/console open. Be sure to complain to your
- Linux distributor about this!
-
- You can identify processes which will be killed by SAK with the
- command::
-
- # ls -l /proc/[0-9]*/fd/* | grep console
- l-wx------ 1 root root 64 Mar 18 00:46 /proc/579/fd/0 -> /dev/console
-
- Then::
-
- # ps aux|grep 579
- root 579 0.0 0.1 1088 436 ? S 00:43 0:00 gpm -t ps/2
-
- So ``gpm`` will be killed by SAK. This is a bug in gpm. It should
- be closing standard input. You can work around this by finding the
- initscript which launches gpm and changing it thusly:
-
- Old::
-
- daemon gpm
-
- New::
-
- daemon gpm < /dev/null
-
- Vixie cron also seems to have this problem, and needs the same treatment.
-
- Also, one prominent Linux distribution has the following three
- lines in its rc.sysinit and rc scripts::
-
- exec 3<&0
- exec 4>&1
- exec 5>&2
-
- These commands cause **all** daemons which are launched by the
- initscripts to have file descriptors 3, 4 and 5 attached to
- /dev/console. So SAK kills them all. A workaround is to simply
- delete these lines, but this may cause system management
- applications to malfunction - test everything well.
-
+++ /dev/null
-========================================================
-Linux Security Modules: General Security Hooks for Linux
-========================================================
-
-:Author: Stephen Smalley
-:Author: Timothy Fraser
-:Author: Chris Vance
-
-.. note::
-
- The APIs described in this book are outdated.
-
-Introduction
-============
-
-In March 2001, the National Security Agency (NSA) gave a presentation
-about Security-Enhanced Linux (SELinux) at the 2.5 Linux Kernel Summit.
-SELinux is an implementation of flexible and fine-grained
-nondiscretionary access controls in the Linux kernel, originally
-implemented as its own particular kernel patch. Several other security
-projects (e.g. RSBAC, Medusa) have also developed flexible access
-control architectures for the Linux kernel, and various projects have
-developed particular access control models for Linux (e.g. LIDS, DTE,
-SubDomain). Each project has developed and maintained its own kernel
-patch to support its security needs.
-
-In response to the NSA presentation, Linus Torvalds made a set of
-remarks that described a security framework he would be willing to
-consider for inclusion in the mainstream Linux kernel. He described a
-general framework that would provide a set of security hooks to control
-operations on kernel objects and a set of opaque security fields in
-kernel data structures for maintaining security attributes. This
-framework could then be used by loadable kernel modules to implement any
-desired model of security. Linus also suggested the possibility of
-migrating the Linux capabilities code into such a module.
-
-The Linux Security Modules (LSM) project was started by WireX to develop
-such a framework. LSM is a joint development effort by several security
-projects, including Immunix, SELinux, SGI and Janus, and several
-individuals, including Greg Kroah-Hartman and James Morris, to develop a
-Linux kernel patch that implements this framework. The patch is
-currently tracking the 2.4 series and is targeted for integration into
-the 2.5 development series. This technical report provides an overview
-of the framework and the example capabilities security module provided
-by the LSM kernel patch.
-
-LSM Framework
-=============
-
-The LSM kernel patch provides a general kernel framework to support
-security modules. In particular, the LSM framework is primarily focused
-on supporting access control modules, although future development is
-likely to address other security needs such as auditing. By itself, the
-framework does not provide any additional security; it merely provides
-the infrastructure to support security modules. The LSM kernel patch
-also moves most of the capabilities logic into an optional security
-module, with the system defaulting to the traditional superuser logic.
-This capabilities module is discussed further in
-`LSM Capabilities Module <#cap>`__.
-
-The LSM kernel patch adds security fields to kernel data structures and
-inserts calls to hook functions at critical points in the kernel code to
-manage the security fields and to perform access control. It also adds
-functions for registering and unregistering security modules, and adds a
-general :c:func:`security()` system call to support new system calls
-for security-aware applications.
-
-The LSM security fields are simply ``void*`` pointers. For process and
-program execution security information, security fields were added to
-:c:type:`struct task_struct <task_struct>` and
-:c:type:`struct linux_binprm <linux_binprm>`. For filesystem
-security information, a security field was added to :c:type:`struct
-super_block <super_block>`. For pipe, file, and socket security
-information, security fields were added to :c:type:`struct inode
-<inode>` and :c:type:`struct file <file>`. For packet and
-network device security information, security fields were added to
-:c:type:`struct sk_buff <sk_buff>` and :c:type:`struct
-net_device <net_device>`. For System V IPC security information,
-security fields were added to :c:type:`struct kern_ipc_perm
-<kern_ipc_perm>` and :c:type:`struct msg_msg
-<msg_msg>`; additionally, the definitions for :c:type:`struct
-msg_msg <msg_msg>`, struct msg_queue, and struct shmid_kernel
-were moved to header files (``include/linux/msg.h`` and
-``include/linux/shm.h`` as appropriate) to allow the security modules to
-use these definitions.
-
-Each LSM hook is a function pointer in a global table, security_ops.
-This table is a :c:type:`struct security_operations
-<security_operations>` structure as defined by
-``include/linux/security.h``. Detailed documentation for each hook is
-included in this header file. At present, this structure consists of a
-collection of substructures that group related hooks based on the kernel
-object (e.g. task, inode, file, sk_buff, etc) as well as some top-level
-hook function pointers for system operations. This structure is likely
-to be flattened in the future for performance. The placement of the hook
-calls in the kernel code is described by the "called:" lines in the
-per-hook documentation in the header file. The hook calls can also be
-easily found in the kernel code by looking for the string
-"security_ops->".
-
-Linus mentioned per-process security hooks in his original remarks as a
-possible alternative to global security hooks. However, if LSM were to
-start from the perspective of per-process hooks, then the base framework
-would have to deal with how to handle operations that involve multiple
-processes (e.g. kill), since each process might have its own hook for
-controlling the operation. This would require a general mechanism for
-composing hooks in the base framework. Additionally, LSM would still
-need global hooks for operations that have no process context (e.g.
-network input operations). Consequently, LSM provides global security
-hooks, but a security module is free to implement per-process hooks
-(where that makes sense) by storing a security_ops table in each
-process' security field and then invoking these per-process hooks from
-the global hooks. The problem of composition is thus deferred to the
-module.
-
-The global security_ops table is initialized to a set of hook functions
-provided by a dummy security module that provides traditional superuser
-logic. A :c:func:`register_security()` function (in
-``security/security.c``) is provided to allow a security module to set
-security_ops to refer to its own hook functions, and an
-:c:func:`unregister_security()` function is provided to revert
-security_ops to the dummy module hooks. This mechanism is used to set
-the primary security module, which is responsible for making the final
-decision for each hook.
-
-LSM also provides a simple mechanism for stacking additional security
-modules with the primary security module. It defines
-:c:func:`register_security()` and
-:c:func:`unregister_security()` hooks in the :c:type:`struct
-security_operations <security_operations>` structure and
-provides :c:func:`mod_reg_security()` and
-:c:func:`mod_unreg_security()` functions that invoke these hooks
-after performing some sanity checking. A security module can call these
-functions in order to stack with other modules. However, the actual
-details of how this stacking is handled are deferred to the module,
-which can implement these hooks in any way it wishes (including always
-returning an error if it does not wish to support stacking). In this
-manner, LSM again defers the problem of composition to the module.
-
-Although the LSM hooks are organized into substructures based on kernel
-object, all of the hooks can be viewed as falling into two major
-categories: hooks that are used to manage the security fields and hooks
-that are used to perform access control. Examples of the first category
-of hooks include the :c:func:`alloc_security()` and
-:c:func:`free_security()` hooks defined for each kernel data
-structure that has a security field. These hooks are used to allocate
-and free security structures for kernel objects. The first category of
-hooks also includes hooks that set information in the security field
-after allocation, such as the :c:func:`post_lookup()` hook in
-:c:type:`struct inode_security_ops <inode_security_ops>`.
-This hook is used to set security information for inodes after
-successful lookup operations. An example of the second category of hooks
-is the :c:func:`permission()` hook in :c:type:`struct
-inode_security_ops <inode_security_ops>`. This hook checks
-permission when accessing an inode.
-
-LSM Capabilities Module
-=======================
-
-The LSM kernel patch moves most of the existing POSIX.1e capabilities
-logic into an optional security module stored in the file
-``security/capability.c``. This change allows users who do not want to
-use capabilities to omit this code entirely from their kernel, instead
-using the dummy module for traditional superuser logic or any other
-module that they desire. This change also allows the developers of the
-capabilities logic to maintain and enhance their code more freely,
-without needing to integrate patches back into the base kernel.
-
-In addition to moving the capabilities logic, the LSM kernel patch could
-move the capability-related fields from the kernel data structures into
-the new security fields managed by the security modules. However, at
-present, the LSM kernel patch leaves the capability fields in the kernel
-data structures. In his original remarks, Linus suggested that this
-might be preferable so that other security modules can be easily stacked
-with the capabilities module without needing to chain multiple security
-structures on the security field. It also avoids imposing extra overhead
-on the capabilities module to manage the security fields. However, the
-LSM framework could certainly support such a move if it is determined to
-be desirable, with only a few additional changes described below.
-
-At present, the capabilities logic for computing process capabilities on
-:c:func:`execve()` and :c:func:`set\*uid()`, checking
-capabilities for a particular process, saving and checking capabilities
-for netlink messages, and handling the :c:func:`capget()` and
-:c:func:`capset()` system calls have been moved into the
-capabilities module. There are still a few locations in the base kernel
-where capability-related fields are directly examined or modified, but
-the current version of the LSM patch does allow a security module to
-completely replace the assignment and testing of capabilities. These few
-locations would need to be changed if the capability-related fields were
-moved into the security field. The following is a list of known
-locations that still perform such direct examination or modification of
-capability-related fields:
-
-- ``fs/open.c``::c:func:`sys_access()`
-
-- ``fs/lockd/host.c``::c:func:`nlm_bind_host()`
-
-- ``fs/nfsd/auth.c``::c:func:`nfsd_setuser()`
-
-- ``fs/proc/array.c``::c:func:`task_cap()`
+++ /dev/null
-=================================
-Linux Security Module Development
-=================================
-
-Based on https://lkml.org/lkml/2007/10/26/215,
-a new LSM is accepted into the kernel when its intent (a description of
-what it tries to protect against and in what cases one would expect to
-use it) has been appropriately documented in ``Documentation/admin-guide/LSM/``.
-This allows an LSM's code to be easily compared to its goals, and so
-that end users and distros can make a more informed decision about which
-LSMs suit their requirements.
-
-For extensive documentation on the available LSM hook interfaces, please
-see ``include/linux/lsm_hooks.h`` and associated structures:
-
-.. kernel-doc:: include/linux/lsm_hooks.h
- :internal:
credentials
IMA-templates
keys/index
- LSM
+ lsm
+ lsm-development
+ sak
SCTP
self-protection
+ siphash
tpm/index
--- /dev/null
+=================================
+Linux Security Module Development
+=================================
+
+Based on https://lkml.org/lkml/2007/10/26/215,
+a new LSM is accepted into the kernel when its intent (a description of
+what it tries to protect against and in what cases one would expect to
+use it) has been appropriately documented in ``Documentation/admin-guide/LSM/``.
+This allows an LSM's code to be easily compared to its goals, and so
+that end users and distros can make a more informed decision about which
+LSMs suit their requirements.
+
+For extensive documentation on the available LSM hook interfaces, please
+see ``include/linux/lsm_hooks.h`` and associated structures:
+
+.. kernel-doc:: include/linux/lsm_hooks.h
+ :internal:
--- /dev/null
+========================================================
+Linux Security Modules: General Security Hooks for Linux
+========================================================
+
+:Author: Stephen Smalley
+:Author: Timothy Fraser
+:Author: Chris Vance
+
+.. note::
+
+ The APIs described in this book are outdated.
+
+Introduction
+============
+
+In March 2001, the National Security Agency (NSA) gave a presentation
+about Security-Enhanced Linux (SELinux) at the 2.5 Linux Kernel Summit.
+SELinux is an implementation of flexible and fine-grained
+nondiscretionary access controls in the Linux kernel, originally
+implemented as its own particular kernel patch. Several other security
+projects (e.g. RSBAC, Medusa) have also developed flexible access
+control architectures for the Linux kernel, and various projects have
+developed particular access control models for Linux (e.g. LIDS, DTE,
+SubDomain). Each project has developed and maintained its own kernel
+patch to support its security needs.
+
+In response to the NSA presentation, Linus Torvalds made a set of
+remarks that described a security framework he would be willing to
+consider for inclusion in the mainstream Linux kernel. He described a
+general framework that would provide a set of security hooks to control
+operations on kernel objects and a set of opaque security fields in
+kernel data structures for maintaining security attributes. This
+framework could then be used by loadable kernel modules to implement any
+desired model of security. Linus also suggested the possibility of
+migrating the Linux capabilities code into such a module.
+
+The Linux Security Modules (LSM) project was started by WireX to develop
+such a framework. LSM is a joint development effort by several security
+projects, including Immunix, SELinux, SGI and Janus, and several
+individuals, including Greg Kroah-Hartman and James Morris, to develop a
+Linux kernel patch that implements this framework. The patch is
+currently tracking the 2.4 series and is targeted for integration into
+the 2.5 development series. This technical report provides an overview
+of the framework and the example capabilities security module provided
+by the LSM kernel patch.
+
+LSM Framework
+=============
+
+The LSM kernel patch provides a general kernel framework to support
+security modules. In particular, the LSM framework is primarily focused
+on supporting access control modules, although future development is
+likely to address other security needs such as auditing. By itself, the
+framework does not provide any additional security; it merely provides
+the infrastructure to support security modules. The LSM kernel patch
+also moves most of the capabilities logic into an optional security
+module, with the system defaulting to the traditional superuser logic.
+This capabilities module is discussed further in
+`LSM Capabilities Module <#cap>`__.
+
+The LSM kernel patch adds security fields to kernel data structures and
+inserts calls to hook functions at critical points in the kernel code to
+manage the security fields and to perform access control. It also adds
+functions for registering and unregistering security modules, and adds a
+general :c:func:`security()` system call to support new system calls
+for security-aware applications.
+
+The LSM security fields are simply ``void*`` pointers. For process and
+program execution security information, security fields were added to
+:c:type:`struct task_struct <task_struct>` and
+:c:type:`struct linux_binprm <linux_binprm>`. For filesystem
+security information, a security field was added to :c:type:`struct
+super_block <super_block>`. For pipe, file, and socket security
+information, security fields were added to :c:type:`struct inode
+<inode>` and :c:type:`struct file <file>`. For packet and
+network device security information, security fields were added to
+:c:type:`struct sk_buff <sk_buff>` and :c:type:`struct
+net_device <net_device>`. For System V IPC security information,
+security fields were added to :c:type:`struct kern_ipc_perm
+<kern_ipc_perm>` and :c:type:`struct msg_msg
+<msg_msg>`; additionally, the definitions for :c:type:`struct
+msg_msg <msg_msg>`, struct msg_queue, and struct shmid_kernel
+were moved to header files (``include/linux/msg.h`` and
+``include/linux/shm.h`` as appropriate) to allow the security modules to
+use these definitions.
+
+Each LSM hook is a function pointer in a global table, security_ops.
+This table is a :c:type:`struct security_operations
+<security_operations>` structure as defined by
+``include/linux/security.h``. Detailed documentation for each hook is
+included in this header file. At present, this structure consists of a
+collection of substructures that group related hooks based on the kernel
+object (e.g. task, inode, file, sk_buff, etc) as well as some top-level
+hook function pointers for system operations. This structure is likely
+to be flattened in the future for performance. The placement of the hook
+calls in the kernel code is described by the "called:" lines in the
+per-hook documentation in the header file. The hook calls can also be
+easily found in the kernel code by looking for the string
+"security_ops->".
+
+Linus mentioned per-process security hooks in his original remarks as a
+possible alternative to global security hooks. However, if LSM were to
+start from the perspective of per-process hooks, then the base framework
+would have to deal with how to handle operations that involve multiple
+processes (e.g. kill), since each process might have its own hook for
+controlling the operation. This would require a general mechanism for
+composing hooks in the base framework. Additionally, LSM would still
+need global hooks for operations that have no process context (e.g.
+network input operations). Consequently, LSM provides global security
+hooks, but a security module is free to implement per-process hooks
+(where that makes sense) by storing a security_ops table in each
+process' security field and then invoking these per-process hooks from
+the global hooks. The problem of composition is thus deferred to the
+module.
+
+The global security_ops table is initialized to a set of hook functions
+provided by a dummy security module that provides traditional superuser
+logic. A :c:func:`register_security()` function (in
+``security/security.c``) is provided to allow a security module to set
+security_ops to refer to its own hook functions, and an
+:c:func:`unregister_security()` function is provided to revert
+security_ops to the dummy module hooks. This mechanism is used to set
+the primary security module, which is responsible for making the final
+decision for each hook.
+
+LSM also provides a simple mechanism for stacking additional security
+modules with the primary security module. It defines
+:c:func:`register_security()` and
+:c:func:`unregister_security()` hooks in the :c:type:`struct
+security_operations <security_operations>` structure and
+provides :c:func:`mod_reg_security()` and
+:c:func:`mod_unreg_security()` functions that invoke these hooks
+after performing some sanity checking. A security module can call these
+functions in order to stack with other modules. However, the actual
+details of how this stacking is handled are deferred to the module,
+which can implement these hooks in any way it wishes (including always
+returning an error if it does not wish to support stacking). In this
+manner, LSM again defers the problem of composition to the module.
+
+Although the LSM hooks are organized into substructures based on kernel
+object, all of the hooks can be viewed as falling into two major
+categories: hooks that are used to manage the security fields and hooks
+that are used to perform access control. Examples of the first category
+of hooks include the :c:func:`alloc_security()` and
+:c:func:`free_security()` hooks defined for each kernel data
+structure that has a security field. These hooks are used to allocate
+and free security structures for kernel objects. The first category of
+hooks also includes hooks that set information in the security field
+after allocation, such as the :c:func:`post_lookup()` hook in
+:c:type:`struct inode_security_ops <inode_security_ops>`.
+This hook is used to set security information for inodes after
+successful lookup operations. An example of the second category of hooks
+is the :c:func:`permission()` hook in :c:type:`struct
+inode_security_ops <inode_security_ops>`. This hook checks
+permission when accessing an inode.
+
+LSM Capabilities Module
+=======================
+
+The LSM kernel patch moves most of the existing POSIX.1e capabilities
+logic into an optional security module stored in the file
+``security/capability.c``. This change allows users who do not want to
+use capabilities to omit this code entirely from their kernel, instead
+using the dummy module for traditional superuser logic or any other
+module that they desire. This change also allows the developers of the
+capabilities logic to maintain and enhance their code more freely,
+without needing to integrate patches back into the base kernel.
+
+In addition to moving the capabilities logic, the LSM kernel patch could
+move the capability-related fields from the kernel data structures into
+the new security fields managed by the security modules. However, at
+present, the LSM kernel patch leaves the capability fields in the kernel
+data structures. In his original remarks, Linus suggested that this
+might be preferable so that other security modules can be easily stacked
+with the capabilities module without needing to chain multiple security
+structures on the security field. It also avoids imposing extra overhead
+on the capabilities module to manage the security fields. However, the
+LSM framework could certainly support such a move if it is determined to
+be desirable, with only a few additional changes described below.
+
+At present, the capabilities logic for computing process capabilities on
+:c:func:`execve()` and :c:func:`set\*uid()`, checking
+capabilities for a particular process, saving and checking capabilities
+for netlink messages, and handling the :c:func:`capget()` and
+:c:func:`capset()` system calls have been moved into the
+capabilities module. There are still a few locations in the base kernel
+where capability-related fields are directly examined or modified, but
+the current version of the LSM patch does allow a security module to
+completely replace the assignment and testing of capabilities. These few
+locations would need to be changed if the capability-related fields were
+moved into the security field. The following is a list of known
+locations that still perform such direct examination or modification of
+capability-related fields:
+
+- ``fs/open.c``::c:func:`sys_access()`
+
+- ``fs/lockd/host.c``::c:func:`nlm_bind_host()`
+
+- ``fs/nfsd/auth.c``::c:func:`nfsd_setuser()`
+
+- ``fs/proc/array.c``::c:func:`task_cap()`
--- /dev/null
+=========================================
+Linux Secure Attention Key (SAK) handling
+=========================================
+
+:Date: 18 March 2001
+:Author: Andrew Morton
+
+An operating system's Secure Attention Key is a security tool which is
+provided as protection against trojan password capturing programs. It
+is an undefeatable way of killing all programs which could be
+masquerading as login applications. Users need to be taught to enter
+this key sequence before they log in to the system.
+
+From the PC keyboard, Linux has two similar but different ways of
+providing SAK. One is the ALT-SYSRQ-K sequence. You shouldn't use
+this sequence. It is only available if the kernel was compiled with
+sysrq support.
+
+The proper way of generating a SAK is to define the key sequence using
+``loadkeys``. This will work whether or not sysrq support is compiled
+into the kernel.
+
+SAK works correctly when the keyboard is in raw mode. This means that
+once defined, SAK will kill a running X server. If the system is in
+run level 5, the X server will restart. This is what you want to
+happen.
+
+What key sequence should you use? Well, CTRL-ALT-DEL is used to reboot
+the machine. CTRL-ALT-BACKSPACE is magical to the X server. We'll
+choose CTRL-ALT-PAUSE.
+
+In your rc.sysinit (or rc.local) file, add the command::
+
+ echo "control alt keycode 101 = SAK" | /bin/loadkeys
+
+And that's it! Only the superuser may reprogram the SAK key.
+
+
+.. note::
+
+ 1. Linux SAK is said to be not a "true SAK" as is required by
+ systems which implement C2 level security. This author does not
+ know why.
+
+
+ 2. On the PC keyboard, SAK kills all applications which have
+ /dev/console opened.
+
+ Unfortunately this includes a number of things which you don't
+ actually want killed. This is because these applications are
+ incorrectly holding /dev/console open. Be sure to complain to your
+ Linux distributor about this!
+
+ You can identify processes which will be killed by SAK with the
+ command::
+
+ # ls -l /proc/[0-9]*/fd/* | grep console
+ l-wx------ 1 root root 64 Mar 18 00:46 /proc/579/fd/0 -> /dev/console
+
+ Then::
+
+ # ps aux|grep 579
+ root 579 0.0 0.1 1088 436 ? S 00:43 0:00 gpm -t ps/2
+
+ So ``gpm`` will be killed by SAK. This is a bug in gpm. It should
+ be closing standard input. You can work around this by finding the
+ initscript which launches gpm and changing it thusly:
+
+ Old::
+
+ daemon gpm
+
+ New::
+
+ daemon gpm < /dev/null
+
+ Vixie cron also seems to have this problem, and needs the same treatment.
+
+ Also, one prominent Linux distribution has the following three
+ lines in its rc.sysinit and rc scripts::
+
+ exec 3<&0
+ exec 4>&1
+ exec 5>&2
+
+ These commands cause **all** daemons which are launched by the
+ initscripts to have file descriptors 3, 4 and 5 attached to
+ /dev/console. So SAK kills them all. A workaround is to simply
+ delete these lines, but this may cause system management
+ applications to malfunction - test everything well.
+
--- /dev/null
+===========================
+SipHash - a short input PRF
+===========================
+
+:Author: Written by Jason A. Donenfeld <jason@zx2c4.com>
+
+SipHash is a cryptographically secure PRF -- a keyed hash function -- that
+performs very well for short inputs, hence the name. It was designed by
+cryptographers Daniel J. Bernstein and Jean-Philippe Aumasson. It is intended
+as a replacement for some uses of: `jhash`, `md5_transform`, `sha_transform`,
+and so forth.
+
+SipHash takes a secret key filled with randomly generated numbers and either
+an input buffer or several input integers. It spits out an integer that is
+indistinguishable from random. You may then use that integer as part of secure
+sequence numbers, secure cookies, or mask it off for use in a hash table.
+
+Generating a key
+================
+
+Keys should always be generated from a cryptographically secure source of
+random numbers, either using get_random_bytes or get_random_once::
+
+ siphash_key_t key;
+ get_random_bytes(&key, sizeof(key));
+
+If you're not deriving your key from here, you're doing it wrong.
+
+Using the functions
+===================
+
+There are two variants of the function, one that takes a list of integers, and
+one that takes a buffer::
+
+ u64 siphash(const void *data, size_t len, const siphash_key_t *key);
+
+And::
+
+ u64 siphash_1u64(u64, const siphash_key_t *key);
+ u64 siphash_2u64(u64, u64, const siphash_key_t *key);
+ u64 siphash_3u64(u64, u64, u64, const siphash_key_t *key);
+ u64 siphash_4u64(u64, u64, u64, u64, const siphash_key_t *key);
+ u64 siphash_1u32(u32, const siphash_key_t *key);
+ u64 siphash_2u32(u32, u32, const siphash_key_t *key);
+ u64 siphash_3u32(u32, u32, u32, const siphash_key_t *key);
+ u64 siphash_4u32(u32, u32, u32, u32, const siphash_key_t *key);
+
+If you pass the generic siphash function something of a constant length, it
+will constant fold at compile-time and automatically choose one of the
+optimized functions.
+
+Hashtable key function usage::
+
+ struct some_hashtable {
+ DECLARE_HASHTABLE(hashtable, 8);
+ siphash_key_t key;
+ };
+
+ void init_hashtable(struct some_hashtable *table)
+ {
+ get_random_bytes(&table->key, sizeof(table->key));
+ }
+
+ static inline hlist_head *some_hashtable_bucket(struct some_hashtable *table, struct interesting_input *input)
+ {
+ return &table->hashtable[siphash(input, sizeof(*input), &table->key) & (HASH_SIZE(table->hashtable) - 1)];
+ }
+
+You may then iterate like usual over the returned hash bucket.
+
+Security
+========
+
+SipHash has a very high security margin, with its 128-bit key. So long as the
+key is kept secret, it is impossible for an attacker to guess the outputs of
+the function, even if being able to observe many outputs, since 2^128 outputs
+is significant.
+
+Linux implements the "2-4" variant of SipHash.
+
+Struct-passing Pitfalls
+=======================
+
+Often times the XuY functions will not be large enough, and instead you'll
+want to pass a pre-filled struct to siphash. When doing this, it's important
+to always ensure the struct has no padding holes. The easiest way to do this
+is to simply arrange the members of the struct in descending order of size,
+and to use offsetendof() instead of sizeof() for getting the size. For
+performance reasons, if possible, it's probably a good thing to align the
+struct to the right boundary. Here's an example::
+
+ const struct {
+ struct in6_addr saddr;
+ u32 counter;
+ u16 dport;
+ } __aligned(SIPHASH_ALIGNMENT) combined = {
+ .saddr = *(struct in6_addr *)saddr,
+ .counter = counter,
+ .dport = dport
+ };
+ u64 h = siphash(&combined, offsetofend(typeof(combined), dport), &secret);
+
+Resources
+=========
+
+Read the SipHash paper if you're interested in learning more:
+https://131002.net/siphash/siphash.pdf
+
+-------------------------------------------------------------------------------
+
+===============================================
+HalfSipHash - SipHash's insecure younger cousin
+===============================================
+
+:Author: Written by Jason A. Donenfeld <jason@zx2c4.com>
+
+On the off-chance that SipHash is not fast enough for your needs, you might be
+able to justify using HalfSipHash, a terrifying but potentially useful
+possibility. HalfSipHash cuts SipHash's rounds down from "2-4" to "1-3" and,
+even scarier, uses an easily brute-forcable 64-bit key (with a 32-bit output)
+instead of SipHash's 128-bit key. However, this may appeal to some
+high-performance `jhash` users.
+
+Danger!
+
+Do not ever use HalfSipHash except for as a hashtable key function, and only
+then when you can be absolutely certain that the outputs will never be
+transmitted out of the kernel. This is only remotely useful over `jhash` as a
+means of mitigating hashtable flooding denial of service attacks.
+
+Generating a key
+================
+
+Keys should always be generated from a cryptographically secure source of
+random numbers, either using get_random_bytes or get_random_once:
+
+hsiphash_key_t key;
+get_random_bytes(&key, sizeof(key));
+
+If you're not deriving your key from here, you're doing it wrong.
+
+Using the functions
+===================
+
+There are two variants of the function, one that takes a list of integers, and
+one that takes a buffer::
+
+ u32 hsiphash(const void *data, size_t len, const hsiphash_key_t *key);
+
+And::
+
+ u32 hsiphash_1u32(u32, const hsiphash_key_t *key);
+ u32 hsiphash_2u32(u32, u32, const hsiphash_key_t *key);
+ u32 hsiphash_3u32(u32, u32, u32, const hsiphash_key_t *key);
+ u32 hsiphash_4u32(u32, u32, u32, u32, const hsiphash_key_t *key);
+
+If you pass the generic hsiphash function something of a constant length, it
+will constant fold at compile-time and automatically choose one of the
+optimized functions.
+
+Hashtable key function usage
+============================
+
+::
+
+ struct some_hashtable {
+ DECLARE_HASHTABLE(hashtable, 8);
+ hsiphash_key_t key;
+ };
+
+ void init_hashtable(struct some_hashtable *table)
+ {
+ get_random_bytes(&table->key, sizeof(table->key));
+ }
+
+ static inline hlist_head *some_hashtable_bucket(struct some_hashtable *table, struct interesting_input *input)
+ {
+ return &table->hashtable[hsiphash(input, sizeof(*input), &table->key) & (HASH_SIZE(table->hashtable) - 1)];
+ }
+
+You may then iterate like usual over the returned hash bucket.
+
+Performance
+===========
+
+HalfSipHash is roughly 3 times slower than JenkinsHash. For many replacements,
+this will not be a problem, as the hashtable lookup isn't the bottleneck. And
+in general, this is probably a good sacrifice to make for the security and DoS
+resistance of HalfSipHash.
.. toctree::
tpm_vtpm_proxy
+ xen-tpmfront
-:orphan:
-
=============================
Virtual TPM interface for Xen
=============================
+++ /dev/null
-===========================
-SipHash - a short input PRF
-===========================
-
-:Author: Written by Jason A. Donenfeld <jason@zx2c4.com>
-
-SipHash is a cryptographically secure PRF -- a keyed hash function -- that
-performs very well for short inputs, hence the name. It was designed by
-cryptographers Daniel J. Bernstein and Jean-Philippe Aumasson. It is intended
-as a replacement for some uses of: `jhash`, `md5_transform`, `sha_transform`,
-and so forth.
-
-SipHash takes a secret key filled with randomly generated numbers and either
-an input buffer or several input integers. It spits out an integer that is
-indistinguishable from random. You may then use that integer as part of secure
-sequence numbers, secure cookies, or mask it off for use in a hash table.
-
-Generating a key
-================
-
-Keys should always be generated from a cryptographically secure source of
-random numbers, either using get_random_bytes or get_random_once::
-
- siphash_key_t key;
- get_random_bytes(&key, sizeof(key));
-
-If you're not deriving your key from here, you're doing it wrong.
-
-Using the functions
-===================
-
-There are two variants of the function, one that takes a list of integers, and
-one that takes a buffer::
-
- u64 siphash(const void *data, size_t len, const siphash_key_t *key);
-
-And::
-
- u64 siphash_1u64(u64, const siphash_key_t *key);
- u64 siphash_2u64(u64, u64, const siphash_key_t *key);
- u64 siphash_3u64(u64, u64, u64, const siphash_key_t *key);
- u64 siphash_4u64(u64, u64, u64, u64, const siphash_key_t *key);
- u64 siphash_1u32(u32, const siphash_key_t *key);
- u64 siphash_2u32(u32, u32, const siphash_key_t *key);
- u64 siphash_3u32(u32, u32, u32, const siphash_key_t *key);
- u64 siphash_4u32(u32, u32, u32, u32, const siphash_key_t *key);
-
-If you pass the generic siphash function something of a constant length, it
-will constant fold at compile-time and automatically choose one of the
-optimized functions.
-
-Hashtable key function usage::
-
- struct some_hashtable {
- DECLARE_HASHTABLE(hashtable, 8);
- siphash_key_t key;
- };
-
- void init_hashtable(struct some_hashtable *table)
- {
- get_random_bytes(&table->key, sizeof(table->key));
- }
-
- static inline hlist_head *some_hashtable_bucket(struct some_hashtable *table, struct interesting_input *input)
- {
- return &table->hashtable[siphash(input, sizeof(*input), &table->key) & (HASH_SIZE(table->hashtable) - 1)];
- }
-
-You may then iterate like usual over the returned hash bucket.
-
-Security
-========
-
-SipHash has a very high security margin, with its 128-bit key. So long as the
-key is kept secret, it is impossible for an attacker to guess the outputs of
-the function, even if being able to observe many outputs, since 2^128 outputs
-is significant.
-
-Linux implements the "2-4" variant of SipHash.
-
-Struct-passing Pitfalls
-=======================
-
-Often times the XuY functions will not be large enough, and instead you'll
-want to pass a pre-filled struct to siphash. When doing this, it's important
-to always ensure the struct has no padding holes. The easiest way to do this
-is to simply arrange the members of the struct in descending order of size,
-and to use offsetendof() instead of sizeof() for getting the size. For
-performance reasons, if possible, it's probably a good thing to align the
-struct to the right boundary. Here's an example::
-
- const struct {
- struct in6_addr saddr;
- u32 counter;
- u16 dport;
- } __aligned(SIPHASH_ALIGNMENT) combined = {
- .saddr = *(struct in6_addr *)saddr,
- .counter = counter,
- .dport = dport
- };
- u64 h = siphash(&combined, offsetofend(typeof(combined), dport), &secret);
-
-Resources
-=========
-
-Read the SipHash paper if you're interested in learning more:
-https://131002.net/siphash/siphash.pdf
-
--------------------------------------------------------------------------------
-
-===============================================
-HalfSipHash - SipHash's insecure younger cousin
-===============================================
-
-:Author: Written by Jason A. Donenfeld <jason@zx2c4.com>
-
-On the off-chance that SipHash is not fast enough for your needs, you might be
-able to justify using HalfSipHash, a terrifying but potentially useful
-possibility. HalfSipHash cuts SipHash's rounds down from "2-4" to "1-3" and,
-even scarier, uses an easily brute-forcable 64-bit key (with a 32-bit output)
-instead of SipHash's 128-bit key. However, this may appeal to some
-high-performance `jhash` users.
-
-Danger!
-
-Do not ever use HalfSipHash except for as a hashtable key function, and only
-then when you can be absolutely certain that the outputs will never be
-transmitted out of the kernel. This is only remotely useful over `jhash` as a
-means of mitigating hashtable flooding denial of service attacks.
-
-Generating a key
-================
-
-Keys should always be generated from a cryptographically secure source of
-random numbers, either using get_random_bytes or get_random_once:
-
-hsiphash_key_t key;
-get_random_bytes(&key, sizeof(key));
-
-If you're not deriving your key from here, you're doing it wrong.
-
-Using the functions
-===================
-
-There are two variants of the function, one that takes a list of integers, and
-one that takes a buffer::
-
- u32 hsiphash(const void *data, size_t len, const hsiphash_key_t *key);
-
-And::
-
- u32 hsiphash_1u32(u32, const hsiphash_key_t *key);
- u32 hsiphash_2u32(u32, u32, const hsiphash_key_t *key);
- u32 hsiphash_3u32(u32, u32, u32, const hsiphash_key_t *key);
- u32 hsiphash_4u32(u32, u32, u32, u32, const hsiphash_key_t *key);
-
-If you pass the generic hsiphash function something of a constant length, it
-will constant fold at compile-time and automatically choose one of the
-optimized functions.
-
-Hashtable key function usage
-============================
-
-::
-
- struct some_hashtable {
- DECLARE_HASHTABLE(hashtable, 8);
- hsiphash_key_t key;
- };
-
- void init_hashtable(struct some_hashtable *table)
- {
- get_random_bytes(&table->key, sizeof(table->key));
- }
-
- static inline hlist_head *some_hashtable_bucket(struct some_hashtable *table, struct interesting_input *input)
- {
- return &table->hashtable[hsiphash(input, sizeof(*input), &table->key) & (HASH_SIZE(table->hashtable) - 1)];
- }
-
-You may then iterate like usual over the returned hash bucket.
-
-Performance
-===========
-
-HalfSipHash is roughly 3 times slower than JenkinsHash. For many replacements,
-this will not be a problem, as the hashtable lookup isn't the bottleneck. And
-in general, this is probably a good sacrifice to make for the security and DoS
-resistance of HalfSipHash.
projects / mirror_ubuntu-jammy-kernel.git / commitdiff