Skip to content

Commit 4a6e8a1

Browse files
author
tstarling
committed
Add LuaSandbox extension
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@347858 c90b9560-bf6c-de11-be94-00142212c4b1
1 parent 3c5eb8e commit 4a6e8a1

39 files changed

+3215
-0
lines changed

‎appendices/extensions.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -431,6 +431,7 @@
431431
<listitem><para><xref linkend="book.lapack"/></para></listitem>
432432
<listitem><para><xref linkend="book.libevent"/></para></listitem>
433433
<listitem><para><xref linkend="book.lua"/></para></listitem>
434+
<listitem><para><xref linkend="book.luasandbox"/></para></listitem>
434435
<listitem><para><xref linkend="book.lzf"/></para></listitem>
435436
<listitem><para><xref linkend="book.mailparse"/></para></listitem>
436437
<listitem><para><xref linkend="book.maxdb"/></para></listitem>

‎reference/luasandbox/book.xml

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- $Revision$ -->
3+
4+
<book xml:id="book.luasandbox" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5+
<title>LuaSandbox</title>
6+
<titleabbrev>LuaSandbox</titleabbrev>
7+
8+
<preface xml:id="intro.luasandbox">
9+
&reftitle.intro;
10+
<para>
11+
LuaSandbox is an extension for PHP 5, PHP 7, and HHVM to allow safely
12+
running untrusted Lua 5.1 code from within PHP.
13+
</para>
14+
<para>
15+
Differences compared to the <link linkend="book.lua">Lua</link> extension:
16+
<itemizedlist>
17+
<listitem>
18+
<para>
19+
LuaSandbox has support for time and memory limits.
20+
</para>
21+
</listitem>
22+
<listitem>
23+
<para>
24+
LuaSandbox provides a default-safe environment for running untrusted code.
25+
Stock Lua functions were reviewed for security, and several were patched
26+
accordingly.
27+
</para>
28+
</listitem>
29+
<listitem>
30+
<para>
31+
LuaSandbox has a PHP interface which is more complex, precise and powerful,
32+
but it is less convenient for developers.
33+
</para>
34+
</listitem>
35+
<listitem>
36+
<para>
37+
LuaSandbox supports only Lua 5.1. It is difficult to change this, because
38+
LuaSandbox uses heavily modified Lua standard libraries, and
39+
due to the lack of backwards compatibility between major Lua versions.
40+
LuaSandbox aims to maximise backwards compatibility with user-supplied
41+
scripts.
42+
</para>
43+
</listitem>
44+
</itemizedlist>
45+
</para>
46+
</preface>
47+
48+
&reference.luasandbox.setup;
49+
<!-- &reference.luasandbox.constants; -->
50+
&reference.luasandbox.differences;
51+
&reference.luasandbox.examples;
52+
53+
<!-- &reference.luasandbox.reference; -->
54+
55+
&reference.luasandbox.luasandbox;
56+
&reference.luasandbox.luasandboxfunction;
57+
&reference.luasandbox.luasandboxerror;
58+
&reference.luasandbox.luasandboxerrorerror;
59+
&reference.luasandbox.luasandboxfatalerror;
60+
&reference.luasandbox.luasandboxmemoryerror;
61+
&reference.luasandbox.luasandboxruntimeerror;
62+
&reference.luasandbox.luasandboxsyntaxerror;
63+
&reference.luasandbox.luasandboxtimeouterror;
64+
65+
</book>
66+
67+
<!-- Keep this comment at the end of the file
68+
Local variables:
69+
mode: sgml
70+
sgml-omittag:t
71+
sgml-shorttag:t
72+
sgml-minimize-attributes:nil
73+
sgml-always-quote-attributes:t
74+
sgml-indent-step:1
75+
sgml-indent-data:t
76+
indent-tabs-mode:nil
77+
sgml-parent-document:nil
78+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
79+
sgml-exposed-tags:nil
80+
sgml-local-catalogs:nil
81+
sgml-local-ecat-files:nil
82+
End:
83+
vim600: syn=xml fen fdm=syntax fdl=2 si
84+
vim: et tw=78 syn=sgml
85+
vi: ts=1 sw=1
86+
-->

