Add in the new security documentation guidelines document.

Obtained from:	NAI Labs CBOSS Project
Sponsored by:	DARPA, NAI Labs

3 files changed, 537 insertions, 1 deletions

diff --git a/share/man/man7/Makefile b/share/man/man7/Makefile
index 0d90c4a..090e5f6 100644
--- a/share/man/man7/Makefile
+++ b/share/man/man7/Makefile
@@ -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>
diff --git a/share/man/man7/sdoc.7 b/share/man/man7/sdoc.7
new file mode 100644
index 0000000..e3b6e4d
--- /dev/null
+++ b/share/man/man7/sdoc.7
@@ -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
diff --git a/share/man/man7/sec-doc.7 b/share/man/man7/sec-doc.7
new file mode 100644
index 0000000..e3b6e4d
--- /dev/null
+++ b/share/man/man7/sec-doc.7
@@ -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