.\" Copyright (c) 2001 Networks Associates Technology, Inc.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" From Id: sec-doc.7,v 1.7 2001/12/22 00:14:12 rwatson Exp
.\" $FreeBSD$
.\"
.Dd October 12, 2001
.Dt SEC-DOC 7
.Os
.Sh NAME
.Nm sec-doc
.Nd guide to adding security considerations sections to manual pages
.Sh DESCRIPTION
This document presents guidelines for
adding security considerations sections to manual pages.
It provides two typical examples.
.Pp
The guidelines for writing 
.Fx
manual pages in
.Xr groff_mdoc 7
mandate that each manual page describing a feature of the 
.Fx
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
.Fx
system.
.Ss Where to Start
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:
.Bl -hang -offset indent
.It Em integrity
(example: non-administrators should not modify system binaries),
.It Em confidentiality 
(example: non-administrators should not view the shadow password file),
.It Em availability
(example: the web server should respond to client requests in a timely
fashion), and
.It Em correctness
(example: the ps program should provide exactly the process table
information listing functionality described in its documentation - no more,
no less.)
.El
.Pp
The FSA
contains a list of integrity, confidentiality, availability,
and correctness requirements for the base
.Fx
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.
.Pp
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 run-time.
.Pp
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.
.Pp
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,
.Xr sprog 7 ,
likewise cross-reference that document
rather than replicating information.
Whenever possible, refer to this document
rather than reproducing the material it contains.
.Ss Where to Stop
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
.Sx SEE ALSO ,
below).
.Pp
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 security-relevant issue
should be described in exactly one manual page,
preferably as a specific instance of a general problem
described in
the FSA.
.Sh EXAMPLES
Security considerations sections for most individual functions can follow
this simple formula:
.Pp
.Bl -enum -offset indent -compact
.It
Provide one or two sentences describing each potential security
problem, referencing
the FSA
to provide details whenever possible.
.It
Provide one or two sentences describing how to avoid each potential
security problem.
.It
Provide a short example in code.
.El
.Pp
This is an example security considerations section for the
.Xr strcpy 3
manual page:
.Pp
The
.Fn 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.)
.Pp
Avoid using
.Fn strcpy .
Instead, use
.Fn strncpy 
and ensure that no more characters are copied to the destination buffer
than it can hold.
Don't forget to NUL-terminate the destination buffer,
as
.Fn strncpy
will not terminate the destination string if it is truncated.
.Pp
Note that
.Fn 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:
.Pp
.Bd -literal
void
foo(const char *arbitrary_string)
{
	char onstack[8];

#if defined(BAD)
	/*
	 * This first strcpy is bad behavior.  Don't 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));
#endif
}
.Ed
.Pp
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.
.Pp
This is an example security considerations section for the
.Xr rtld 1
manual page:
.Pp
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-user-ID/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.)
.Pp
All users should be aware that the correct operation of non
set-user-ID/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.
.Sh SEE ALSO
.Xr groff_mdoc 7 ,
.Xr security 7 ,
.Xr sprog 7
.Rs
.%T  "The FreeBSD Security Architecture"
.%J file:///usr/share/doc/{to be determined}
.Re
.Rs
.%A "Edward Amoroso, AT&T Bell Laboratories"
.%B "Fundamentals of Computer Security Technology"
.%I "P T R Prentice Hall"
.%D "1994"
.Re
.Rs
.%A "Ken Thompson"
.%T "Reflections on Trusting Trust"
.%J "Communications of the ACM"
.%I "Association for Computing Machinery, Inc."
.%P "761-763"
.%N "Vol. 27, No. 8"
.%D "August, 1984"
.Re
.Sh HISTORY
The
.Nm
manual page first appeared in
.Fx 5.0 .
.Sh AUTHORS
.An "Tim Fraser, NAI Labs CBOSS project." Aq tfraser@tislabs.com
.An "Brian Feldman, NAI Labs CBOSS project." Aq bfeldman@tislabs.com