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 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
  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 There 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
  75 fashion), and
  76 .It Em correctness
  77 (example: the ps program should provide exactly the process table
  78 information listing functionality described in its documentation - no more,
  79 no less.)
  80 .El
  81 .Pp
  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,
  89 .Xr sprog 7 ,
  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.
  94 .Ss Where to Stop
  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,
 104 and so on,
 105 as described by Thompson (see
 106 .Sx SEE ALSO ,
 107 below).
 108 .Pp
 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.
 114 .Sh EXAMPLES
 115 Security considerations sections for most individual functions can follow
 116 this simple formula:
 117 .Pp
 118 .Bl -enum -offset indent -compact
 119 .It
 120 Provide one or two sentences describing each potential security
 121 problem.
 122 .It
 123 Provide one or two sentences describing how to avoid each potential
 124 security problem.
 125 .It
 126 Provide a short example in code.
 127 .El
 128 .Pp
 129 This is an example security considerations section for the
 130 .Xr strcpy 3
 131 manual page:
 132 .Pp
 133 The
 134 .Fn strcpy
 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.
 138 .Pp
 139 Avoid using
 140 .Fn strcpy .
 141 Instead, use
 142 .Fn strncpy
 143 and ensure that no more characters are copied to the destination buffer
 144 than it can hold.
 145 Do not forget to NUL-terminate the destination buffer,
 146 as
 147 .Fn strncpy
 148 will not terminate the destination string if it is truncated.
 149 .Pp
 150 Note that
 151 .Fn strncpy
 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.
 158 Example:
 159 .Bd -literal
 160 void
 161 foo(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
 189 Security considerations sections for tools and commands
 190 are apt to be less formulaic.
 191 Let your list of potentially-violated security requirements
 192 be your guide;
 193 explain each one and list a solution in as concise a manner as possible.
 194 .Pp
 195 This is an example security considerations section for the
 196 .Xr rtld 1
 197 manual page:
 198 .Pp
 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.
 208 .Pp
 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.
 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
 235 The
 236 .Nm
 237 manual page first appeared in
 238 .Fx 5.0 .
 239 .Sh AUTHORS
 240 .An "Tim Fraser, NAI Labs CBOSS project." Aq tfraser@tislabs.com
 241 .An "Brian Feldman, NAI Labs CBOSS project." Aq bfeldman@tislabs.com