1 .\" Copyright (c) 2001, 2002 Networks Associates Technology, Inc.
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. The names of the authors may not be used to endorse or promote
13 .\" products derived from this software without specific prior written
16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" $Id: sec-doc.7,v 1.7 2001/12/22 00:14:12 rwatson Exp$
36 .Nd guide to adding security considerations sections to manual pages
38 This document presents guidelines for
39 adding security considerations sections to manual pages.
40 It provides two typical examples.
42 The guidelines for writing
46 mandate that each manual page describing a feature of the
48 system should contain a security considerations section
49 describing what security requirements can be broken
50 through the misuse of that feature.
51 When writing these sections, authors should attempt to
52 achieve a happy medium between two conflicting goals:
53 brevity and completeness.
54 On one hand, security consideration sections must not be too verbose,
55 or busy readers might be dissuaded from reading them.
56 On the other hand, security consideration sections must not be incomplete,
57 or they will fail in their purpose of
58 instructing the reader on how to avoid all insecure uses.
59 This document provides guidelines for balancing brevity and completeness
60 in the security consideration section for a given feature of the
65 those general security requirements that can be violated
66 through the misuse of the feature.
68 the FreeBSD Security Architecture (FSA),
69 there are four classes of security requirements:
70 .Bl -hang -offset indent
72 (example: non-administrators should not modify system binaries),
73 .It Em confidentiality
74 (example: non-administrators should not view the shadow password file),
76 (example: the web server should respond to client requests in a timely
79 (example: the ps program should provide exactly the process table
80 information listing functionality described in its documentation - no more,
85 contains a list of integrity, confidentiality, availability,
86 and correctness requirements for the base
89 Many commands, tools, and utilities
90 documented in sections 1, 6, and 8 of the manual
91 are partly responsible for meeting these base system requirements.
92 Consequently, borrowing entries from the list in
94 is a good way to begin the list of requirements for these commands,
97 Complex servers and subsystems may have their own integrity,
98 confidentiality, availability and correctness requirements
99 in addition to the system-wide ones listed in
101 Listing these additional requirements will require
102 some thought and analysis.
103 Correctness requirements will most often
104 deal with configuration issues,
105 especially in cases of programs that can load modules
106 containing arbitrary functionality during run-time.
108 For low-level features, such as the individual functions
109 documented in sections 2, 3, and 9 of the manual,
110 it is generally sufficient to proceed with
111 only a single correctness requirement:
112 simply that the function behaves as advertised.
114 A good security considerations section
115 should explain how the feature can be misused
116 to violate each general security requirement in the list.
117 Each explanation should be accompanied by instructions
118 the reader should follow in order to avoid a violation.
119 For the sake of brevity, assume the reader is familiar with
120 all of the concepts in
122 When referencing potential vulnerabilities
123 described in the Secure Programming Practices man page,
125 likewise cross-reference that document
126 rather than replicating information.
127 Whenever possible, refer to this document
128 rather than reproducing the material it contains.
130 Security problems are often interrelated;
131 individual problems often have far-reaching implications.
132 For example, the correctness of virtually any dynamically-linked program
133 is dependent on the correct implementation and configuration
134 of the run-time linker.
135 The correctness of this program, in turn,
136 depends on the correctness of its libraries,
137 the compiler used to build it,
138 the correctness of the preceding compiler that was used to build that compiler,
140 as described by Thompson (see
144 Due to the need for brevity, security consideration sections
145 should describe only those issues directly related to the feature
146 that is the subject of the manual page.
147 Refer to other manual pages
148 rather than duplicating the material found there.
149 Refer to generalized descriptions of problems in
151 rather than referring to specific instances of those problems
152 in other manual pages.
153 Ideally, each specific security-relevant issue
154 should be described in exactly one manual page,
155 preferably as a specific instance of a general problem
159 Security considerations sections for most individual functions can follow
162 .Bl -enum -offset indent -compact
164 Provide one or two sentences describing each potential security
167 to provide details whenever possible.
169 Provide one or two sentences describing how to avoid each potential
172 Provide a short example in code.
175 This is an example security considerations section for the
181 function is easily misused in a manner which enables malicious users
182 to arbitrarily change a running program's functionality
183 through a buffer overflow attack.
191 and ensure that no more characters are copied to the destination buffer
193 Do not forget to NUL-terminate the destination buffer,
196 will not terminate the destination string if it is truncated.
200 can also be problematic.
201 It may be a security concern for a string to be truncated at all.
202 Since the truncated string will not be as long as the original,
203 it may refer to a completely different resource
204 and usage of the truncated resource
205 could result in very incorrect behavior.
210 foo(const char *arbitrary_string)
216 * This first strcpy is bad behavior. Do not use strcpy()!
218 (void)strcpy(onstack, arbitrary_string); /* BAD! */
219 #elif defined(BETTER)
221 * The following two lines demonstrate better use of
224 (void)strncpy(onstack, arbitrary_string, sizeof(onstack) - 1);
225 onstack[sizeof(onstack - 1)] = '\\0';
228 * These lines are even more robust due to testing for
231 if (strlen(arbitrary_string) + 1 > sizeof(onstack))
232 err(1, "onstack would be truncated");
233 (void)strncpy(onstack, arbitrary_string, sizeof(onstack));
238 Security considerations sections for tools and commands
239 are apt to be less formulaic.
240 Let your list of potentially-violated security requirements
242 explain each one and list a solution in as concise a manner as possible.
244 This is an example security considerations section for the
248 Using the LD_LIBRARY_PATH and LD_PRELOAD environment variables,
249 malicious users can cause the dynamic linker
250 to link shared libraries of their own devising
251 into the address space of processes running non-set-user-ID/group-ID programs.
252 These shared libraries can arbitrarily change the functionality
253 of the program by replacing calls to standard library functions
254 with calls to their own.
255 Although this feature is disabled for set-user-ID and set-group-ID programs,
256 it can still be used to create Trojan horses in other programs.
260 All users should be aware that the correct operation of non
261 set-user-ID/group-ID dynamically-linked programs depends on the proper
262 configuration of these environment variables,
263 and take care to avoid actions that might set them to values
264 which would cause the run-time linker
265 to link in shared libraries of unknown pedigree.
271 .%T "The FreeBSD Security Architecture"
272 .%J file:///usr/share/doc/{to be determined}
275 .%A "Edward Amoroso, AT&T Bell Laboratories"
276 .%B "Fundamentals of Computer Security Technology"
277 .%I "P T R Prentice Hall"
282 .%T "Reflections on Trusting Trust"
283 .%J "Communications of the ACM"
284 .%I "Association for Computing Machinery, Inc."
292 manual page first appeared in
295 .An "Tim Fraser, NAI Labs CBOSS project." Aq tfraser@tislabs.com
296 .An "Brian Feldman, NAI Labs CBOSS project." Aq bfeldman@tislabs.com