From owner-p4-projects@FreeBSD.ORG Thu Jun 11 17:03:27 2009 Return-Path: Delivered-To: p4-projects@freebsd.org Received: by hub.freebsd.org (Postfix, from userid 32767) id E9D6A1065700; Thu, 11 Jun 2009 17:03:26 +0000 (UTC) Delivered-To: perforce@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id A09A2106573A for ; Thu, 11 Jun 2009 17:03:22 +0000 (UTC) (envelope-from bb+lists.freebsd.perforce@cyrus.watson.org) Received: from repoman.freebsd.org (repoman.freebsd.org [IPv6:2001:4f8:fff6::29]) by mx1.freebsd.org (Postfix) with ESMTP id 19ED08FC19 for ; Thu, 11 Jun 2009 17:03:22 +0000 (UTC) (envelope-from bb+lists.freebsd.perforce@cyrus.watson.org) Received: from repoman.freebsd.org (localhost [127.0.0.1]) by repoman.freebsd.org (8.14.3/8.14.3) with ESMTP id n5BH3LZM004436 for ; Thu, 11 Jun 2009 17:03:21 GMT (envelope-from bb+lists.freebsd.perforce@cyrus.watson.org) Received: (from perforce@localhost) by repoman.freebsd.org (8.14.3/8.14.3/Submit) id n5BH3Ldh004434 for perforce@freebsd.org; Thu, 11 Jun 2009 17:03:21 GMT (envelope-from bb+lists.freebsd.perforce@cyrus.watson.org) Date: Thu, 11 Jun 2009 17:03:21 GMT Message-Id: <200906111703.n5BH3Ldh004434@repoman.freebsd.org> X-Authentication-Warning: repoman.freebsd.org: perforce set sender to bb+lists.freebsd.perforce@cyrus.watson.org using -f From: Robert Watson To: Perforce Change Reviews Cc: Subject: PERFORCE change 164121 for review X-BeenThere: p4-projects@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: p4 projects tree changes List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 11 Jun 2009 17:03:28 -0000 http://perforce.freebsd.org/chv.cgi?CH=164121 Change 164121 by rwatson@rwatson_freebsd_capabilities on 2009/06/11 17:02:44 Update man page. Affected files ... .. //depot/projects/trustedbsd/capabilities/src/libexec/rtld-elf-cap/rtld-elf-cap.1#4 edit Differences ... ==== //depot/projects/trustedbsd/capabilities/src/libexec/rtld-elf-cap/rtld-elf-cap.1#4 (text+ko) ==== @@ -32,7 +32,7 @@ .\" .\" $FreeBSD$ .\" -.Dd January 30, 2009 +.Dd June 11, 2009 .Os .Dt RTLD-ELF-CAP 1 .Sh NAME @@ -50,11 +50,14 @@ is intended to be directly executed using the .Xr fexeve 2 system call, and expects the binary to be passed as file descriptor -.Dv 3 . +.Dv 3 , +as well as additional libraries described by the +.Dv LD_CAPLIBINDEX +environmental variable. .Pp -Binaries for the sandbox environment are relocatable shared objects with the -addition of C start-up code (CSU) normally linked only into binaries -intended for direct execution. +Binaries for the sandbox environment are normal, dynamically linked binaries +as created by +.Xr gcc 1 . As with traditional .Fx binaries, the C run-time expects to begin execution with a @@ -62,28 +65,20 @@ function which will be passed execution-time arguments explicitly, as well as having access to inherited environmental variables. .Pp -A typical -.Xr gcc 1 -command line to build a sandbox-mode binary might be: -.Bd -literal -offset indent -gcc -o main.so main.c -shared /usr/lib/crt1.o -.Ed +Most capability-mode applications will be started using the APIs defined in +.Xr libcapability 3 , +which properly set up the run-time environment for +.Nm . .Sh IMPLEMENTATION NOTES Linking sandbox binaries as relocatable shared objects rather than linking them with a fixed virtual address allows them to be directly linked into consumers, if desired, for debugging or performance analysis purposes. -.Pp -The C run-time start-up code (CSU) is included to provide an ELF brand as -well as -.Dv _start -function sufficient to properly align the stack, start C run-time services -such as profiling and thread-local storage, and to provide and pass command -line arguments and environmental variables to the executing binary. .Sh SEE ALSO .Xr gcc 1 , .Xr ld-elf.so.1 1 , .Xr cap_enter 2 , -.Xr fexecve 2 +.Xr fexecve 2 , +.Xr libcapability 3 .Sh HISTORY Support for capabilities and capabilities mode was developed as part of the .Tn TrustedBSD @@ -91,6 +86,10 @@ .Sh BUGS WARNING: THIS IS EXPERIMENTAL SECURITY SOFTWARE THAT MUST NOT BE RELIED ON IN PRODUCTION SYSTEMS. IT WILL BREAK YOUR SOFTWARE IN NEW AND UNEXPECTED WAYS. +.Pp +The format of +.Dv LD_CAPLIBINDEX +is not documented, and may change. .Sh AUTHORS .Nm is derived from