You are on: Home | Suhosin | Configuration
Table of Contents

Configuration

Suhosin‘s features are all configured through the php.ini configuration file. Here you can find descriptions of all supported options.

For most users the Suhosin will work out of the box without any change to the default configuration needed.

When you only use the Suhosin-Patch only the logging features are supported. When you only use the Suhosin-Extension you cannot use the predefined constants for configuration. This is due to the way php.ini constant support is implemented in PHP.

Logging Configuration

suhosin.log.syslog

  • Type: Integer
  • Default: S_ALL & ~S_SQL

Defines what classes of security alerts are logged to the syslog daemon. Logging of errors of the class S_MEMORY are always logged to syslog, no matter what this configuration says, because a corrupted heap could mean that the other logging options will malfunction during the logging process.

Keep in mind that using the constants is only supported when the Suhosin-Patch is used

Constant Value Description
S_MEMORY 1 All canary violations and the safe unlink protection use this class
S_MISC 2 All log messages (f.e. format string protection) that do not fit in other classes use this class
S_VARS 4 All variable filters trigger this class
S_FILES 8 All violations triggered by the uploaded files filter use this class
S_INCLUDE 16 The protection against malicious include filenames use this class
S_SQL 32 Failed SQL queris are logged with this class (not yet supported in Suhosin BETA)
S_EXECUTOR 64 The execution depth protection uses this logging class
S_MAIL 128 The mail() header newline protection uses this logging class
S_SESSION 256 The transparent session protection uses this logging class
S_ALL 511 Combines all classes

suhosin.log.syslog.facility

  • Type: Integer
  • Default: LOG_USER

Defines the syslog facility that is used when ALERTs are logged to syslog. Depending on your system type (syslogd) the following facilities are available. Please check your system ‘s include header if the values are the same for your syslogd.

Constant Value
LOG_KERN 8
LOG_USER 9
LOG_MAIL 10
LOG_DAEMON 11
LOG_AUTH 12
LOG_SYSLOG 13
LOG_LPR 14
LOG_NEWS 15
LOG_UUCP 16
LOG_CRON 17
LOG_AUTHPRIV 18
LOG_LOCAL0 24
LOG_LOCAL1 25
LOG_LOCAL2 26
LOG_LOCAL3 27
LOG_LOCAL4 28
LOG_LOCAL5 29
LOG_LOCAL6 30
LOG_LOCAL7 31

suhosin.log.syslog.priority

  • Type: Integer
  • Default: LOG_ALERT

Defines the syslog priority that is used when ALERTs are logged to syslog. Depending on your system type (syslogd) the following priorities are available. Please check your system ‘s include header if the values are the same for your syslogd.

Constant Value
LOG_EMERG 0
LOG_ALERT 1
LOG_CRIT 2
LOG_WARNING 3
LOG_NOTICE 4
LOG_INFO 5
LOG_DEBUG 6
LOG_ERR 7

suhosin.log.sapi

  • Type: Integer
  • Default: S_ALL & ~S_SQL

Defines what classes of security alerts are logged through the SAPI error log. For a list of available classes see table 1.

suhosin.log.script

  • Type: Integer
  • Default: 0

Defines what classes of security alerts are logged through the external logging script. For a list of available classes see table 1. An exception is the S_MEMORY class. It cannot be logged by a script, because S_MEMORY is triggered by bufferoverflows etc... which means the process is in an unstable state.

suhosin.log.phpscript

  • Type: Integer
  • Default: 0

Defines what classes of security alerts are logged through the defined PHP script. For a list of available classes see table 1. Please notice, that only those classes are allowed, that can be triggered during script execution. An exception is the S_MEMORY class. It cannot be logged by a PHP script, because S_MEMORY is triggered by bufferoverflows etc... which means the process is in an unstable state.

suhosin.log.script.name

  • Type: String
  • Default:

Defines the full path to an external logging script. The script is called with 2 parameters. The first one is the alert class in string notation and the second parameter is the log message. This can be used for example to mail failing MySQL queries to your email address, because on a production system these things should never happen (S_SQL not yet supported by Suhosin).

suhosin.log.phpscript.name

  • Type: String
  • Default:

