Add in the new security documentation guidelines document.

Obtained from:	NAI Labs CBOSS Project
Sponsored by:	DARPA, NAI Labs
This commit is contained in:
Chris Costello 2001-12-22 22:07:02 +00:00
parent 7270230e88
commit 1fc841e3ab
3 changed files with 537 additions and 1 deletions

View File

@ -4,7 +4,7 @@
#MISSING: eqnchar.7 ms.7 term.7
MAN= ascii.7 build.7 clocks.7 environ.7 hier.7 hostname.7 intro.7 \
mailaddr.7 operator.7 ports.7 security.7 tuning.7 firewall.7 \
sprog.7 style.perl.7
sec-doc.7 sprog.7 style.perl.7
MLINKS= intro.7 miscellaneous.7
.include <bsd.prog.mk>

268
share/man/man7/sdoc.7 Normal file
View File

@ -0,0 +1,268 @@
.\" 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.
.Sh 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.
.Sh 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 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

268
share/man/man7/sec-doc.7 Normal file
View File

@ -0,0 +1,268 @@
.\" 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.
.Sh 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.
.Sh 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 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