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.
67 There are four classes of security requirements:
68 .Bl -hang -offset indent
70 (example: non-administrators should not modify system binaries),
71 .It Em confidentiality
72 (example: non-administrators should not view the shadow password file),
74 (example: the web server should respond to client requests in a timely
77 (example: the ps program should provide exactly the process table
78 information listing functionality described in its documentation - no more,
82 A good security considerations section
83 should explain how the feature can be misused
84 to violate each general security requirement in the list.
85 Each explanation should be accompanied by instructions
86 the reader should follow in order to avoid a violation.
87 When referencing potential vulnerabilities
88 described in the Secure Programming Practices manual page,
90 likewise cross-reference that document
91 rather than replicating information.
92 Whenever possible, refer to this document
93 rather than reproducing the material it contains.
95 Security problems are often interrelated;
96 individual problems often have far-reaching implications.
97 For example, the correctness of virtually any dynamically-linked program
98 is dependent on the correct implementation and configuration
99 of the run-time linker.
100 The correctness of this program, in turn,
101 depends on the correctness of its libraries,
102 the compiler used to build it,
103 the correctness of the preceding compiler that was used to build that compiler,
105 as described by Thompson (see
109 Due to the need for brevity, security consideration sections
110 should describe only those issues directly related to the feature
111 that is the subject of the manual page.
112 Refer to other manual pages
113 rather than duplicating the material found there.
115 Security considerations sections for most individual functions can follow
118 .Bl -enum -offset indent -compact
120 Provide one or two sentences describing each potential security
123 Provide one or two sentences describing how to avoid each potential
126 Provide a short example in code.
129 This is an example security considerations section for the
135 function is easily misused in a manner which enables malicious users
136 to arbitrarily change a running program's functionality
137 through a buffer overflow attack.
143 and ensure that no more characters are copied to the destination buffer
145 Do not forget to NUL-terminate the destination buffer,
148 will not terminate the destination string if it is truncated.
152 can also be problematic.
153 It may be a security concern for a string to be truncated at all.
154 Since the truncated string will not be as long as the original,
155 it may refer to a completely different resource
156 and usage of the truncated resource
157 could result in very incorrect behavior.
161 foo(const char *arbitrary_string)
167 * This first strcpy is bad behavior. Do not use strcpy()!
169 (void)strcpy(onstack, arbitrary_string); /* BAD! */
170 #elif defined(BETTER)
172 * The following two lines demonstrate better use of
175 (void)strncpy(onstack, arbitrary_string, sizeof(onstack) - 1);
176 onstack[sizeof(onstack - 1)] = '\\0';
179 * These lines are even more robust due to testing for
182 if (strlen(arbitrary_string) + 1 > sizeof(onstack))
183 err(1, "onstack would be truncated");
184 (void)strncpy(onstack, arbitrary_string, sizeof(onstack));
189 Security considerations sections for tools and commands
190 are apt to be less formulaic.
191 Let your list of potentially-violated security requirements
193 explain each one and list a solution in as concise a manner as possible.
195 This is an example security considerations section for the
199 Using the LD_LIBRARY_PATH and LD_PRELOAD environment variables,
200 malicious users can cause the dynamic linker
201 to link shared libraries of their own devising
202 into the address space of processes running non-set-user-ID/group-ID programs.
203 These shared libraries can arbitrarily change the functionality
204 of the program by replacing calls to standard library functions
205 with calls to their own.
206 Although this feature is disabled for set-user-ID and set-group-ID programs,
207 it can still be used to create Trojan horses in other programs.
209 All users should be aware that the correct operation of non
210 set-user-ID/group-ID dynamically-linked programs depends on the proper
211 configuration of these environment variables,
212 and take care to avoid actions that might set them to values
213 which would cause the run-time linker
214 to link in shared libraries of unknown pedigree.
220 .%A "Edward Amoroso, AT&T Bell Laboratories"
221 .%B "Fundamentals of Computer Security Technology"
222 .%I "P T R Prentice Hall"
227 .%T "Reflections on Trusting Trust"
228 .%J "Communications of the ACM"
229 .%I "Association for Computing Machinery, Inc."
237 manual page first appeared in
240 .An "Tim Fraser, NAI Labs CBOSS project." Aq tfraser@tislabs.com
241 .An "Brian Feldman, NAI Labs CBOSS project." Aq bfeldman@tislabs.com