Defines the full path to a PHP logging script. The script is called with 2 variables registered in the current scope: SUHOSIN_ERRORCLASS and SUHOSIN_ERROR. The first one is the alert class and the second variable is the log message. This can be used for example to mail attempted remote URL include attacks to your email address.

suhosin.log.use-x-forwarded-for

  • Type: Boolean
  • Default: off

When the Suhosin logs an error the log message also contains the IP of the attacker. Usually this IP is retrieved from the REMOTE_ADDR SAPI environment variable. With this switch it is possible to change this behavior to read the IP from the X-Forwarded-For HTTP header. This is for example necessary when your PHP server runs behind a reverse proxy.

Executor Options

suhosin.executor.max_depth

  • Type: Integer
  • Default: 0

Defines the maximum stack depth allowed by the executor before it stops the script. Without this function an endless recursion in a PHP script could crash the PHP executor or trigger the configured memory_limit. A value of ’0’ disables this feature.

suhosin.executor.include.max_traversal

  • Type: Integer
  • Default: 0

Defines how many ‘../’ an include filename needs to contain to be considered an attack and stopped. A value of ‘2’ will block ‘../../etc/passwd’, while a value of ‘3’ will allow it. Most PHP applications should work flawlessly with values ‘4’ or ‘5’. A value of ’0’ disables this feature.

suhosin.executor.include.whitelist

  • Type: String
  • Default:

