1.\" Copyright (c) 2001, 2002 Networks Associates Technology, Inc. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 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 14.\" permission. 15.\" 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 26.\" SUCH DAMAGE. 27.\" 28.\" $Id: sec-doc.7,v 1.7 2001/12/22 00:14:12 rwatson Exp$ 29.\" $FreeBSD$ 30.\" 31.Dd September 5, 2005 32.Dt SDOC 7 33.Os 34.Sh NAME 35.Nm sdoc 36.Nd guide to adding security considerations sections to manual pages 37.Sh DESCRIPTION 38This document presents guidelines for 39adding security considerations sections to manual pages. 40It provides two typical examples. 41.Pp 42The guidelines for writing 43.Fx 44manual pages in 45.Xr groff_mdoc 7 46mandate that each manual page describing a feature of the 47.Fx 48system should contain a security considerations section 49describing what security requirements can be broken 50through the misuse of that feature. 51When writing these sections, authors should attempt to 52achieve a happy medium between two conflicting goals: 53brevity and completeness. 54On one hand, security consideration sections must not be too verbose, 55or busy readers might be dissuaded from reading them. 56On the other hand, security consideration sections must not be incomplete, 57or they will fail in their purpose of 58instructing the reader on how to avoid all insecure uses. 59This document provides guidelines for balancing brevity and completeness 60in the security consideration section for a given feature of the 61.Fx 62system. 63.Ss Where to Start 64Begin by listing 65those general security requirements that can be violated 66through the misuse of the feature. 67There are four classes of security requirements: 68.Bl -hang -offset indent 69.It Em integrity 70(example: non-administrators should not modify system binaries), 71.It Em confidentiality 72(example: non-administrators should not view the shadow password file), 73.It Em availability 74(example: the web server should respond to client requests in a timely 75fashion), and 76.It Em correctness 77(example: the ps program should provide exactly the process table 78information listing functionality described in its documentation - no more, 79no less.) 80.El 81.Pp 82A good security considerations section 83should explain how the feature can be misused 84to violate each general security requirement in the list. 85Each explanation should be accompanied by instructions 86the reader should follow in order to avoid a violation. 87When referencing potential vulnerabilities 88described in the Secure Programming Practices manual page, 89.Xr sprog 7 , 90likewise cross-reference that document 91rather than replicating information. 92Whenever possible, refer to this document 93rather than reproducing the material it contains. 94.Ss Where to Stop 95Security problems are often interrelated; 96individual problems often have far-reaching implications. 97For example, the correctness of virtually any dynamically-linked program 98is dependent on the correct implementation and configuration 99of the run-time linker. 100The correctness of this program, in turn, 101depends on the correctness of its libraries, 102the compiler used to build it, 103the correctness of the preceding compiler that was used to build that compiler, 104and so on, 105as described by Thompson (see 106.Sx SEE ALSO , 107below). 108.Pp 109Due to the need for brevity, security consideration sections 110should describe only those issues directly related to the feature 111that is the subject of the manual page. 112Refer to other manual pages 113rather than duplicating the material found there. 114.Sh EXAMPLES 115Security considerations sections for most individual functions can follow 116this simple formula: 117.Pp 118.Bl -enum -offset indent -compact 119.It 120Provide one or two sentences describing each potential security 121problem. 122.It 123Provide one or two sentences describing how to avoid each potential 124security problem. 125.It 126Provide a short example in code. 127.El 128.Pp 129This is an example security considerations section for the 130.Xr strcpy 3 131manual page: 132.Pp 133The 134.Fn strcpy 135function is easily misused in a manner which enables malicious users 136to arbitrarily change a running program's functionality 137through a buffer overflow attack. 138.Pp 139Avoid using 140.Fn strcpy . 141Instead, use 142.Fn strncpy 143and ensure that no more characters are copied to the destination buffer 144than it can hold. 145Do not forget to NUL-terminate the destination buffer, 146as 147.Fn strncpy 148will not terminate the destination string if it is truncated. 149.Pp 150Note that 151.Fn strncpy 152can also be problematic. 153It may be a security concern for a string to be truncated at all. 154Since the truncated string will not be as long as the original, 155it may refer to a completely different resource 156and usage of the truncated resource 157could result in very incorrect behavior. 158Example: 159.Bd -literal 160void 161foo(const char *arbitrary_string) 162{ 163 char onstack[8]; 164 165#if defined(BAD) 166 /* 167 * This first strcpy is bad behavior. Do not use strcpy()! 168 */ 169 (void)strcpy(onstack, arbitrary_string); /* BAD! */ 170#elif defined(BETTER) 171 /* 172 * The following two lines demonstrate better use of 173 * strncpy(). 174 */ 175 (void)strncpy(onstack, arbitrary_string, sizeof(onstack) - 1); 176 onstack[sizeof(onstack - 1)] = '\\0'; 177#elif defined(BEST) 178 /* 179 * These lines are even more robust due to testing for 180 * truncation. 181 */ 182 if (strlen(arbitrary_string) + 1 > sizeof(onstack)) 183 err(1, "onstack would be truncated"); 184 (void)strncpy(onstack, arbitrary_string, sizeof(onstack)); 185#endif 186} 187.Ed 188.Pp 189Security considerations sections for tools and commands 190are apt to be less formulaic. 191Let your list of potentially-violated security requirements 192be your guide; 193explain each one and list a solution in as concise a manner as possible. 194.Pp 195This is an example security considerations section for the 196.Xr rtld 1 197manual page: 198.Pp 199Using the LD_LIBRARY_PATH and LD_PRELOAD environment variables, 200malicious users can cause the dynamic linker 201to link shared libraries of their own devising 202into the address space of processes running non-set-user-ID/group-ID programs. 203These shared libraries can arbitrarily change the functionality 204of the program by replacing calls to standard library functions 205with calls to their own. 206Although this feature is disabled for set-user-ID and set-group-ID programs, 207it can still be used to create Trojan horses in other programs. 208.Pp 209All users should be aware that the correct operation of non 210set-user-ID/group-ID dynamically-linked programs depends on the proper 211configuration of these environment variables, 212and take care to avoid actions that might set them to values 213which would cause the run-time linker 214to link in shared libraries of unknown pedigree. 215.Sh SEE ALSO 216.Xr groff_mdoc 7 , 217.Xr security 7 , 218.Xr sprog 7 219.Rs 220.%A "Edward Amoroso, AT&T Bell Laboratories" 221.%B "Fundamentals of Computer Security Technology" 222.%I "P T R Prentice Hall" 223.%D "1994" 224.Re 225.Rs 226.%A "Ken Thompson" 227.%T "Reflections on Trusting Trust" 228.%J "Communications of the ACM" 229.%I "Association for Computing Machinery, Inc." 230.%P "761-763" 231.%N "Vol. 27, No. 8" 232.%D "August, 1984" 233.Re 234.Sh HISTORY 235The 236.Nm 237manual page first appeared in 238.Fx 5.0 . 239.Sh AUTHORS 240.An Tim Fraser Aq Mt tfraser@tislabs.com , 241NAI Labs CBOSS project 242.An Brian Feldman Aq Mt bfeldman@tislabs.com , 243NAI Labs CBOSS project 244