‎reference/luasandbox/configure.xml

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- $Revision$ -->
3+
4+
<section xml:id="luasandbox.installation" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5+
&reftitle.install;
6+
7+
<para>
8+
&pecl.info;
9+
<link xlink:href="&url.pecl.package;luasandbox">&url.pecl.package;luasandbox</link>
10+
</para>
11+
12+
</section>
13+
14+
15+
<!-- Keep this comment at the end of the file
16+
Local variables:
17+
mode: sgml
18+
sgml-omittag:t
19+
sgml-shorttag:t
20+
sgml-minimize-attributes:nil
21+
sgml-always-quote-attributes:t
22+
sgml-indent-step:1
23+
sgml-indent-data:t
24+
indent-tabs-mode:nil
25+
sgml-parent-document:nil
26+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
27+
sgml-exposed-tags:nil
28+
sgml-local-catalogs:nil
29+
sgml-local-ecat-files:nil
30+
End:
31+
vim600: syn=xml fen fdm=syntax fdl=2 si
32+
vim: et tw=78 syn=sgml
33+
vi: ts=1 sw=1
34+
-->

‎reference/luasandbox/constants.xml

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- $Revision$ -->
3+
4+
<appendix xml:id="luasandbox.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5+
&reftitle.constants;
6+
&no.constants;
7+
</appendix>
8+
9+
<!-- Keep this comment at the end of the file
10+
Local variables:
11+
mode: sgml
12+
sgml-omittag:t
13+
sgml-shorttag:t
14+
sgml-minimize-attributes:nil
15+
sgml-always-quote-attributes:t
16+
sgml-indent-step:1
17+
sgml-indent-data:t
18+
indent-tabs-mode:nil
19+
sgml-parent-document:nil
20+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
21+
sgml-exposed-tags:nil
22+
sgml-local-catalogs:nil
23+
sgml-local-ecat-files:nil
24+
End:
25+
vim600: syn=xml fen fdm=syntax fdl=2 si
26+
vim: et tw=78 syn=sgml
27+
vi: ts=1 sw=1
28+
-->