Comma separated whitelist of URL schemes that are allowed to be included from include or require statements. Additionally to URL schemes it is possible to specify the beginning of allowed URLs. (f.e.: php://stdin) If no whitelist is specified, then the blacklist is evaluated.

suhosin.executor.include.blacklist

  • Type: String
  • Default:

Comma separated blacklist of URL schemes that are not allowed to be included from include or require statements. Additionally to URL schemes it is possible to specify the beginning of allowed URLs. (f.e.: php://stdin) If no blacklist and no whitelist is specified all URL schemes are forbidden.

suhosin.executor.func.whitelist

  • Type: String
  • Default:

Comma separated whitelist of functions that are allowed to be called. If the whitelist is empty the blacklist is evaluated, otherwise calling a function not in the whitelist will terminate the script and get logged.

suhosin.executor.func.blacklist

  • Type: String
  • Default:

Comma separated blacklist of functions that are not allowed to be called. If no whitelist is given, calling a function within the blacklist will terminate the script and get logged.

suhosin.executor.eval.whitelist

  • Type: String
  • Default:

Comma separated whitelist of functions that are allowed to be called from within eval(). If the whitelist is empty the blacklist is evaluated, otherwise calling a function not in the whitelist will terminate the script and get logged. Please read the instructions carefully.

suhosin.executor.eval.blacklist

  • Type: String
  • Default:

Comma separated blacklist of functions that are not allowed to be called from within eval(). If no whitelist is given, calling a function within the blacklist will terminate the script and get logged. Please read the instructions carefully.

suhosin.executor.disable_eval

  • Type: Boolean
  • Default: Off

eval() is a very dangerous statement and therefore you might want to disable it completely. Deactivating it will however break lots of scripts. Because every violation is logged, this allows finding all places where eval() is used.

suhosin.executor.disable_emodifier

  • Type: Boolean
  • Default: Off

The /e modifier inside preg_replace() allows code execution. Often it is the cause for remote code execution exploits. It is wise to deactivate this feature and test where in the application it is used. The developer using the /e modifier should be made aware that he should use preg_replace_callback() instead.

suhosin.executor.allow_symlink

  • Type: Boolean
  • Default: Off

This flag reactivates symlink() when open_basedir is used, which is disabled by default in Suhosin >= 0.9.6. Allowing symlink() while open_basedir is used is actually a security risk.

Misc Options

suhosin.simulation

  • Type: Boolean
  • Default: Off

If you fear that Suhosin breaks your application, you can activate Suhosin’s simulation mode with this flag. When Suhosin runs in simulation mode, violations are logged as usual, but nothing is blocked or removed from the request. (Transparent Encryptions are NOT deactivated in simulation mode.)

suhosin.apc_bug_workaround

  • Type: Boolean
  • Default: Off

APC 3.0.12(p1/p2) uses reserved resources without requesting a resource slot first. It always uses resource slot 0. If Suhosin got this slot assigned APC will overwrite the information Suhosin stores in this slot. When this flag is set Suhosin will request 2 Slots and use the second one. This allows working correctly with these buggy APC versions.

suhosin.sql.bailout_on_error

  • Type: Boolean
  • Default: Off

When a SQL Query fails scripts often spit out a bunch of useful information for possible attackers. When this configuration directive is turned on, the script will silently terminate, after the problem has been logged. (This is not yet supported)

suhosin.sql.user_prefix

  • Type: String
  • Default:

This is an experimental feature for shared environments. With this configuration option it is possible to specify a prefix that is automatically prepended to the database username, whenever a database connection is made. (Unless the username starts with the prefix)

With this feature it is possible for shared hosters to disallow customers to connect with the usernames of other customers. This feature is experimental, because support for PDO and PostgreSQL are not yet implemented.

suhosin.sql.user_postfix

  • Type: String
  • Default:

This is an experimental feature for shared environments. With this configuration option it is possible to specify a postfix that is automatically appended to the database username, whenever a database connection is made. (Unless the username end with the postfix)

With this feature it is possible for shared hosters to disallow customers to connect with the usernames of other customers. This feature is experimental, because support for PDO and PostgreSQL are not yet implemented.

suhosin.multiheader

  • Type: Boolean
  • Default: Off

This directive controls if multiple headers are allowed or not in a header() call. By default the Suhosin forbids this. (HTTP headers spanning multiple lines are still allowed).

suhosin.mail.protect

  • Type: Integer
  • Default: 0

This directive controls if the mail() header protection is activated or not and to what degree it is activated. The appended table lists the possible activation levels.

Value Description
0 mail() header protection is disabled
1 Disallows newlines in Subject:, To: headers and double newlines in additional headers
2 Additionally disallows To:, CC:, BCC: in additional headers

Logging of this class of alerts is controlled by the new S_MAIL constant.

suhosin.memory_limit

  • Type: Integer
  • Default: 0

As long scripts are not running within safe_mode they are free to change the memory_limit to whatever value they want. Suhosin changes this fact and disallows setting the memory_limit to a value greater than the one the script started with, when this option is left at 0. A value greater than 0 means that Suhosin will disallows scripts setting the memory_limit to a value above this configured hard limit. This is for example usefull if you want to run the script normaly with a limit of 16M but image processing scripts may raise it to 20M.

Transparent Encryption Options

suhosin.session.encrypt

  • Type: Boolean
  • Default: On

Flag that decides if the transparent session encryption is activated or not.

suhosin.session.cryptkey

  • Type: String
  • Default:

Session data can be encrypted transparently. The encryption key used consists of this user defined string (which can be altered by a script via ini_set()) and optionally the User-Agent, the Document-Root and 0-4 Octects of the REMOTE_ADDR.

suhosin.session.cryptua

  • Type: Boolean
  • Default: On

Flag that decides if the transparent session encryption key depends on the User-Agent field. (When activated this feature transparently adds a little bit protection against session fixation/hijacking attacks)

suhosin.session.cryptdocroot

  • Type: Boolean
  • Default: On

Flag that decides if the transparent session encryption key depends on the Documentroot field.

suhosin.session.cryptraddr

  • Type: Integer
  • Default: 0

Number of octets (0-4) from the REMOTE_ADDR that the transparent session encryption key depends on. Keep in mind that this should not be used on sites that have visitors from big ISPs, because their IP address often changes during a session. But this feature might be interesting for admin interfaces or intranets. When used wisely this is a transparent protection against session hijacking/fixation.

suhosin.session.checkraddr

  • Type: Integer
  • Default: 0

Number of octets (0-4) from the REMOTE_ADDR that have to match to decrypt the session. The difference to suhosin.session.cryptaddr is, that the IP is not part of the encryption key, so that the same session can be used for different areas with different protection levels on the site.

suhosin.cookie.encrypt

  • Type: Boolean
  • Default: On

Flag that decides if the transparent cookie encryption is activated or not.

suhosin.cookie.cryptkey

  • Type: String
  • Default:

Cookies can be encrypted transparently. The encryption key used consists of this user defined string and optionally the User-Agent, the Document-Root and 0-4 Octects of the REMOTE_ADDR.

suhosin.cookie.cryptua

  • Type: Boolean
  • Default: On

Flag that decides if the transparent session encryption key depends on the User-Agent field. (When activated this feature transparently adds a little bit protection against session fixation/hijacking attacks (if only session cookies are allowed))

suhosin.cookie.cryptdocroot

  • Type: Boolean
  • Default: On

Flag that decides if the transparent cookie encryption key depends on the Documentroot field.

suhosin.cookie.cryptraddr

  • Type: Integer
  • Default: 0

Number of octets (0-4) from the REMOTE_ADDR that the transparent cookie encryption key depends on. Keep in mind that this should not be used on sites that have visitors from big ISPs, because their IP address often changes during a session. But this feature might be interesting for admin interfaces or intranets. When used wisely this is a transparent protection against session hijacking/fixation.

suhosin.cookie.checkraddr

  • Type: Integer
  • Default: 0

Number of octets (0-4) from the REMOTE_ADDR that have to match to decrypt the cookie. The difference to suhosin.cookie.cryptaddr is, that the IP is not part of the encryption key, so that the same cookie can be used for different areas with different protection levels on the site.

suhosin.cookie.cryptlist

  • Type: String
  • Default:

In case not all cookies are supposed to get encrypted this is a comma separated list of cookie names that should get encrypted. All other cookies will not get touched.

suhosin.cookie.plainlist

  • Type: String
  • Default:

In case some cookies should not be crypted this is a comma separated list of cookies that do not get encrypted. All other cookies will be encrypted.

Filtering Options

suhosin.filter.action

  • Type: Mixed
  • Default:

Defines the reaction of Suhosin on a filter violation. Following possible actions are supported

Type Description
Normal action is simply blocking the variable from beeing registered
402 Do not execute the script an return a HTTP 402 response code
[302,]http://www.disney.com Redirect to http://www.disney.com instead of executing. Optionally set a specific HTTP response code
[402,]/var/scripts/badguy.php Execute a specific PHP script instead of the requested script. Optionally set a specific HTTP response code

suhosin.cookie.max_array_depth

  • Type: Integer
  • Default: 100

Defines the maximum depth an array variable may have, when registered through the COOKIE.

Note: Array depth is not the number of elements within an array.

suhosin.cookie.max_array_index_length

  • Type: Integer
  • Default: 64

Defines the maximum length of array indices for variables registered through the COOKIE.

suhosin.cookie.max_name_length

  • Type: Integer
  • Default: 64

Defines the maximum length of variable names for variables registered through the COOKIE. For array variables this is the name in front of the indices.

suhosin.cookie.max_totalname_length

  • Type: Integer
  • Default: 256

Defines the maximum length of the total variable name when registered through the COOKIE. For array variables this includes all indices.

suhosin.cookie.max_value_length

  • Type: Integer
  • Default: 10000

Defines the maximum length of a variable that is registered through the COOKIE.

suhosin.cookie.max_vars

  • Type: Integer
  • Default: 100

Defines the maximum number of variables that may be registered through the COOKIE.

suhosin.cookie.disallow_nul

  • Type: Boolean
  • Default: On

When set to On ASCIIZ chars are not allowed in variables.

suhosin.get.max_array_depth

  • Type: Integer
  • Default: 50

Defines the maximum depth an array variable may have, when registered through the URL.

Note: Array depth is not the number of elements within an array.

suhosin.get.max_array_index_length

  • Type: Integer
  • Default: 64

Defines the maximum length of array indices for variables registered through the URL.

suhosin.get.max_name_length

  • Type: Integer
  • Default: 64

Defines the maximum length of variable names for variables registered through the URL. For array variables this is the name in front of the indices.

suhosin.get.max_totalname_length

  • Type: Integer
  • Default: 256

Defines the maximum length of the total variable name when registered through the URL. For array variables this includes all indices.

suhosin.get.max_value_length

  • Type: Integer
  • Default: 512

Defines the maximum length of a variable that is registered through the URL.

suhosin.get.max_vars

  • Type: Integer
  • Default: 100

Defines the maximum number of variables that may be registered through the URL.

suhosin.get.disallow_nul

  • Type: Boolean
  • Default: On

When set to On ASCIIZ chars are not allowed in variables.

suhosin.post.max_array_depth

  • Type: Integer
  • Default: 100

Defines the maximum depth an array variable may have, when registered through a POST request.

Note: Array depth is not the number of elements within an array.

suhosin.post.max_array_index_length

  • Type: Integer
  • Default: 64

Defines the maximum length of array indices for variables registered through a POST request.

suhosin.post.max_name_length

  • Type: Integer
  • Default: 64

Defines the maximum length of variable names for variables registered through a POST request. For array variables this is the name in front of the indices.

suhosin.post.max_totalname_length

  • Type: Integer
  • Default: 256

Defines the maximum length of the total variable name when registered through a POST request. For array variables this includes all indices.

suhosin.post.max_value_length

  • Type: Integer
  • Default: 65000

Defines the maximum length of a variable that is registered through a POST request.

suhosin.post.max_vars

  • Type: Integer
  • Default: 200

Defines the maximum number of variables that may be registered through a POST request.

suhosin.post.disallow_nul

  • Type: Boolean
  • Default: On

When set to On ASCIIZ chars are not allowed in variables.

suhosin.request.max_array_depth

  • Type: Integer
  • Default: 100

Defines the maximum depth an array variable may have, when registered through GET , POST or COOKIE. This setting is also an upper limit for the separate GET, POST, COOKIE configuration directives.

Note: Array depth is not the number of elements within an array.

suhosin.request.max_array_index_length

  • Type: Integer
  • Default: 64

Defines the maximum length of array indices for variables registered through GET, POST or COOKIE. This setting is also an upper limit for the separate GET, POST, COOKIE configuration directives.

suhosin.request.max_totalname_length

  • Type: Integer
  • Default: 256

Defines the maximum length of variable names for variables registered through the COOKIE, the URL or through a POST request. This is the complete name string, including all indicies. This setting is also an upper limit for the separate GET, POST, COOKIE configuration directives.

suhosin.request.max_value_length

  • Type: Integer
  • Default: 65000

Defines the maximum length of a variable that is registered through the COOKIE, the URL or through a POST request. This setting is also an upper limit for the variable origin specific configuration directives.

suhosin.request.max_vars

  • Type: Integer
  • Default: 200

Defines the maximum number of variables that may be registered through the COOKIE, the URL or through a POST request. This setting is also an upper limit for the variable origin specific configuration directives.

suhosin.request.max_varname_length

  • Type: Integer
  • Default: 64

Defines the maximum name length (excluding possible array indicies) of variables that may be registered through the COOKIE, the URL or through a POST request. This setting is also an upper limit for the variable origin specific configuration directives.

suhosin.request.disallow_nul

  • Type: Boolean
  • Default: On

When set to On ASCIIZ chars are not allowed in variables.

suhosin.upload.max_uploads

  • Type: Integer
  • Default: 25

Defines the maximum number of files that may be uploaded with one request.

suhosin.upload.disallow_elf

  • Type: Boolean
  • Default: On

When set to On it is not possible to upload ELF executables.

suhosin.upload.disallow_binary

  • Type: Boolean
  • Default: Off

When set to On it is not possible to upload binary files.

suhosin.upload.remove_binary

  • Type: Boolean
  • Default: Off

When set to On binary content is removed from the uploaded files.

suhosin.upload.verification_script

  • Type: String
  • Default:

This defines the full path to a verification script for uploaded files. The script gets the temporary filename supplied and has to decide if the upload is allowed. A possible application for this is to scan uploaded files for viruses. The called script has to write a 1 as first line to standard output to allow the upload. Any other value or no output at all will result in the file being deleted.

suhosin.session.max_id_length

  • Type: Integer
  • Default: 128

Specifies the maximum length of the session identifier that is allowed. When a longer session identifier is passed a new session identifier will be created. This feature is important to fight bufferoverflows in 3rd party session handlers.


© Hardened PHP Project