sec-doc.7 has been repo-copied to sdoc.7 to be consistent with sprog.7.
Sponsored by: DARPA, NAI Labs
This commit is contained in:
Chris Costello
parent
e6f0183bff
commit
2131a0f65d
@ -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>
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
Loading…
x
Reference in New Issue
Block a user