summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--Doc/lib/libbastion.tex17
-rw-r--r--Doc/lib/librexec.tex77
-rw-r--r--Doc/libbastion.tex17
-rw-r--r--Doc/librexec.tex77
4 files changed, 104 insertions, 84 deletions
diff --git a/Doc/lib/libbastion.tex b/Doc/lib/libbastion.tex
index c405c64..b5bec15 100644
--- a/Doc/lib/libbastion.tex
+++ b/Doc/lib/libbastion.tex
@@ -1,7 +1,6 @@
\section{Standard Module \sectcode{Bastion}}
\label{module-Bastion}
\stmodindex{Bastion}
-\setindexsubitem{(in module Bastion)}
% I'm concerned that the word 'bastion' won't be understood by people
% for whom English is a second language, making the module name
@@ -17,7 +16,8 @@ other, unsafe attributes.
% I've punted on the issue of documenting keyword arguments for now.
-\begin{funcdesc}{Bastion}{object\optional{, filter, name, class}}
+\begin{funcdesc}{Bastion}{object\optional{, filter\optional{,
+ name\optional{, class}}}}
Protect the object \var{object}, returning a bastion for the
object. Any attempt to access one of the object's attributes will
have to be approved by the \var{filter} function; if the access is
@@ -32,8 +32,17 @@ will be \samp{<Bastion for \var{name}>} if a value for
\var{name} is provided; otherwise, \samp{repr(\var{object})} will be
used.
-\var{class}, if present, would be a subclass of \class{BastionClass};
+\var{class}, if present, should be a subclass of \class{BastionClass};
see the code in \file{bastion.py} for the details. Overriding the
default \class{BastionClass} will rarely be required.
-
\end{funcdesc}
+
+
+\begin{classdesc}{BastionClass}{getfunc, name}
+Class which actually implements bastion objects. This is the default
+class used by \function{Bastion()}. The \var{getfunc} parameter is a
+function which returns the value of an attribute which should be
+exposed to the restricted execution environment when called with the
+name of the attribute as the only parameter. \var{name} is used to
+construct the \function{repr()} of the \class{BastionClass} instance.
+\end{classdesc}
diff --git a/Doc/lib/librexec.tex b/Doc/lib/librexec.tex
index e301f81..03e8284 100644
--- a/Doc/lib/librexec.tex
+++ b/Doc/lib/librexec.tex
@@ -50,8 +50,7 @@ instance won't have any effect; instead, create a subclass of
Instances of the new class will then use those new values. All these
attributes are tuples of strings.
-\setindexsubitem{(RExec object attribute)}
-\begin{datadesc}{nok_builtin_names}
+\begin{memberdesc}{nok_builtin_names}
Contains the names of built-in functions which will \emph{not} be
available to programs running in the restricted environment. The
value for \class{RExec} is \code{('open',} \code{'reload',}
@@ -61,9 +60,9 @@ override this variable should probably start with the value from the
base class and concatenate additional forbidden functions --- when new
dangerous built-in functions are added to Python, they will also be
added to this module.)
-\end{datadesc}
+\end{memberdesc}
-\begin{datadesc}{ok_builtin_modules}
+\begin{memberdesc}{ok_builtin_modules}
Contains the names of built-in modules which can be safely imported.
The value for \class{RExec} is \code{('audioop',} \code{'array',}
\code{'binascii',} \code{'cmath',} \code{'errno',} \code{'imageop',}
@@ -72,16 +71,16 @@ The value for \class{RExec} is \code{('audioop',} \code{'array',}
\code{'strop',} \code{'struct',} \code{'time')}. A similar remark
about overriding this variable applies --- use the value from the base
class as a starting point.
-\end{datadesc}
+\end{memberdesc}
-\begin{datadesc}{ok_path}
+\begin{memberdesc}{ok_path}
Contains the directories which will be searched when an \keyword{import}
is performed in the restricted environment.
The value for \class{RExec} is the same as \code{sys.path} (at the time
the module is loaded) for unrestricted code.
-\end{datadesc}
+\end{memberdesc}
-\begin{datadesc}{ok_posix_names}
+\begin{memberdesc}{ok_posix_names}
% Should this be called ok_os_names?
Contains the names of the functions in the \module{os} module which will be
available to programs running in the restricted environment. The
@@ -90,68 +89,69 @@ value for \class{RExec} is \code{('error',} \code{'fstat',}
\code{'times',} \code{'uname',} \code{'getpid',} \code{'getppid',}
\code{'getcwd',} \code{'getuid',} \code{'getgid',} \code{'geteuid',}
\code{'getegid')}.
-\end{datadesc}
+\end{memberdesc}
-\begin{datadesc}{ok_sys_names}
+\begin{memberdesc}{ok_sys_names}
Contains the names of the functions and variables in the \module{sys}
module which will be available to programs running in the restricted
environment. The value for \class{RExec} is \code{('ps1',}
\code{'ps2',} \code{'copyright',} \code{'version',} \code{'platform',}
\code{'exit',} \code{'maxint')}.
-\end{datadesc}
+\end{memberdesc}
+
\class{RExec} instances support the following methods:
-\setindexsubitem{(RExec object method)}
-\begin{funcdesc}{r_eval}{code}
+\begin{methoddesc}{r_eval}{code}
\var{code} must either be a string containing a Python expression, or
a compiled code object, which will be evaluated in the restricted
environment's \module{__main__} module. The value of the expression or
code object will be returned.
-\end{funcdesc}
+\end{methoddesc}
-\begin{funcdesc}{r_exec}{code}
+\begin{methoddesc}{r_exec}{code}
\var{code} must either be a string containing one or more lines of
Python code, or a compiled code object, which will be executed in the
restricted environment's \module{__main__} module.
-\end{funcdesc}
+\end{methoddesc}
-\begin{funcdesc}{r_execfile}{filename}
+\begin{methoddesc}{r_execfile}{filename}
Execute the Python code contained in the file \var{filename} in the
restricted environment's \module{__main__} module.
-\end{funcdesc}
+\end{methoddesc}
Methods whose names begin with \samp{s_} are similar to the functions
beginning with \samp{r_}, but the code will be granted access to
restricted versions of the standard I/O streams \code{sys.stdin},
\code{sys.stderr}, and \code{sys.stdout}.
-\begin{funcdesc}{s_eval}{code}
+\begin{methoddesc}{s_eval}{code}
\var{code} must be a string containing a Python expression, which will
be evaluated in the restricted environment.
-\end{funcdesc}
+\end{methoddesc}
-\begin{funcdesc}{s_exec}{code}
+\begin{methoddesc}{s_exec}{code}
\var{code} must be a string containing one or more lines of Python code,
which will be executed in the restricted environment.
-\end{funcdesc}
+\end{methoddesc}
-\begin{funcdesc}{s_execfile}{code}
+\begin{methoddesc}{s_execfile}{code}
Execute the Python code contained in the file \var{filename} in the
restricted environment.
-\end{funcdesc}
+\end{methoddesc}
\class{RExec} objects must also support various methods which will be
implicitly called by code executing in the restricted environment.
Overriding these methods in a subclass is used to change the policies
enforced by a restricted environment.
-\begin{funcdesc}{r_import}{modulename\optional{, globals, locals, fromlist}}
+\begin{methoddesc}{r_import}{modulename\optional{, globals\optional{,
+ locals\optional{, fromlist}}}}
Import the module \var{modulename}, raising an \exception{ImportError}
exception if the module is considered unsafe.
-\end{funcdesc}
+\end{methoddesc}
-\begin{funcdesc}{r_open}{filename\optional{, mode\optional{, bufsize}}}
+\begin{methoddesc}{r_open}{filename\optional{, mode\optional{, bufsize}}}
Method called when \function{open()} is called in the restricted
environment. The arguments are identical to those of \function{open()},
and a file object (or a class instance compatible with file objects)
@@ -159,32 +159,33 @@ should be returned. \class{RExec}'s default behaviour is allow opening
any file for reading, but forbidding any attempt to write a file. See
the example below for an implementation of a less restrictive
\method{r_open()}.
-\end{funcdesc}
+\end{methoddesc}
-\begin{funcdesc}{r_reload}{module}
+\begin{methoddesc}{r_reload}{module}
Reload the module object \var{module}, re-parsing and re-initializing it.
-\end{funcdesc}
+\end{methoddesc}
-\begin{funcdesc}{r_unload}{module}
+\begin{methoddesc}{r_unload}{module}
Unload the module object \var{module} (i.e., remove it from the
restricted environment's \code{sys.modules} dictionary).
-\end{funcdesc}
+\end{methoddesc}
And their equivalents with access to restricted standard I/O streams:
-\begin{funcdesc}{s_import}{modulename\optional{, globals, locals, fromlist}}
+\begin{methoddesc}{s_import}{modulename\optional{, globals\optional{,
+ locals\optional{, fromlist}}}}
Import the module \var{modulename}, raising an \exception{ImportError}
exception if the module is considered unsafe.
-\end{funcdesc}
+\end{methoddesc}
-\begin{funcdesc}{s_reload}{module}
+\begin{methoddesc}{s_reload}{module}
Reload the module object \var{module}, re-parsing and re-initializing it.
-\end{funcdesc}
+\end{methoddesc}
-\begin{funcdesc}{s_unload}{module}
+\begin{methoddesc}{s_unload}{module}
Unload the module object \var{module}.
% XXX what are the semantics of this?
-\end{funcdesc}
+\end{methoddesc}
\subsection{An example}
diff --git a/Doc/libbastion.tex b/Doc/libbastion.tex
index c405c64..b5bec15 100644
--- a/Doc/libbastion.tex
+++ b/Doc/libbastion.tex
@@ -1,7 +1,6 @@
\section{Standard Module \sectcode{Bastion}}
\label{module-Bastion}
\stmodindex{Bastion}
-\setindexsubitem{(in module Bastion)}
% I'm concerned that the word 'bastion' won't be understood by people
% for whom English is a second language, making the module name
@@ -17,7 +16,8 @@ other, unsafe attributes.
% I've punted on the issue of documenting keyword arguments for now.
-\begin{funcdesc}{Bastion}{object\optional{, filter, name, class}}
+\begin{funcdesc}{Bastion}{object\optional{, filter\optional{,
+ name\optional{, class}}}}
Protect the object \var{object}, returning a bastion for the
object. Any attempt to access one of the object's attributes will
have to be approved by the \var{filter} function; if the access is
@@ -32,8 +32,17 @@ will be \samp{<Bastion for \var{name}>} if a value for
\var{name} is provided; otherwise, \samp{repr(\var{object})} will be
used.
-\var{class}, if present, would be a subclass of \class{BastionClass};
+\var{class}, if present, should be a subclass of \class{BastionClass};
see the code in \file{bastion.py} for the details. Overriding the
default \class{BastionClass} will rarely be required.
-
\end{funcdesc}
+
+
+\begin{classdesc}{BastionClass}{getfunc, name}
+Class which actually implements bastion objects. This is the default
+class used by \function{Bastion()}. The \var{getfunc} parameter is a
+function which returns the value of an attribute which should be
+exposed to the restricted execution environment when called with the
+name of the attribute as the only parameter. \var{name} is used to
+construct the \function{repr()} of the \class{BastionClass} instance.
+\end{classdesc}
diff --git a/Doc/librexec.tex b/Doc/librexec.tex
index e301f81..03e8284 100644
--- a/Doc/librexec.tex
+++ b/Doc/librexec.tex
@@ -50,8 +50,7 @@ instance won't have any effect; instead, create a subclass of
Instances of the new class will then use those new values. All these
attributes are tuples of strings.
-\setindexsubitem{(RExec object attribute)}
-\begin{datadesc}{nok_builtin_names}
+\begin{memberdesc}{nok_builtin_names}
Contains the names of built-in functions which will \emph{not} be
available to programs running in the restricted environment. The
value for \class{RExec} is \code{('open',} \code{'reload',}
@@ -61,9 +60,9 @@ override this variable should probably start with the value from the
base class and concatenate additional forbidden functions --- when new
dangerous built-in functions are added to Python, they will also be
added to this module.)
-\end{datadesc}
+\end{memberdesc}
-\begin{datadesc}{ok_builtin_modules}
+\begin{memberdesc}{ok_builtin_modules}
Contains the names of built-in modules which can be safely imported.
The value for \class{RExec} is \code{('audioop',} \code{'array',}
\code{'binascii',} \code{'cmath',} \code{'errno',} \code{'imageop',}
@@ -72,16 +71,16 @@ The value for \class{RExec} is \code{('audioop',} \code{'array',}
\code{'strop',} \code{'struct',} \code{'time')}. A similar remark
about overriding this variable applies --- use the value from the base
class as a starting point.
-\end{datadesc}
+\end{memberdesc}
-\begin{datadesc}{ok_path}
+\begin{memberdesc}{ok_path}
Contains the directories which will be searched when an \keyword{import}
is performed in the restricted environment.
The value for \class{RExec} is the same as \code{sys.path} (at the time
the module is loaded) for unrestricted code.
-\end{datadesc}
+\end{memberdesc}
-\begin{datadesc}{ok_posix_names}
+\begin{memberdesc}{ok_posix_names}
% Should this be called ok_os_names?
Contains the names of the functions in the \module{os} module which will be
available to programs running in the restricted environment. The
@@ -90,68 +89,69 @@ value for \class{RExec} is \code{('error',} \code{'fstat',}
\code{'times',} \code{'uname',} \code{'getpid',} \code{'getppid',}
\code{'getcwd',} \code{'getuid',} \code{'getgid',} \code{'geteuid',}
\code{'getegid')}.
-\end{datadesc}
+\end{memberdesc}
-\begin{datadesc}{ok_sys_names}
+\begin{memberdesc}{ok_sys_names}
Contains the names of the functions and variables in the \module{sys}
module which will be available to programs running in the restricted
environment. The value for \class{RExec} is \code{('ps1',}
\code{'ps2',} \code{'copyright',} \code{'version',} \code{'platform',}
\code{'exit',} \code{'maxint')}.
-\end{datadesc}
+\end{memberdesc}
+
\class{RExec} instances support the following methods:
-\setindexsubitem{(RExec object method)}
-\begin{funcdesc}{r_eval}{code}
+\begin{methoddesc}{r_eval}{code}
\var{code} must either be a string containing a Python expression, or
a compiled code object, which will be evaluated in the restricted
environment's \module{__main__} module. The value of the expression or
code object will be returned.
-\end{funcdesc}
+\end{methoddesc}
-\begin{funcdesc}{r_exec}{code}
+\begin{methoddesc}{r_exec}{code}
\var{code} must either be a string containing one or more lines of
Python code, or a compiled code object, which will be executed in the
restricted environment's \module{__main__} module.
-\end{funcdesc}
+\end{methoddesc}
-\begin{funcdesc}{r_execfile}{filename}
+\begin{methoddesc}{r_execfile}{filename}
Execute the Python code contained in the file \var{filename} in the
restricted environment's \module{__main__} module.
-\end{funcdesc}
+\end{methoddesc}
Methods whose names begin with \samp{s_} are similar to the functions
beginning with \samp{r_}, but the code will be granted access to
restricted versions of the standard I/O streams \code{sys.stdin},
\code{sys.stderr}, and \code{sys.stdout}.
-\begin{funcdesc}{s_eval}{code}
+\begin{methoddesc}{s_eval}{code}
\var{code} must be a string containing a Python expression, which will
be evaluated in the restricted environment.
-\end{funcdesc}
+\end{methoddesc}
-\begin{funcdesc}{s_exec}{code}
+\begin{methoddesc}{s_exec}{code}
\var{code} must be a string containing one or more lines of Python code,
which will be executed in the restricted environment.
-\end{funcdesc}
+\end{methoddesc}
-\begin{funcdesc}{s_execfile}{code}
+\begin{methoddesc}{s_execfile}{code}
Execute the Python code contained in the file \var{filename} in the
restricted environment.
-\end{funcdesc}
+\end{methoddesc}
\class{RExec} objects must also support various methods which will be
implicitly called by code executing in the restricted environment.
Overriding these methods in a subclass is used to change the policies
enforced by a restricted environment.
-\begin{funcdesc}{r_import}{modulename\optional{, globals, locals, fromlist}}
+\begin{methoddesc}{r_import}{modulename\optional{, globals\optional{,
+ locals\optional{, fromlist}}}}
Import the module \var{modulename}, raising an \exception{ImportError}
exception if the module is considered unsafe.
-\end{funcdesc}
+\end{methoddesc}
-\begin{funcdesc}{r_open}{filename\optional{, mode\optional{, bufsize}}}
+\begin{methoddesc}{r_open}{filename\optional{, mode\optional{, bufsize}}}
Method called when \function{open()} is called in the restricted
environment. The arguments are identical to those of \function{open()},
and a file object (or a class instance compatible with file objects)
@@ -159,32 +159,33 @@ should be returned. \class{RExec}'s default behaviour is allow opening
any file for reading, but forbidding any attempt to write a file. See
the example below for an implementation of a less restrictive
\method{r_open()}.
-\end{funcdesc}
+\end{methoddesc}
-\begin{funcdesc}{r_reload}{module}
+\begin{methoddesc}{r_reload}{module}
Reload the module object \var{module}, re-parsing and re-initializing it.
-\end{funcdesc}
+\end{methoddesc}
-\begin{funcdesc}{r_unload}{module}
+\begin{methoddesc}{r_unload}{module}
Unload the module object \var{module} (i.e., remove it from the
restricted environment's \code{sys.modules} dictionary).
-\end{funcdesc}
+\end{methoddesc}
And their equivalents with access to restricted standard I/O streams:
-\begin{funcdesc}{s_import}{modulename\optional{, globals, locals, fromlist}}
+\begin{methoddesc}{s_import}{modulename\optional{, globals\optional{,
+ locals\optional{, fromlist}}}}
Import the module \var{modulename}, raising an \exception{ImportError}
exception if the module is considered unsafe.
-\end{funcdesc}
+\end{methoddesc}
-\begin{funcdesc}{s_reload}{module}
+\begin{methoddesc}{s_reload}{module}
Reload the module object \var{module}, re-parsing and re-initializing it.
-\end{funcdesc}
+\end{methoddesc}
-\begin{funcdesc}{s_unload}{module}
+\begin{methoddesc}{s_unload}{module}
Unload the module object \var{module}.
% XXX what are the semantics of this?
-\end{funcdesc}
+\end{methoddesc}
\subsection{An example}