‎reference/luasandbox/differences.xml

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- $Revision$ -->
3+
<chapter xml:id="reference.luasandbox.differences" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
4+
<title>Differences from Standard Lua</title>
5+
6+
<para>
7+
LuaSandbox provides a sandboxed environment which differs in some ways from standard Lua 5.1.
8+
</para>
9+
10+
<simplesect xml:id="reference.luasandbox.differences.unavailable">
11+
<title>Features that are not available</title>
12+
<para>
13+
<itemizedlist>
14+
<listitem>
15+
<para>
16+
<literal>dofile()</literal>, <literal>loadfile()</literal>, and the <literal>io</literal> package, as they allow direct filesystem access. If needed, filesystem access should be done via PHP callbacks.
17+
</para>
18+
</listitem>
19+
<listitem>
20+
<para>
21+
The <literal>package</literal> package, including <literal>require()</literal> and <literal>module()</literal>, as it depends heavily on direct filesystem access. A pure-Lua rewrite such as that used in the MediaUncyclo Scribunto extension may be used instead.
22+
</para>
23+
</listitem>
24+
<listitem>
25+
<para>
26+
<literal>load()</literal> and <literal>loadstring()</literal>, to allow for static analysis of Lua code.
27+
</para>
28+
</listitem>
29+
<listitem>
30+
<para>
31+
<literal>print()</literal>, since it outputs to standard output. If needed, output should be done via PHP callbacks.
32+
</para>
33+
</listitem>
34+
<listitem>
35+
<para>
36+
Most of the <literal>os</literal> package, as it allows manipulation of the process and executing of other processes.
37+
</para>
38+
<para>
39+
<itemizedlist>
40+
<listitem>
41+
<para>
42+
<literal>os.clock()</literal>, <literal>os.date()</literal>, <literal>os.difftime()</literal>, and <literal>os.time()</literal> remain available.
43+
</para>
44+
</listitem>
45+
</itemizedlist>
46+
</para>
47+
</listitem>
48+
<listitem>
49+
<para>
50+
Most of the <literal>debug</literal> package, as it allows manipulation of Lua state and metadata in ways that can break sandboxing.
51+
</para>
52+
<para>
53+
<itemizedlist>
54+
<listitem>
55+
<para>
56+
<literal>debug.traceback()</literal> remains available.
57+
</para>
58+
</listitem>
59+
</itemizedlist>
60+
</para>
61+
</listitem>
62+
<listitem>
63+
<para>
64+
<literal>string.dump()</literal>, as it may expose internal data.
65+
</para>
66+
</listitem>
67+
<listitem>
68+
<para>
69+
<literal>collectgarbage()</literal>, <literal>gcinfo()</literal>, and the <literal>coroutine</literal> package have not been reviewed for security.
70+
</para>
71+
</listitem>
72+
</itemizedlist>
73+
</para>
74+
</simplesect>
75+
76+
<simplesect xml:id="reference.luasandbox.differences.modified">
77+
<title>Features that have been modified</title>
78+
<para>
79+
<itemizedlist>
80+
<listitem>
81+
<para>
82+
<literal>pcall()</literal> and <literal>xpcall()</literal> cannot catch certain errors, particularly timeout errors.
83+
</para>
84+
</listitem>
85+
<listitem>
86+
<para>
87+
<literal>tostring()</literal> does not include pointer addresses.
88+
</para>
89+
</listitem>
90+
<listitem>
91+
<para>
92+
<literal>string.match()</literal> has been patched to limit the recursion depth and to periodically check for a timeout.
93+
</para>
94+
</listitem>
95+
<listitem>
96+
<para>
97+
<literal>math.random()</literal> and <literal>math.randomseed()</literal> are replaced with versions that don't share state with PHP's <literal>rand()</literal>.
98+
</para>
99+
</listitem>
100+
<listitem>
101+
<para>
102+
The Lua 5.2 <literal>__pairs</literal> and <literal>__ipairs</literal> metamethods are supported by <literal>pairs()</literal> and <literal>ipairs()</literal>.
103+
</para>
104+
</listitem>
105+
</itemizedlist>
106+
</para>
107+
</simplesect>
108+
109+
</chapter>
110+
111+
<!-- Keep this comment at the end of the file
112+
Local variables:
113+
mode: sgml
114+
sgml-omittag:t
115+
sgml-shorttag:t
116+
sgml-minimize-attributes:nil
117+
sgml-always-quote-attributes:t
118+
sgml-indent-step:1
119+
sgml-indent-data:t
120+
indent-tabs-mode:nil
121+
sgml-parent-document:nil
122+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
123+
sgml-exposed-tags:nil
124+
sgml-local-catalogs:nil
125+
sgml-local-ecat-files:nil
126+
End:
127+
vim600: syn=xml fen fdm=syntax fdl=2 si
128+
vim: et tw=78 syn=sgml
129+
vi: ts=1 sw=1
130+
-->

‎reference/luasandbox/entities.luasandbox.xml

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
&reference.luasandbox.luasandbox.callfunction;
2+
&reference.luasandbox.luasandbox.disableprofiler;
3+
&reference.luasandbox.luasandbox.enableprofiler;
4+
&reference.luasandbox.luasandbox.getcpuusage;
5+
&reference.luasandbox.luasandbox.getmemoryusage;
6+
&reference.luasandbox.luasandbox.getpeakmemoryusage;
7+
&reference.luasandbox.luasandbox.getprofilerfunctionreport;
8+
&reference.luasandbox.luasandbox.getversioninfo;
9+
&reference.luasandbox.luasandbox.loadbinary;
10+
&reference.luasandbox.luasandbox.loadstring;
11+
&reference.luasandbox.luasandbox.pauseusagetimer;
12+
&reference.luasandbox.luasandbox.registerlibrary;
13+
&reference.luasandbox.luasandbox.setcpulimit;
14+
&reference.luasandbox.luasandbox.setmemorylimit;
15+
&reference.luasandbox.luasandbox.unpauseusagetimer;
16+
&reference.luasandbox.luasandbox.wrapphpfunction;

‎reference/luasandbox/entities.luasandboxfunction.xml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
&reference.luasandbox.luasandboxfunction.call;
2+
&reference.luasandbox.luasandboxfunction.construct;
3+
&reference.luasandbox.luasandboxfunction.dump;

0 commit comments

Comments
 (0)