diff options
| -rw-r--r-- | share/man/man7/Makefile | 2 | ||||
| -rw-r--r-- | share/man/man7/sdoc.7 | 4 | ||||
| -rw-r--r-- | share/man/man7/sec-doc.7 | 296 |
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 |
