6/share/man/man7/sdoc.7

   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 October 12, 2001
  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
  38 This document presents guidelines for
  39 adding security considerations sections to manual pages.
  40 It provides two typical examples.
  41 .Pp
  42 The guidelines for writing
  43 .Fx
  44 manual pages in
  45 .Xr groff_mdoc 7
  46 mandate that each manual page describing a feature of the
  47 .Fx
  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
  61 .Fx
  62 system.
  63 .Ss Where to Start
  64 Begin by listing
  65 those general security requirements that can be violated
  66 through the misuse of the feature.
  67 As described in
  68 the FreeBSD Security Architecture (FSA),
  69 there are four classes of security requirements:
  70 .Bl -hang -offset indent
  71 .It Em integrity
  72 (example: non-administrators should not modify system binaries),
  73 .It Em confidentiality
  74 (example: non-administrators should not view the shadow password file),
  75 .It Em availability
  76 (example: the web server should respond to client requests in a timely
  77 fashion), and
  78 .It Em correctness
  79 (example: the ps program should provide exactly the process table
  80 information listing functionality described in its documentation - no more,
  81 no less.)
  82 .El
  83 .Pp
  84 The FSA
  85 contains a list of integrity, confidentiality, availability,
  86 and correctness requirements for the base
  87 .Fx
  88 system.
  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
  93 the FSA
  94 is a good way to begin the list of requirements for these commands,
  95 tools, and utilities.
  96 .Pp
  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
 100 the FSA.
 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.
 107 .Pp
 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.
 113 .Pp
 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
 121 the FSA.
 122 When referencing potential vulnerabilities
 123 described in the Secure Programming Practices manual page,
 124 .Xr sprog 7 ,
 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.
 129 .Ss Where to Stop
 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,
 139 and so on,
 140 as described by Thompson (see
 141 .Sx SEE ALSO ,
 142 below).
 143 .Pp
 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
 150 the FSA
 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
 156 described in
 157 the FSA.
 158 .Sh EXAMPLES
 159 Security considerations sections for most individual functions can follow
 160 this simple formula:
 161 .Pp
 162 .Bl -enum -offset indent -compact
 163 .It
 164 Provide one or two sentences describing each potential security
 165 problem, referencing
 166 the FSA
 167 to provide details whenever possible.
 168 .It
 169 Provide one or two sentences describing how to avoid each potential
 170 security problem.
 171 .It
 172 Provide a short example in code.
 173 .El
 174 .Pp
 175 This is an example security considerations section for the
 176 .Xr strcpy 3
 177 manual page:
 178 .Pp
 179 The
 180 .Fn strcpy
 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.
 184 (See
 185 the FSA.)
 186 .Pp
 187 Avoid using
 188 .Fn strcpy .
 189 Instead, use
 190 .Fn strncpy
 191 and ensure that no more characters are copied to the destination buffer
 192 than it can hold.
 193 Do not forget to NUL-terminate the destination buffer,
 194 as
 195 .Fn strncpy
 196 will not terminate the destination string if it is truncated.
 197 .Pp
 198 Note that
 199 .Fn strncpy
 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.
 206 Example:
 207 .Pp
 208 .Bd -literal
 209 void
 210 foo(const char *arbitrary_string)
 211 {
 212         char onstack[8];
 213
 214 #if defined(BAD)
 215         /*
 216          * This first strcpy is bad behavior.  Do not use strcpy()!
 217          */
 218         (void)strcpy(onstack, arbitrary_string);     /* BAD! */
 219 #elif defined(BETTER)
 220         /*
 221          * The following two lines demonstrate better use of
 222          * strncpy().
 223          */
 224         (void)strncpy(onstack, arbitrary_string, sizeof(onstack) - 1);
 225         onstack[sizeof(onstack - 1)] = '\\0';
 226 #elif defined(BEST)
 227         /*
 228          * These lines are even more robust due to testing for
 229          * truncation.
 230          */
 231         if (strlen(arbitrary_string) + 1 > sizeof(onstack))
 232                 err(1, "onstack would be truncated");
 233         (void)strncpy(onstack, arbitrary_string, sizeof(onstack));
 234 #endif
 235 }
 236 .Ed
 237 .Pp
 238 Security considerations sections for tools and commands
 239 are apt to be less formulaic.
 240 Let your list of potentially-violated security requirements
 241 be your guide;
 242 explain each one and list a solution in as concise a manner as possible.
 243 .Pp
 244 This is an example security considerations section for the
 245 .Xr rtld 1
 246 manual page:
 247 .Pp
 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.
 257 (See
 258 the FSA.)
 259 .Pp
 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.
 266 .Sh SEE ALSO
 267 .Xr groff_mdoc 7 ,
 268 .Xr security 7 ,
 269 .Xr sprog 7
 270 .Rs
 271 .%T "The FreeBSD Security Architecture"
 272 .%J file:///usr/share/doc/{to be determined}
 273 .Re
 274 .Rs
 275 .%A "Edward Amoroso, AT&T Bell Laboratories"
 276 .%B "Fundamentals of Computer Security Technology"
 277 .%I "P T R Prentice Hall"
 278 .%D "1994"
 279 .Re
 280 .Rs
 281 .%A "Ken Thompson"
 282 .%T "Reflections on Trusting Trust"
 283 .%J "Communications of the ACM"
 284 .%I "Association for Computing Machinery, Inc."
 285 .%P "761-763"
 286 .%N "Vol. 27, No. 8"
 287 .%D "August, 1984"
 288 .Re
 289 .Sh HISTORY
 290 The
 291 .Nm
 292 manual page first appeared in
 293 .Fx 5.0 .
 294 .Sh AUTHORS
 295 .An "Tim Fraser, NAI Labs CBOSS project." Aq tfraser@tislabs.com
 296 .An "Brian Feldman, NAI Labs CBOSS project." Aq bfeldman@tislabs.com