Commit 8802f616 authored by Paul Moore's avatar Paul Moore Committed by David S. Miller

[NetLabel]: documentation

Documentation for the NetLabel system, this includes a basic overview
of how NetLabel works, how LSM developers can integrate it into their
favorite LSM, as well as documentation on the CIPSO related sysctl
variables.  Also, due to the difficulty of finding expired IETF
drafts, I am including the IETF CIPSO draft that is the basis of the
NetLabel CIPSO implementation.
Signed-off-by: default avatarPaul Moore <>
Signed-off-by: default avatarDavid S. Miller <>
parent a51c64f1
......@@ -2384,6 +2384,13 @@ N: Thomas Molina
D: bug fixes, documentation, minor hackery
N: Paul Moore
D: NetLabel author
S: Hewlett-Packard
S: 110 Spit Brook Road
S: Nashua, NH 03062
N: James Morris
......@@ -184,6 +184,8 @@ mtrr.txt
- how to use PPro Memory Type Range Registers to increase performance.
- info on a TCP implementation of a network block device.
- directory with information on the NetLabel subsystem.
- directory with info on various aspects of networking with Linux.
- this file.
- documentation on the IPv4 CIPSO protocol engine.
- IETF draft of the CIPSO protocol, dated 16 July 1992.
- NetLabel introduction, READ THIS FIRST.
- documentation on the NetLabel kernel security module API.
NetLabel CIPSO/IPv4 Protocol Engine
Paul Moore,
May 17, 2006
* Overview
The NetLabel CIPSO/IPv4 protocol engine is based on the IETF Commercial IP
Security Option (CIPSO) draft from July 16, 1992. A copy of this draft can be
found in this directory, consult '00-INDEX' for the filename. While the IETF
draft never made it to an RFC standard it has become a de-facto standard for
labeled networking and is used in many trusted operating systems.
* Outbound Packet Processing
The CIPSO/IPv4 protocol engine applies the CIPSO IP option to packets by
adding the CIPSO label to the socket. This causes all packets leaving the
system through the socket to have the CIPSO IP option applied. The socket's
CIPSO label can be changed at any point in time, however, it is recommended
that it is set upon the socket's creation. The LSM can set the socket's CIPSO
label by using the NetLabel security module API; if the NetLabel "domain" is
configured to use CIPSO for packet labeling then a CIPSO IP option will be
generated and attached to the socket.
* Inbound Packet Processing
The CIPSO/IPv4 protocol engine validates every CIPSO IP option it finds at the
IP layer without any special handling required by the LSM. However, in order
to decode and translate the CIPSO label on the packet the LSM must use the
NetLabel security module API to extract the security attributes of the packet.
This is typically done at the socket layer using the 'socket_sock_rcv_skb()'
LSM hook.
* Label Translation
The CIPSO/IPv4 protocol engine contains a mechanism to translate CIPSO security
attributes such as sensitivity level and category to values which are
appropriate for the host. These mappings are defined as part of a CIPSO
Domain Of Interpretation (DOI) definition and are configured through the
NetLabel user space communication layer. Each DOI definition can have a
different security attribute mapping table.
* Label Translation Cache
The NetLabel system provides a framework for caching security attribute
mappings from the network labels to the corresponding LSM identifiers. The
CIPSO/IPv4 protocol engine supports this caching mechanism.
This diff is collapsed.
NetLabel Introduction
Paul Moore,
August 2, 2006
* Overview
NetLabel is a mechanism which can be used by kernel security modules to attach
security attributes to outgoing network packets generated from user space
applications and read security attributes from incoming network packets. It
is composed of three main components, the protocol engines, the communication
layer, and the kernel security module API.
* Protocol Engines
The protocol engines are responsible for both applying and retrieving the
network packet's security attributes. If any translation between the network
security attributes and those on the host are required then the protocol
engine will handle those tasks as well. Other kernel subsystems should
refrain from calling the protocol engines directly, instead they should use
the NetLabel kernel security module API described below.
Detailed information about each NetLabel protocol engine can be found in this
directory, consult '00-INDEX' for filenames.
* Communication Layer
The communication layer exists to allow NetLabel configuration and monitoring
from user space. The NetLabel communication layer uses a message based
protocol built on top of the Generic NETLINK transport mechanism. The exact
formatting of these NetLabel messages as well as the Generic NETLINK family
names can be found in the the 'net/netlabel/' directory as comments in the
header files as well as in 'include/net/netlabel.h'.
* Security Module API
The purpose of the NetLabel security module API is to provide a protocol
independent interface to the underlying NetLabel protocol engines. In addition
to protocol independence, the security module API is designed to be completely
LSM independent which should allow multiple LSMs to leverage the same code
Detailed information about the NetLabel security module API can be found in the
'include/net/netlabel.h' header file as well as the 'lsm_interface.txt' file
found in this directory.
NetLabel Linux Security Module Interface
Paul Moore,
May 17, 2006
* Overview
NetLabel is a mechanism which can set and retrieve security attributes from
network packets. It is intended to be used by LSM developers who want to make
use of a common code base for several different packet labeling protocols.
The NetLabel security module API is defined in 'include/net/netlabel.h' but a
brief overview is given below.
* NetLabel Security Attributes
Since NetLabel supports multiple different packet labeling protocols and LSMs
it uses the concept of security attributes to refer to the packet's security
labels. The NetLabel security attributes are defined by the
'netlbl_lsm_secattr' structure in the NetLabel header file. Internally the
NetLabel subsystem converts the security attributes to and from the correct
low-level packet label depending on the NetLabel build time and run time
configuration. It is up to the LSM developer to translate the NetLabel
security attributes into whatever security identifiers are in use for their
particular LSM.
* NetLabel LSM Protocol Operations
These are the functions which allow the LSM developer to manipulate the labels
on outgoing packets as well as read the labels on incoming packets. Functions
exist to operate both on sockets as well as the sk_buffs directly. These high
level functions are translated into low level protocol operations based on how
the administrator has configured the NetLabel subsystem.
* NetLabel Label Mapping Cache Operations
Depending on the exact configuration, translation between the network packet
label and the internal LSM security identifier can be time consuming. The
NetLabel label mapping cache is a caching mechanism which can be used to
sidestep much of this overhead once a mapping has been established. Once the
LSM has received a packet, used NetLabel to decode it's security attributes,
and translated the security attributes into a LSM internal identifier the LSM
can use the NetLabel caching functions to associate the LSM internal
identifier with the network packet's label. This means that in the future
when a incoming packet matches a cached value not only are the internal
NetLabel translation mechanisms bypassed but the LSM translation mechanisms are
bypassed as well which should result in a significant reduction in overhead.
......@@ -375,6 +375,41 @@ tcp_slow_start_after_idle - BOOLEAN
be timed out after an idle period.
Default: 1
CIPSOv4 Variables:
cipso_cache_enable - BOOLEAN
If set, enable additions to and lookups from the CIPSO label mapping
cache. If unset, additions are ignored and lookups always result in a
miss. However, regardless of the setting the cache is still
invalidated when required when means you can safely toggle this on and
off and the cache will always be "safe".
Default: 1
cipso_cache_bucket_size - INTEGER
The CIPSO label cache consists of a fixed size hash table with each
hash bucket containing a number of cache entries. This variable limits
the number of entries in each hash bucket; the larger the value the
more CIPSO label mappings that can be cached. When the number of
entries in a given hash bucket reaches this limit adding new entries
causes the oldest entry in the bucket to be removed to make room.
Default: 10
cipso_rbm_optfmt - BOOLEAN
Enable the "Optimized Tag 1 Format" as defined in section of
the CIPSO draft specification (see Documentation/netlabel for details).
This means that when set the CIPSO tag will be padded with empty
categories in order to make the packet data 32-bit aligned.
Default: 0
cipso_rbm_structvalid - BOOLEAN
If set, do a very strict check of the CIPSO option when
ip_options_compile() is called. If unset, relax the checks done during
ip_options_compile(). Either way is "safe" as errors are caught else
where in the CIPSO processing code but setting this to 0 (False) should
result in less work (i.e. it should be faster) but could cause problems
with other implementations that require strict checking.
Default: 0
IP Variables:
ip_local_port_range - 2 INTEGERS
Markdown is supported
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment