sec-doc.7 has been repo-copied to sdoc.7 to be consistent with sprog.7.

Sponsored by:	DARPA, NAI Labs

3 files changed, 3 insertions, 299 deletions

diff --git a/share/man/man7/Makefile b/share/man/man7/Makefile
index 9c5a52d..5af0c7d 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 firewall.7 ffs.7 hier.7 \
 	hostname.7 intro.7 mailaddr.7 operator.7 ports.7 release.7 \
-	security.7 sec-doc.7 sprog.7 stdint.7 tuning.7
+	sdoc.7 security.7 sprog.7 stdint.7 tuning.7
 MLINKS=	intro.7 miscellaneous.7
 
 .include <bsd.prog.mk>
diff --git a/share/man/man7/sdoc.7 b/share/man/man7/sdoc.7
index eb19069..28dc628 100644
--- a/share/man/man7/sdoc.7
+++ b/share/man/man7/sdoc.7
@@ -29,10 +29,10 @@
 .\" $FreeBSD$
 .\"
 .Dd October 12, 2001
-.Dt SEC-DOC 7
+.Dt SDOC 7
 .Os
 .Sh NAME
-.Nm sec-doc
+.Nm sdoc
 .Nd guide to adding security considerations sections to manual pages
 .Sh DESCRIPTION
 This document presents guidelines for
diff --git a/share/man/man7/sec-doc.7 b/share/man/man7/sec-doc.7
deleted file mode 100644
index eb19069..0000000
--- a/share/man/man7/sec-doc.7
+++ /dev/null
@@ -1,296 +0,0 @@
-.\" Copyright (c) 2001, 2002 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.
-.\" 3. The names of the authors may not be used to endorse or promote
-.\"    products derived from this software without specific prior written
-.\"    permission.
-.\"
-.\" 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.
-.\"
-.\" $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.
-Do not 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.  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));
-#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