Difference between revisions of "Documentation:Unix Section 4"

From POV-Wiki
Jump to navigation Jump to search
 
m (canonicalize a version number)
 
(12 intermediate revisions by 2 users not shown)
Line 7: Line 7:
 
<br>
 
<br>
 
<!--</wikitalk>--->
 
<!--</wikitalk>--->
===I/O Restrictions===
+
==I/O Restrictions==
<!--<indexentry "I/O Restrictions">--->
+
{{#indexentry:unix, I/O Restrictions}}
  
<p>
+
<p>I/O Restrictions is a feature that was introduced in POV-Ray for Unix v3.5. The purpose of this feature is to attempt to at least partially protect a machine running POV-Ray from having files read or written outside of a given set of directories.</p>
I/O Restrictions are feature introduced in POV-Ray for Unix 3.5. The purpose of this feature
+
 
is to attempt to at least partially protect a machine running POV-Ray from having files
+
<p>The need for this is related to the fact that the POV-Ray scene language has, over the years, become something more akin to a scripting language combined with a scene-description model. It is now possible to write obfuscated POV-Ray code, and to open, create, read and write arbitrary files anywhere on the target system's hard disk, subject to operating system permission.</p>
read or written outside of a given set of directories.
+
 
</p>
+
<p>The basic idea of I/O Restrictions is to attempt to protect the user from a script that may have been downloaded from an untrusted source, and which may attempt to create or modify files that it should not.</p>
<p>
+
 
The need for this is related to the fact that the POV-Ray scene language has, over the years,
+
<p>The I/O Restriction facility hooks the file open and creation functions in the core POV-Ray renderer code, and allows the Unix version to allow or deny any particular file operation.</p>
become something more akin to a scripting language combined with a scene-description model.
+
 
It is now possible to write obfuscated POV-Ray code, and to open, create, read and write
+
<p class="Note"><strong>Note:</strong> We do not guarantee that the I/O Restriction facility will actually stop anything from happening. There is always the chance that, like almost all software, it could have a bug in it that causes it to malfunction. Therefore, the onus is on the person who chooses to load an INI or scene file into POV-Ray to ensure that it does not do anything that it should not do. Please consider I/O Restrictions just a sometimes-helpful backup for manual checks.</p>
arbitrary files anywhere on the target system's hard disk (subject to operating system
+
 
permission).
+
<p>Please read this section in full so that you understand the caveats and conditions of the facility, as some directories are allowed by default.</p>
</p>
 
<p>
 
The basic idea of I/O Restrictions is to attempt to protect the user from a script that may
 
have been downloaded from an untrusted source, and which may attempt to create or modify files
 
that it should not.
 
</p>
 
<p>
 
The I/O Restriction facility hooks the file open and creation functions in the core POV-Ray
 
renderer code, and allows the Unix version to allow or deny any particular file operation.
 
</p>
 
<p class="Warning">
 
<strong>Note:</strong>  
 
We do not guarantee that the I/O Restriction facility will actually stop anything from
 
happening. There is always the chance that, like almost all software, it could have a bug in
 
it that causes it to malfunction. Therefore, the onus is on the person who chooses to load an
 
INI or scene file into POV-Ray to ensure that it does not do anything that it should not do.
 
Please consider I/O Restrictions just a sometimes-helpful backup for manual checks.
 
</p>
 
<p>
 
Please read this section in full so that you understand the caveats and conditions of the
 
facility (such as the fact that some directories are allowed by default).
 
</p>
 
  
 
===Configuration file format===
 
===Configuration file format===
<p>
 
Now to the details: how to configure the I/O Restrictions (or get them out of your hair if
 
you want them turned off).
 
</p>
 
  
<p>
+
<p>The I/O Restrictions are configured by two separate configuration files. This can be a system-wide configuration, or a user configuration file located in the following places, on most systems <code>$PREFIX</code> is <code>/usr/local</code>.</p>
The I/O Restrictions are configured by a separate configuration file. This can be a  
+
<ul>
system-wide configuration file (<code>PREFIX/etc/povray/3.6/povray.conf</code>,
+
  <li><code>$PREFIX/etc/povray/vX.y/povray.conf</code></li>
<code>PREFIX</code> by default is <code>/usr/local</code>) or a user configuration file
+
  <li><code>$HOME/.povray/vX.y/povray.conf</code></li>
(<code>$HOME/.povray/3.6/povray.conf</code>).  POV-Ray will always use the most strict
+
</ul>
version of what is specified; user settings can only make security more strict.
 
</p>
 
  
<p class="Note"><strong>Note:</strong>
+
<p>POV-Ray will always use the most strict version of what is specified; user settings can only make security more strict.</p>
The format of this files has changed from version 3.5 to version 3.6.  Therefore POV-Ray
 
3.6 won't attempt to read the configuration from the old locations.
 
</p>
 
  
<p>
+
<p>The general syntax of these files is:</p>
If neither of these files exists I/O Restrictions are deactivated.
 
</p>
 
  
<p>
+
<pre>
The general syntax of these files is:
+
;Comment
</p>
 
 
 
<pre>; Comment
 
  
 
[Section]
 
[Section]
 
setting
 
setting
 
</pre>
 
</pre>
 +
 +
<p class="Warning"><strong>Warning:</strong> If neither of these files exists I/O Restrictions are deactivated!</p>
  
 
===File I/O Security===
 
===File I/O Security===
<p>
+
<p>The <code>[File I/O Security]</code> section only contains a single setting which is either <code>none</code>, <code>read-only</code> or <code>restricted</code>.</p>
The <code>[File I/O Security]</code> section only contains a single setting
 
which is either <code>none</code>, <code>read-only</code> or
 
<code>restricted</code>.
 
</p>
 
  
<p>
+
<ul>
<code>none</code> means that there are no restrictions other than those
+
  <li><code>none</code> means that there are no restrictions other than those enforced by the file system.</li>
enforced by the file system, i.e. normal Unix file and directory permissions.
+
  <li><code>read-only</code> means that files may be read without restriction.</li>
</p>
+
  <li><code>restricted</code> means that files access is subject to restrictions as specified in the rest of this file.  See below for details.</li>
 
+
</ul>
<p>
 
<code>read-only</code> means that files may be read without restriction.
 
</p>
 
 
 
<p>
 
<code>restricted</code> means that files access is subject to restrictions as
 
specified in the rest of this file.  See below for details.
 
</p>
 
  
 
===Shellout Security===
 
===Shellout Security===
<p>
+
<p>The <code>[Shellout Security]</code> section determines whether POV-Ray will be allowed to call scripts.</p>
<code>[Shellout Security]</code> determines whether POV-Ray will be allowed to
 
call scripts (e.g. Post_Frame_Command etc., see
 
<!--<linkto "Setting POV-Ray Options">POV-Ray Options</linkto>--->[[Documentation:Reference Section 1.2#Shell-out to Operating System|POV-Ray Options]]).
 
</p>
 
  
<p>
+
<p>This section contains a single setting which is either <code>allowed</code> or <code>forbidden</code>.</p>
This section contains a single setting which is either  
 
<code>allowed</code> or <code>forbidden</code>.
 
</p>
 
  
<p>
+
<ul>
<code>allowed</code> means that shellout will work as specified in the documentation.
+
  <li><code>allowed</code> means that shellout will work as specified in the documentation.</li>
</p>
+
  <li><code>forbidden</code> means that shellout will be disabled.
 +
</ul>
  
<p>
+
<p>See the section <!--<linkto "Setting POV-Ray Options">POV-Ray Options</linkto>--->[[Reference:Shell Command Options|Shell-out to Operating System]] for more details.</p>
<code>forbidden</code> means that shellout will be disabled.
 
</p>
 
  
 
===Permitted Paths===
 
===Permitted Paths===
<p>
+
<p>The <code>[Permitted Paths]</code> section contains a list of directories which are specifically allowed for either reading or reading and writing. These paths are only used when the setting for <code>[File I/O Security]</code> is either <code>read-only</code> or <code>restricted</code>.</p>
The <code>[Permitted Paths]</code> section contains a list of directories
 
which are specifically allowed for either reading or reading and writing.
 
These paths are only used when the setting for <code>[File I/O Security]</code>
 
is either <code>read-only</code> or <code>restricted</code>.
 
</p>
 
  
<p>
+
<ul>
Directories that are only allowed for reading are added with <code>read=directory</code>.
+
  <li>Directories that are only allowed for reading are added with <code>read=directory</code>.</li>
For allowing reading and writing use <code>read+write=directory</code>.
+
  <li>For allowing reading and writing use <code>read+write=directory</code>.</li>
</p>
+
<li>If <code>[File I/O Security]</code> is set to <code>read-only</code>, any directory can be used to read in a file, and <code>read+write</code> entries must specify which directories are allowed for writing.</li>
 +
<li>If <code>[File I/O Security]</code> is set to <code>restricted</code>, reading and writing is allowed <em>only</em> in the directories given by the <code>read</code> and <code>read+write</code> entries.</li>
 +
</ul>
  
<p>
+
<p>If the directory name contains spaces it has to be quoted or doubly-quoted. There can be spaces before and after the equal sign. Read-only and read/write entries can be specified in any order.</p>
If <code>[File I/O Security]</code> is set to <code>read-only</code>,
 
any directory can be used to read in a file, and <code>read+write</code>
 
entries must specify which directories are allowed for writing.
 
</p>
 
  
<p>
+
<p>If you want the permissions for a specified directory to also extend to all of its sub-directories wildcards are permitted.</p>
If <code>[File I/O Security]</code> is set to <code>restricted</code>,
 
reading and writing is allowed <em>only</em> in the directories
 
given by the <code>read</code> and <code>read+write</code> entries.
 
</p>
 
  
<p>
+
<p>For example:</p>
If the directory name contains spaces it has to be quoted or doubly-quoted. 
+
<pre>
There can be spaces before and after the equal sign. Read-only and read/write
+
read*=directory
entries can be specified in any order.
+
read+write*=directory
</p>
+
</pre>
 
 
<p>
 
If you want the permissions for a specified directory to also extend to all of its
 
subdirectories you have to add a <code>*</code> (like <code>read*=directory</code> or
 
<code>read+write*=directory</code>).
 
</p>
 
  
<p>
+
<p>Both relative and absolute paths are permitted, so <em>the dot</em> character can be especially useful. The install directory, typically <code>/usr/local/share/povray/vX.y</code> or <code>/usr/share/povray/vX.y</code> can be specified with <code>%INSTALLDIR%</code> and the user home directory with <code>%HOME%</code>. The install directory and its descendants are typically only writable by root; therefore it does not make sense to have <code>%INSTALLDIR%</code> in read/write directory paths.</p>
Both relative and absolute paths are permitted (making <code>.</code> especially  
 
useful). The install directory (typically <code>/usr/local/share/povray-3.6</code>  
 
or <code>/usr/share/povray-3.6</code>) can be specified with <code>%INSTALLDIR%</code>,
 
the user home directory with <code>%HOME%</code>. The install directory and its
 
descendents are typically only writable by root; therefore it does not
 
make sense to have <code>%INSTALLDIR%</code> in read/write directory paths.
 
</p>
 
  
<p class="Note">
+
<p class="Note"><strong>Note:</strong> Since user-level permissions are at least as strict as system-level restrictions, any paths specified in the system-wide <code>povray.conf</code> will also need to be specified in <code>~/.povray/vX.y/povray.conf</code> if this file exists.</p>
<strong>Note:</strong>  
 
Since user-level permissions are at least as strict as
 
system-level restrictions, any paths specified in the system-wide
 
<code>povray.conf</code> will also need to be specified in  
 
<code>~/.povray/3.6/povray.conf</code> if this file exists.
 
</p>
 
  
===Examples for path settings===
+
====Examples for path settings====
 
<pre>[Permitted Paths]
 
<pre>[Permitted Paths]
 
read=%INSTALLDIR%
 
read=%INSTALLDIR%
 
</pre>
 
</pre>
  
<p>
+
<p>Would permit reading from the directory where the POV-Ray supplementary files are installed.</p>
would permit reading from the directory where the POV-Ray supplementary files are installed.
 
</p>
 
  
<p>
+
<p>Note that the installdir location does not relate to where the binary is run from - it relates to the information defined at compile-time. Relative paths are legal as well, and will be resolved only once at load time (but relative to the current directory, not the installdir). For example, a relative path like the following ...</p>
Note that the installdir location does not relate to where the binary is run from - it relates
 
to the information defined at compile-time. Relative paths are legal as well, and will be resolved
 
only once at load time (but relative to the current directory, not the installdir). For example,
 
a relative path like the following ...
 
</p>
 
  
 
<pre>[Permitted Paths]
 
<pre>[Permitted Paths]
Line 192: Line 101:
 
</pre>
 
</pre>
  
<p>
+
<p>Would be resolved with relation to the <em>current directory at the time POV-Ray for Unix was started</em>, so if you started povray while in the directory <code>~/myscenes/newscene</code>, then the above path would be resolved as <code>~/myscenes/output</code>. Please note that the actual location of the povray binary is not relevent here - it is the current directory that matters, which is typically not that of the program.</p>
would be resolved with relation to the <em>current directory at the time POV-Ray for Unix was
 
started</em>, so if you started povray while in the directory <code>~/myscenes/newscene</code>,
 
then the above path would be resolved as <code>~/myscenes/output</code>. Please note that the
 
actual location of the povray binary is not relevent here - it is the current directory that
 
matters (which is typically not that of the program).
 
</p>
 
  
 
===Example configuration file===
 
===Example configuration file===
<p>
+
<p>Here is a complete example for a <code>povray.conf</code> file:</p>
Here is a complete example for a <code>povray.conf</code> file:
 
</p>
 
  
 
<pre>[File I/O Security]
 
<pre>[File I/O Security]

Latest revision as of 15:39, 9 June 2021

This document is protected, so submissions, corrections and discussions should be held on this documents talk page.


I/O Restrictions

I/O Restrictions is a feature that was introduced in POV-Ray for Unix v3.5. The purpose of this feature is to attempt to at least partially protect a machine running POV-Ray from having files read or written outside of a given set of directories.

The need for this is related to the fact that the POV-Ray scene language has, over the years, become something more akin to a scripting language combined with a scene-description model. It is now possible to write obfuscated POV-Ray code, and to open, create, read and write arbitrary files anywhere on the target system's hard disk, subject to operating system permission.

The basic idea of I/O Restrictions is to attempt to protect the user from a script that may have been downloaded from an untrusted source, and which may attempt to create or modify files that it should not.

The I/O Restriction facility hooks the file open and creation functions in the core POV-Ray renderer code, and allows the Unix version to allow or deny any particular file operation.

Note: We do not guarantee that the I/O Restriction facility will actually stop anything from happening. There is always the chance that, like almost all software, it could have a bug in it that causes it to malfunction. Therefore, the onus is on the person who chooses to load an INI or scene file into POV-Ray to ensure that it does not do anything that it should not do. Please consider I/O Restrictions just a sometimes-helpful backup for manual checks.

Please read this section in full so that you understand the caveats and conditions of the facility, as some directories are allowed by default.

Configuration file format

The I/O Restrictions are configured by two separate configuration files. This can be a system-wide configuration, or a user configuration file located in the following places, on most systems $PREFIX is /usr/local.

  • $PREFIX/etc/povray/vX.y/povray.conf
  • $HOME/.povray/vX.y/povray.conf

POV-Ray will always use the most strict version of what is specified; user settings can only make security more strict.

The general syntax of these files is:

;Comment

[Section]
setting

Warning: If neither of these files exists I/O Restrictions are deactivated!

File I/O Security

The [File I/O Security] section only contains a single setting which is either none, read-only or restricted.

  • none means that there are no restrictions other than those enforced by the file system.
  • read-only means that files may be read without restriction.
  • restricted means that files access is subject to restrictions as specified in the rest of this file. See below for details.

Shellout Security

The [Shellout Security] section determines whether POV-Ray will be allowed to call scripts.

This section contains a single setting which is either allowed or forbidden.

  • allowed means that shellout will work as specified in the documentation.
  • forbidden means that shellout will be disabled.

See the section Shell-out to Operating System for more details.

Permitted Paths

The [Permitted Paths] section contains a list of directories which are specifically allowed for either reading or reading and writing. These paths are only used when the setting for [File I/O Security] is either read-only or restricted.

  • Directories that are only allowed for reading are added with read=directory.
  • For allowing reading and writing use read+write=directory.
  • If [File I/O Security] is set to read-only, any directory can be used to read in a file, and read+write entries must specify which directories are allowed for writing.
  • If [File I/O Security] is set to restricted, reading and writing is allowed only in the directories given by the read and read+write entries.

If the directory name contains spaces it has to be quoted or doubly-quoted. There can be spaces before and after the equal sign. Read-only and read/write entries can be specified in any order.

If you want the permissions for a specified directory to also extend to all of its sub-directories wildcards are permitted.

For example:

read*=directory
read+write*=directory

Both relative and absolute paths are permitted, so the dot character can be especially useful. The install directory, typically /usr/local/share/povray/vX.y or /usr/share/povray/vX.y can be specified with %INSTALLDIR% and the user home directory with %HOME%. The install directory and its descendants are typically only writable by root; therefore it does not make sense to have %INSTALLDIR% in read/write directory paths.

Note: Since user-level permissions are at least as strict as system-level restrictions, any paths specified in the system-wide povray.conf will also need to be specified in ~/.povray/vX.y/povray.conf if this file exists.

Examples for path settings

[Permitted Paths]
read=%INSTALLDIR%

Would permit reading from the directory where the POV-Ray supplementary files are installed.

Note that the installdir location does not relate to where the binary is run from - it relates to the information defined at compile-time. Relative paths are legal as well, and will be resolved only once at load time (but relative to the current directory, not the installdir). For example, a relative path like the following ...

[Permitted Paths]
read+write=../output

Would be resolved with relation to the current directory at the time POV-Ray for Unix was started, so if you started povray while in the directory ~/myscenes/newscene, then the above path would be resolved as ~/myscenes/output. Please note that the actual location of the povray binary is not relevent here - it is the current directory that matters, which is typically not that of the program.

Example configuration file

Here is a complete example for a povray.conf file:

[File I/O Security]
; none
; read-only
restricted

[Shellout Security]
allowed
; forbidden

[Permitted Paths]
read*=%INSTALLDIR%/include
read*=%INSTALLDIR%/scenes
read=%INSTALLDIR%/../../etc
read+write=.
read+write*=/tmp


Post-processing Images Understanding File Types


This document is protected, so submissions, corrections and discussions should be held on this documents talk page.