diff options
author | David S. Miller <davem@davemloft.net> | 2014-01-06 17:37:45 -0500 |
---|---|---|
committer | David S. Miller <davem@davemloft.net> | 2014-01-06 17:37:45 -0500 |
commit | 56a4342dfe3145cd66f766adccb28fd9b571606d (patch) | |
tree | d1593764488ff8cbb0b83cb9ae35fd968bf81760 /Documentation | |
parent | 805c1f4aedaba1bc8d839e7c27b128083dd5c2f0 (diff) | |
parent | fe0d692bbc645786bce1a98439e548ae619269f5 (diff) |
Merge branch 'master' of git://git.kernel.org/pub/scm/linux/kernel/git/davem/net
Conflicts:
drivers/net/ethernet/qlogic/qlcnic/qlcnic_sriov_pf.c
net/ipv6/ip6_tunnel.c
net/ipv6/ip6_vti.c
ipv6 tunnel statistic bug fixes conflicting with consolidation into
generic sw per-cpu net stats.
qlogic conflict between queue counting bug fix and the addition
of multiple MAC address support.
Signed-off-by: David S. Miller <davem@davemloft.net>
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/block/null_blk.txt | 72 | ||||
-rw-r--r-- | Documentation/kernel-parameters.txt | 2 | ||||
-rw-r--r-- | Documentation/module-signing.txt | 240 |
3 files changed, 314 insertions, 0 deletions
diff --git a/Documentation/block/null_blk.txt b/Documentation/block/null_blk.txt new file mode 100644 index 000000000000..b2830b435895 --- /dev/null +++ b/Documentation/block/null_blk.txt | |||
@@ -0,0 +1,72 @@ | |||
1 | Null block device driver | ||
2 | ================================================================================ | ||
3 | |||
4 | I. Overview | ||
5 | |||
6 | The null block device (/dev/nullb*) is used for benchmarking the various | ||
7 | block-layer implementations. It emulates a block device of X gigabytes in size. | ||
8 | The following instances are possible: | ||
9 | |||
10 | Single-queue block-layer | ||
11 | - Request-based. | ||
12 | - Single submission queue per device. | ||
13 | - Implements IO scheduling algorithms (CFQ, Deadline, noop). | ||
14 | Multi-queue block-layer | ||
15 | - Request-based. | ||
16 | - Configurable submission queues per device. | ||
17 | No block-layer (Known as bio-based) | ||
18 | - Bio-based. IO requests are submitted directly to the device driver. | ||
19 | - Directly accepts bio data structure and returns them. | ||
20 | |||
21 | All of them have a completion queue for each core in the system. | ||
22 | |||
23 | II. Module parameters applicable for all instances: | ||
24 | |||
25 | queue_mode=[0-2]: Default: 2-Multi-queue | ||
26 | Selects which block-layer the module should instantiate with. | ||
27 | |||
28 | 0: Bio-based. | ||
29 | 1: Single-queue. | ||
30 | 2: Multi-queue. | ||
31 | |||
32 | home_node=[0--nr_nodes]: Default: NUMA_NO_NODE | ||
33 | Selects what CPU node the data structures are allocated from. | ||
34 | |||
35 | gb=[Size in GB]: Default: 250GB | ||
36 | The size of the device reported to the system. | ||
37 | |||
38 | bs=[Block size (in bytes)]: Default: 512 bytes | ||
39 | The block size reported to the system. | ||
40 | |||
41 | nr_devices=[Number of devices]: Default: 2 | ||
42 | Number of block devices instantiated. They are instantiated as /dev/nullb0, | ||
43 | etc. | ||
44 | |||
45 | irq_mode=[0-2]: Default: 1-Soft-irq | ||
46 | The completion mode used for completing IOs to the block-layer. | ||
47 | |||
48 | 0: None. | ||
49 | 1: Soft-irq. Uses IPI to complete IOs across CPU nodes. Simulates the overhead | ||
50 | when IOs are issued from another CPU node than the home the device is | ||
51 | connected to. | ||
52 | 2: Timer: Waits a specific period (completion_nsec) for each IO before | ||
53 | completion. | ||
54 | |||
55 | completion_nsec=[ns]: Default: 10.000ns | ||
56 | Combined with irq_mode=2 (timer). The time each completion event must wait. | ||
57 | |||
58 | submit_queues=[0..nr_cpus]: | ||
59 | The number of submission queues attached to the device driver. If unset, it | ||
60 | defaults to 1 on single-queue and bio-based instances. For multi-queue, | ||
61 | it is ignored when use_per_node_hctx module parameter is 1. | ||
62 | |||
63 | hw_queue_depth=[0..qdepth]: Default: 64 | ||
64 | The hardware queue depth of the device. | ||
65 | |||
66 | III: Multi-queue specific parameters | ||
67 | |||
68 | use_per_node_hctx=[0/1]: Default: 0 | ||
69 | 0: The number of submit queues are set to the value of the submit_queues | ||
70 | parameter. | ||
71 | 1: The multi-queue block layer is instantiated with a hardware dispatch | ||
72 | queue for each CPU node in the system. | ||
diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 50680a59a2ff..b9e9bd854298 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt | |||
@@ -1529,6 +1529,8 @@ bytes respectively. Such letter suffixes can also be entirely omitted. | |||
1529 | 1529 | ||
1530 | * atapi_dmadir: Enable ATAPI DMADIR bridge support | 1530 | * atapi_dmadir: Enable ATAPI DMADIR bridge support |
1531 | 1531 | ||
1532 | * disable: Disable this device. | ||
1533 | |||
1532 | If there are multiple matching configurations changing | 1534 | If there are multiple matching configurations changing |
1533 | the same attribute, the last one is used. | 1535 | the same attribute, the last one is used. |
1534 | 1536 | ||
diff --git a/Documentation/module-signing.txt b/Documentation/module-signing.txt new file mode 100644 index 000000000000..2b40e04d3c49 --- /dev/null +++ b/Documentation/module-signing.txt | |||
@@ -0,0 +1,240 @@ | |||
1 | ============================== | ||
2 | KERNEL MODULE SIGNING FACILITY | ||
3 | ============================== | ||
4 | |||
5 | CONTENTS | ||
6 | |||
7 | - Overview. | ||
8 | - Configuring module signing. | ||
9 | - Generating signing keys. | ||
10 | - Public keys in the kernel. | ||
11 | - Manually signing modules. | ||
12 | - Signed modules and stripping. | ||
13 | - Loading signed modules. | ||
14 | - Non-valid signatures and unsigned modules. | ||
15 | - Administering/protecting the private key. | ||
16 | |||
17 | |||
18 | ======== | ||
19 | OVERVIEW | ||
20 | ======== | ||
21 | |||
22 | The kernel module signing facility cryptographically signs modules during | ||
23 | installation and then checks the signature upon loading the module. This | ||
24 | allows increased kernel security by disallowing the loading of unsigned modules | ||
25 | or modules signed with an invalid key. Module signing increases security by | ||
26 | making it harder to load a malicious module into the kernel. The module | ||
27 | signature checking is done by the kernel so that it is not necessary to have | ||
28 | trusted userspace bits. | ||
29 | |||
30 | This facility uses X.509 ITU-T standard certificates to encode the public keys | ||
31 | involved. The signatures are not themselves encoded in any industrial standard | ||
32 | type. The facility currently only supports the RSA public key encryption | ||
33 | standard (though it is pluggable and permits others to be used). The possible | ||
34 | hash algorithms that can be used are SHA-1, SHA-224, SHA-256, SHA-384, and | ||
35 | SHA-512 (the algorithm is selected by data in the signature). | ||
36 | |||
37 | |||
38 | ========================== | ||
39 | CONFIGURING MODULE SIGNING | ||
40 | ========================== | ||
41 | |||
42 | The module signing facility is enabled by going to the "Enable Loadable Module | ||
43 | Support" section of the kernel configuration and turning on | ||
44 | |||
45 | CONFIG_MODULE_SIG "Module signature verification" | ||
46 | |||
47 | This has a number of options available: | ||
48 | |||
49 | (1) "Require modules to be validly signed" (CONFIG_MODULE_SIG_FORCE) | ||
50 | |||
51 | This specifies how the kernel should deal with a module that has a | ||
52 | signature for which the key is not known or a module that is unsigned. | ||
53 | |||
54 | If this is off (ie. "permissive"), then modules for which the key is not | ||
55 | available and modules that are unsigned are permitted, but the kernel will | ||
56 | be marked as being tainted. | ||
57 | |||
58 | If this is on (ie. "restrictive"), only modules that have a valid | ||
59 | signature that can be verified by a public key in the kernel's possession | ||
60 | will be loaded. All other modules will generate an error. | ||
61 | |||
62 | Irrespective of the setting here, if the module has a signature block that | ||
63 | cannot be parsed, it will be rejected out of hand. | ||
64 | |||
65 | |||
66 | (2) "Automatically sign all modules" (CONFIG_MODULE_SIG_ALL) | ||
67 | |||
68 | If this is on then modules will be automatically signed during the | ||
69 | modules_install phase of a build. If this is off, then the modules must | ||
70 | be signed manually using: | ||
71 | |||
72 | scripts/sign-file | ||
73 | |||
74 | |||
75 | (3) "Which hash algorithm should modules be signed with?" | ||
76 | |||
77 | This presents a choice of which hash algorithm the installation phase will | ||
78 | sign the modules with: | ||
79 | |||
80 | CONFIG_SIG_SHA1 "Sign modules with SHA-1" | ||
81 | CONFIG_SIG_SHA224 "Sign modules with SHA-224" | ||
82 | CONFIG_SIG_SHA256 "Sign modules with SHA-256" | ||
83 | CONFIG_SIG_SHA384 "Sign modules with SHA-384" | ||
84 | CONFIG_SIG_SHA512 "Sign modules with SHA-512" | ||
85 | |||
86 | The algorithm selected here will also be built into the kernel (rather | ||
87 | than being a module) so that modules signed with that algorithm can have | ||
88 | their signatures checked without causing a dependency loop. | ||
89 | |||
90 | |||
91 | ======================= | ||
92 | GENERATING SIGNING KEYS | ||
93 | ======================= | ||
94 | |||
95 | Cryptographic keypairs are required to generate and check signatures. A | ||
96 | private key is used to generate a signature and the corresponding public key is | ||
97 | used to check it. The private key is only needed during the build, after which | ||
98 | it can be deleted or stored securely. The public key gets built into the | ||
99 | kernel so that it can be used to check the signatures as the modules are | ||
100 | loaded. | ||
101 | |||
102 | Under normal conditions, the kernel build will automatically generate a new | ||
103 | keypair using openssl if one does not exist in the files: | ||
104 | |||
105 | signing_key.priv | ||
106 | signing_key.x509 | ||
107 | |||
108 | during the building of vmlinux (the public part of the key needs to be built | ||
109 | into vmlinux) using parameters in the: | ||
110 | |||
111 | x509.genkey | ||
112 | |||
113 | file (which is also generated if it does not already exist). | ||
114 | |||
115 | It is strongly recommended that you provide your own x509.genkey file. | ||
116 | |||
117 | Most notably, in the x509.genkey file, the req_distinguished_name section | ||
118 | should be altered from the default: | ||
119 | |||
120 | [ req_distinguished_name ] | ||
121 | O = Magrathea | ||
122 | CN = Glacier signing key | ||
123 | emailAddress = slartibartfast@magrathea.h2g2 | ||
124 | |||
125 | The generated RSA key size can also be set with: | ||
126 | |||
127 | [ req ] | ||
128 | default_bits = 4096 | ||
129 | |||
130 | |||
131 | It is also possible to manually generate the key private/public files using the | ||
132 | x509.genkey key generation configuration file in the root node of the Linux | ||
133 | kernel sources tree and the openssl command. The following is an example to | ||
134 | generate the public/private key files: | ||
135 | |||
136 | openssl req -new -nodes -utf8 -sha256 -days 36500 -batch -x509 \ | ||
137 | -config x509.genkey -outform DER -out signing_key.x509 \ | ||
138 | -keyout signing_key.priv | ||
139 | |||
140 | |||
141 | ========================= | ||
142 | PUBLIC KEYS IN THE KERNEL | ||
143 | ========================= | ||
144 | |||
145 | The kernel contains a ring of public keys that can be viewed by root. They're | ||
146 | in a keyring called ".system_keyring" that can be seen by: | ||
147 | |||
148 | [root@deneb ~]# cat /proc/keys | ||
149 | ... | ||
150 | 223c7853 I------ 1 perm 1f030000 0 0 keyring .system_keyring: 1 | ||
151 | 302d2d52 I------ 1 perm 1f010000 0 0 asymmetri Fedora kernel signing key: d69a84e6bce3d216b979e9505b3e3ef9a7118079: X509.RSA a7118079 [] | ||
152 | ... | ||
153 | |||
154 | Beyond the public key generated specifically for module signing, any file | ||
155 | placed in the kernel source root directory or the kernel build root directory | ||
156 | whose name is suffixed with ".x509" will be assumed to be an X.509 public key | ||
157 | and will be added to the keyring. | ||
158 | |||
159 | Further, the architecture code may take public keys from a hardware store and | ||
160 | add those in also (e.g. from the UEFI key database). | ||
161 | |||
162 | Finally, it is possible to add additional public keys by doing: | ||
163 | |||
164 | keyctl padd asymmetric "" [.system_keyring-ID] <[key-file] | ||
165 | |||
166 | e.g.: | ||
167 | |||
168 | keyctl padd asymmetric "" 0x223c7853 <my_public_key.x509 | ||
169 | |||
170 | Note, however, that the kernel will only permit keys to be added to | ||
171 | .system_keyring _if_ the new key's X.509 wrapper is validly signed by a key | ||
172 | that is already resident in the .system_keyring at the time the key was added. | ||
173 | |||
174 | |||
175 | ========================= | ||
176 | MANUALLY SIGNING MODULES | ||
177 | ========================= | ||
178 | |||
179 | To manually sign a module, use the scripts/sign-file tool available in | ||
180 | the Linux kernel source tree. The script requires 4 arguments: | ||
181 | |||
182 | 1. The hash algorithm (e.g., sha256) | ||
183 | 2. The private key filename | ||
184 | 3. The public key filename | ||
185 | 4. The kernel module to be signed | ||
186 | |||
187 | The following is an example to sign a kernel module: | ||
188 | |||
189 | scripts/sign-file sha512 kernel-signkey.priv \ | ||
190 | kernel-signkey.x509 module.ko | ||
191 | |||
192 | The hash algorithm used does not have to match the one configured, but if it | ||
193 | doesn't, you should make sure that hash algorithm is either built into the | ||
194 | kernel or can be loaded without requiring itself. | ||
195 | |||
196 | |||
197 | ============================ | ||
198 | SIGNED MODULES AND STRIPPING | ||
199 | ============================ | ||
200 | |||
201 | A signed module has a digital signature simply appended at the end. The string | ||
202 | "~Module signature appended~." at the end of the module's file confirms that a | ||
203 | signature is present but it does not confirm that the signature is valid! | ||
204 | |||
205 | Signed modules are BRITTLE as the signature is outside of the defined ELF | ||
206 | container. Thus they MAY NOT be stripped once the signature is computed and | ||
207 | attached. Note the entire module is the signed payload, including any and all | ||
208 | debug information present at the time of signing. | ||
209 | |||
210 | |||
211 | ====================== | ||
212 | LOADING SIGNED MODULES | ||
213 | ====================== | ||
214 | |||
215 | Modules are loaded with insmod, modprobe, init_module() or finit_module(), | ||
216 | exactly as for unsigned modules as no processing is done in userspace. The | ||
217 | signature checking is all done within the kernel. | ||
218 | |||
219 | |||
220 | ========================================= | ||
221 | NON-VALID SIGNATURES AND UNSIGNED MODULES | ||
222 | ========================================= | ||
223 | |||
224 | If CONFIG_MODULE_SIG_FORCE is enabled or enforcemodulesig=1 is supplied on | ||
225 | the kernel command line, the kernel will only load validly signed modules | ||
226 | for which it has a public key. Otherwise, it will also load modules that are | ||
227 | unsigned. Any module for which the kernel has a key, but which proves to have | ||
228 | a signature mismatch will not be permitted to load. | ||
229 | |||
230 | Any module that has an unparseable signature will be rejected. | ||
231 | |||
232 | |||
233 | ========================================= | ||
234 | ADMINISTERING/PROTECTING THE PRIVATE KEY | ||
235 | ========================================= | ||
236 | |||
237 | Since the private key is used to sign modules, viruses and malware could use | ||
238 | the private key to sign modules and compromise the operating system. The | ||
239 | private key must be either destroyed or moved to a secure location and not kept | ||
240 | in the root node of the kernel source tree. | ||