*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->FreeBSD man pages -> sdoc (7)              



NAME    [Toc]    [Back]

     sdoc -- guide to adding security considerations sections to manual pages

DESCRIPTION    [Toc]    [Back]

     This document presents guidelines for adding security considerations sections
 to manual pages.  It provides two typical examples.

     The guidelines for writing FreeBSD manual pages in groff_mdoc(7) mandate
     that each manual page describing a feature of the FreeBSD system should
     contain a security considerations section describing what security
     requirements can be broken through the misuse of that feature.  When
     writing these sections, authors should attempt to achieve a happy medium
     between two conflicting goals: brevity and completeness.  On one hand,
     security consideration sections must not be too verbose, or busy readers
     might be dissuaded from reading them.  On the other hand, security consideration
 sections must not be incomplete, or they will fail in their
     purpose of instructing the reader on how to avoid all insecure uses.
     This document provides guidelines for balancing brevity and completeness
     in the security consideration section for a given feature of the FreeBSD

   Where to Start    [Toc]    [Back]
     Begin by listing those general security requirements that can be violated
     through the misuse of the feature.  As described in the FreeBSD Security
     Architecture (FSA), there are four classes of security requirements:

	   integrity (example: non-administrators should not modify system

	   confidentiality (example: non-administrators should not view the
		   shadow password file),

	   availability (example: the web server should respond to client
		   requests in a timely fashion), and

	   correctness (example: the ps program should provide exactly the
		   process table information listing functionality described
		   in its documentation - no more, no less.)

     The FSA contains a list of integrity, confidentiality, availability, and
     correctness requirements for the base FreeBSD system.  Many commands,
     tools, and utilities documented in sections 1, 6, and 8 of the manual are
     partly responsible for meeting these base system requirements.  Consequently,
 borrowing entries from the list in the FSA is a good way to
     begin the list of requirements for these commands, tools, and utilities.

     Complex servers and subsystems may have their own integrity, confidentiality,
 availability and correctness requirements in addition to the
     system-wide ones listed in the FSA.  Listing these additional requirements
 will require some thought and analysis.  Correctness requirements
     will most often deal with configuration issues, especially in cases of
     programs that can load modules containing arbitrary functionality during

     For low-level features, such as the individual functions documented in
     sections 2, 3, and 9 of the manual, it is generally sufficient to proceed
     with only a single correctness requirement: simply that the function
     behaves as advertised.

     A good security considerations section should explain how the feature can
     be misused to violate each general security requirement in the list.
     Each explanation should be accompanied by instructions the reader should
     follow in order to avoid a violation.  For the sake of brevity, assume
     the reader is familiar with all of the concepts in the FSA.  When referencing
 potential vulnerabilities described in the Secure Programming
     Practices man page, sprog(7), likewise cross-reference that document
     rather than replicating information.  Whenever possible, refer to this
     document rather than reproducing the material it contains.

   Where to Stop    [Toc]    [Back]
     Security problems are often interrelated; individual problems often have
     far-reaching implications.  For example, the correctness of virtually any
     dynamically-linked program is dependent on the correct implementation and
     configuration of the run-time linker.  The correctness of this program,
     in turn, depends on the correctness of its libraries, the compiler used
     to build it, the correctness of the preceding compiler that was used to
     build that compiler, and so on, as described by Thompson (see SEE ALSO,

     Due to the need for brevity, security consideration sections should
     describe only those issues directly related to the feature that is the
     subject of the manual page.  Refer to other manual pages rather than
     duplicating the material found there.  Refer to generalized descriptions
     of problems in the FSA rather than referring to specific instances of
     those problems in other manual pages.  Ideally, each specific securityrelevant
 issue should be described in exactly one manual page, preferably
     as a specific instance of a general problem described in the FSA.

EXAMPLES    [Toc]    [Back]

     Security considerations sections for most individual functions can follow
     this simple formula:

	   1.	Provide one or two sentences describing each potential security
 problem, referencing the FSA to provide details whenever
	   2.	Provide one or two sentences describing how to avoid each
		potential security problem.
	   3.	Provide a short example in code.

     This is an example security considerations section for the strcpy(3) manual

     The strcpy() function is easily misused in a manner which enables malicious
 users to arbitrarily change a running program's functionality
     through a buffer overflow attack.	(See the FSA.)

     Avoid using strcpy().  Instead, use strncpy() and ensure that no more
     characters are copied to the destination buffer than it can hold.	Do not
     forget to NUL-terminate the destination buffer, as strncpy() will not
     terminate the destination string if it is truncated.

     Note that strncpy() can also be problematic.  It may be a security concern
 for a string to be truncated at all.	Since the truncated string
     will not be as long as the original, it may refer to a completely different
 resource and usage of the truncated resource could result in very
     incorrect behavior.  Example:

     foo(const char *arbitrary_string)
	     char onstack[8];

     #if defined(BAD)
	      * This first strcpy is bad behavior.  Do not use strcpy()!
	     (void)strcpy(onstack, arbitrary_string);	  /* BAD! */
     #elif defined(BETTER)
	      * The following two lines demonstrate better use of
	      * strncpy().
	     (void)strncpy(onstack, arbitrary_string, sizeof(onstack) - 1);
	     onstack[sizeof(onstack - 1)] = '\0';
     #elif defined(BEST)
	      * These lines are even more robust due to testing for
	      * truncation.
	     if (strlen(arbitrary_string) + 1 > sizeof(onstack))
		     err(1, "onstack would be truncated");
	     (void)strncpy(onstack, arbitrary_string, sizeof(onstack));

     Security considerations sections for tools and commands are apt to be
     less formulaic.  Let your list of potentially-violated security requirements
 be your guide; explain each one and list a solution in as concise a
     manner as possible.

     This is an example security considerations section for the rtld(1) manual

     Using the LD_LIBRARY_PATH and LD_PRELOAD environment variables, malicious
     users can cause the dynamic linker to link shared libraries of their own
     devising into the address space of processes running non-set-userID/group-ID
 programs.  These shared libraries can arbitrarily change the
     functionality of the program by replacing calls to standard library functions
 with calls to their own.  Although this feature is disabled for
     set-user-ID and set-group-ID programs, it can still be used to create
     Trojan horses in other programs.  (See the FSA.)

     All users should be aware that the correct operation of non set-userID/group-ID
 dynamically-linked programs depends on the proper configuration
 of these environment variables, and take care to avoid actions that
     might set them to values which would cause the run-time linker to link in
     shared libraries of unknown pedigree.

SEE ALSO    [Toc]    [Back]

     groff_mdoc(7), security(7), sprog(7)

     "The FreeBSD Security Architecture", file:///usr/share/doc/{to be

     Edward Amoroso, AT&T Bell Laboratories, Fundamentals of Computer Security
     Technology, P T R Prentice Hall, 1994.

     Ken Thompson, "Reflections on Trusting Trust", Association for Computing
     Machinery, Inc., Communications of the ACM, Vol. 27, No. 8, 761-763,
     August, 1984.

HISTORY    [Toc]    [Back]

     The sdoc manual page first appeared in FreeBSD 5.0.

AUTHORS    [Toc]    [Back]

     Tim Fraser, NAI Labs CBOSS project. <tfraser@tislabs.com>
     Brian Feldman, NAI Labs CBOSS project. <bfeldman@tislabs.com>

FreeBSD 5.2.1		       October 12, 2001 		 FreeBSD 5.2.1
[ Back ]
 Similar pages
Name OS Title
getNAME FreeBSD get name sections from manual pages
getNAME OpenBSD get NAME sections from manual source for whatis/apropos data base
manctl FreeBSD manipulating manual pages
fixman HP-UX fix manual pages for faster viewing with man(1)
man OpenBSD display the on-line manual pages
catman Linux create or update the pre-formatted manual pages
manpath Linux determine search path for manual pages
man FreeBSD format and display the on-line manual pages
c2man Linux generate manual pages from C source code
man HP-UX find manual information by keywords; print out a manual entry
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service