Documentation:Windows Section 2.1

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

I/O Restrictions

I/O Restrictions are a feature introduced in POV-Ray 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 obsfucated 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 Windows version to allow or deny any particular file operation. Please note that this only affects file I/O from the core POV-Ray code; that is, the code that implements the parser and renderer. It does not affect which files the Windows interface can read and write. That is to say, it does not prevent you loading a file into an editor, or saving a file from the editor, or any other feature implemented on the Windows interface that is not part of the core POV-Ray feature set. (The 'core feature set' is those features of POV-Ray that are available on all operating systems and computer platforms for which a version of POV is available).

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. I/O Restrictions are 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 (such as the fact that some directories are allowed by default).

High-Level Configuration

Now to the details: how to configure the I/O Restrictions (or get them out of your hair if you want them turned off). Under the Options menu there is a sub-menu called Script I/O Restrictions.

Script I/O Restrictions sub-menu

This provides you with high-level control of the restriction subsystem. The top section of the menu provides you with three options (detailed below). You can only choose one of the three. The bottom section provides you with two additional options, either of which can be on or off.

No Restrictions

If this option is chosen, POV scripts can read/write everything (subject to operating system permission). The I/O Restriction system is turned off.

Restrict Write but Allow Read

If this option is chosen. POV scripts can read anything, but file creation and file write is only allowed in the implicit and user-specified directories (see Low-Level Configuration for more information on how to specify which directories).

Another way to put it is that I/O Restrictions are turned off for reading files, but not for writing them.

Restrict Read/Write

Both read and write by POV scripts is restricted to implicit and user-specified directories. Note that this is the default setting for a clean installation of POV-Ray for Windows.

Restrictions Affect all Core File I/O

Note that the above settings do not just affect scripted file I/O; they also affect things like include files, output files, and input .POV files. Basically any file-related input or output by the rendering engine. You should take careful note of this statement if you are in the habit of writing your output files to anywhere other than the same directory as the scene file is in (see below).

Additional Options

In addition to the above, there are two other options:

Permit Read/Write in Current Directory

If turned on, the current directory (but not any below it) is automatically added to the allowed list of read/write locations. Since POVWIN sets the current directory to that which contains the source file (.pov or .ini) at the start of a render, this automatically enables the location containing a scene for read/write. For most people, this is a useful feature, so it is on by default for a clean install.

Please note that having this option unchecked does not prevent read in the current directory if you have turned off read restrictions (as documented above), and nor will it prevent writing if you have turned off I/O Restrictions altogether. Also, turning it on will not allow read/write in subdirectories of the current directory - just that dir alone.

Disable Starting other Programs

If this option is selected (the default), shell-outs will not be permitted. 'Shell Outs' are a facility where an INI file can specify that a particular program be run either before or after a frame is rendered as well as at other points in the parse/render process. If you want these, you have to explicitly allow them by unchecking this option.

Low-Level Configuration

This section tells you how to manually specify explicit directories for read/write access, if the standard settings aren't suitable. First we need to cover what is and isn't protected by default.

Overall Concept

The overall concept of the I/O Restrictions, when enabled, is that everything should be denied unless it is explicitly allowed (with one or two exceptions). So unless you add a directory to the 'allowed' list, unless it is one of the implicitly allowed locations then the directory in question is not permitted to be accessed.

Implicitly Permitted Locations

The exceptions to the 'deny everything' rule (referred to above as 'implicit' locations) are as follows:

1. The document installation directory of POV-Ray for Windows (as given by the registry or otherwise determined at run-time) is permitted to be used for read (but not write). This includes all of its subdirectories (except as below). Note that you can alter this setting if you like.
2. Write is permitted to the 'Insert Menu' sub-directory within the POV-Ray documents install directory. This is to enable the 'Re-render Insert Menu Bitmaps' feature to function without needing to modify the restrictions.
3. Read is permitted from the Windows 'Fonts' directory. This is to allow TTF files to be read, as POV-Ray's portable rendering engine has its own TTF parser. (The Fonts directory is also added to the include path automatically).

Adding or Changing Allowed Directories

Note: The INI subdirectory contained within the document install directory is permanently write-protected (unless the I/O Restriction system is turned off). Even if you grant permission to write this dir from he below INI file, writes will not succeed. This is to prevent the INI file that contains the I/O Restriction configuration from being modified by a script to grant itself more access next time POVWIN is run.

To add or change allowed directories, you'll need to modify the file <installdir>\ini\pvengine.ini, where <installdir> is where the POV-Ray for Windows user-editable files where installed. An easy way to get at this file is to select it from the tools menu (by default, it is the second item).

Within PVENGINE.INI you may see two sections like the following ... (note that the actual contents of the installed version are slightly different from this example).

[Permitted Input Paths]
1=%INSTALLDIR%

[Permitted Output Paths]
1=%INSTALLDIR%

If they are not present, it means that POVWIN is using the defaults, in which case you may add them. For example, %INSTALLDIR% is implicitly allowed for input and does not need to be added to the INI file (though there is no harm in doing so).

%INSTALLDIR% resolves to the location that the POVWIN user-editable files were installed. It would be legal to say something like -

%INSTALLDIR%\scenes

for example, to refer to (say) C:\Users\Joe\Documents\POV-Ray\vX.y\scenes.

Relative paths are legal as well, and will be resolved only once at load time (but relative to the current directory, not the documents folder). For example, a relative path like the following ...

[Permitted Output Paths]
1=..\output

would be resolved with relation to the current directory at the time POV-Ray for Windows was started, so if you started pvengine.exe from the directory c:\myscenes\newscene, then the above path would be resolved as c:\myscenes\output. Please note that the actual location of the POV-Ray executable file is not relevent here - it is the current directory that matters (which is not necessarily that of the program installation). You only need to care about this if you want to use relative paths in the restrictions setup: 99% of users don't, so if it doesn't make sense, don't worry :-)

A directory placed in the permitted input paths section only allows read. One placed in the output paths section permits both read and write; write permission is inferred to mean read permission. This means you don't need to duplicate entries (the above example shows such a duplication - it is not harmful, just unnecessary). You can have up to 64 entries (numbered 0..63) in each section.

An entry in the permitted paths sections gives permission not only for that directory, but all the ones below it (note that this is different from the 'permit read/write in current directory' option mentioned earlier, which only applies to that one directory alone, and not those below it).

A reminder that, as mentioned above, if write protection is turned on at all, the <installdir>\INI directory is always write-protected, and nothing in the above permission sections should be able to allow it. This is to prevent a script from modifying pvengine.ini to remove or alter the I/O Restrictions for the next time that POVWIN runs.

For Those Who use an Image Output Directory

Some users have POV-Ray set up such that all images are written into the same output directory. To make this work with I/O Restrictions active, and assuming the output directory isn't in the POV-Ray for Windows document folder, you will need to add that directory to the permitted output list.

For example, if your image output directory is c:\images\, you could have something like this in the INI file -

[Permitted Input Paths]
1=%INSTALLDIR%

[Permitted Output Paths]
1=%INSTALLDIR%
2=c:\images

If you want to grant access to an entire drive (e.g. d:\), just add it like this -

[Permitted Input Paths]
1=%INSTALLDIR%

[Permitted Output Paths]
1=%INSTALLDIR%
2=c:\images
3=d:\

The Font Setting

Command-Line Options

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