Examples

Notes

Note:

Avoid using this function in multithreaded webservers. It is better to
change the file permissions with chmod() after
creating the file. Using umask() can lead to
unexpected behavior of concurrently running scripts and the webserver
itself because they all use the same umask.

User Contributed Notes 11 notes

I think that the best way to understand umask is to say that umask is used to revoke permissions, not to set permissions.

umask sets which permissions must be removed from the system default when you create a file or a directory.

For example, a mask 0022 means that you don't want group and others modify the file.

default 0666 rw-.rw-.rw- umask 0022 ---.-w-.-w-Final 0644 rw-.r--.r--

That means that any file from now on will have 0644 permissions.

It is important to understand that umask revokes, deletes permissions from system default, so it can´t grant permissions the system default hasn't. In the example above, with the 666 system default, there is no way you can use umask to create a file with execute permission. If you want to grant more permissions, use chmod.

Be aware that system default permissions are not related to PHP (they depends upon server configuration). PHP has a default umask that is applied after system default base permissions. And there are different system default base permissions for files and directories.

Usually, system default permissions for files are 666 and for directories 0777. And usually, default PHP umask is 0022

In case you don't understand why you need to "Avoid using this function in multithreaded webservers":

It's because this function changes the umask at the process level, rather than only for PHP or for the current script. If there are multiple simultaneous threads running in the process in which your PHP script is running, the change will apply to all of those threads at the same time hence why this is not safe for multithreaded use.

I understand that if you are using the PHP module and Apache's prefork MPM, which is not multi-threaded, then you at least won't get race-condition problems such as this. However, it is still worth noting that the umask setting, if not re-set, will persist for the life of that process even if the process is re-used to serve future PHP or non-PHP requests.

"It is better to change the file permissions with chmod() after creating the file."

The usual lacking of security knowledge within the PHP team rears its head once again. You *always* want to have the file created with the proper permission. Let me illustrate why:

(a) you create new file with read permissions(b) an attacking script opens the file(c) you chmod the file to remove read permissions(d) you write sensitive data to the file

Now, you might think that the changes of an attacking script getting to open the file before you chmod them are low. And you're right. But low changes are never low enough - you want zero chance.

When creating a file that needs increased permissions, you always need to create the file with the proper permissions, and also create it with O_EXCL set. If you don't do an exclusive create, you end up with this scenario:

(a) attacker creates the file, makes it writable to everyone(b) you open the file with restricted permissions, but since it already exists, the file is merely opened and the permissions left alone(c) you write sensitive data into the insecure file

Detecting the latter scenario is possible, but it requires a bit of work. You have to check that the file's owner and group match the script's (that is, posix_geteuid(), not myuid()) and check the permissions - if any of those are incorrect, then the file is insecure - you can attempt to unlink() it and try again while logging a warning, of course.

The only time when it is reasonable or safe to chmod() a file after creating it is when you want to grant extra permissions instead of removing them. For example, it is completely safe to set the umask to 0077 and then chmoding the files you create afterward.

Doing truly secure programming in PHP is difficult as is, and advice like this in the documentation just makes things worse. Remember, kids, anything that applies to security in the C or UNIX worlds is 100% applicable to PHP. The best thing you can possibly do for yourself as a PHP programmer is to learn and understand secure C and UNIX programming techniques.

"It is better to change the file permissions with chmod() after creating the file."

If you take that advice seriously, consider setting your umask so that files are created private to your user, then use chmod to open them up.

<?php// files will create as -rw-------umask(0077);

// create a file, eg fopen()

// give access: -rw-r--r--chmod('/path/to/file', 0644);?>

Whenever reasonable, default to shut and open as needed (like above) instead of default to open and shut as needed. The above still has a race condition, but the race condition will deny appropriate access instead of granting inappropriate access.

On most UNIX environments the recommended default umask for files, defined in /home/user/.profile or /etc/profile, is 022 (chmod: 644). On trusted systems it is 002. Exercise caution when applying more liberal settings.

calculate the result:<?php$umask = 0670;umask($umask);//- if you are creating a new directory, $permission = 0777;//- if you are creating a new file, $permission = 0666.printf( "result: %04o", $permission & ( 0777 - $umask) );?>

BTW, as the manual said, the form of umask() is "int umask ( [int mask] )", so if you want to print/echo any umask, don't forget to convert it from DEC (because it returns a "int") to OCT.

<?php$umask = umask(); //- returns the current umask, which is a "int"$umask = decoct($umask); //- Now, $umask is a "string"echo $umask;?>

Don't forget that the argument(parameter) is a "int", too.

<?phpumask(777); //- WRONG! Even though you maybe use "umask 777" in some OS.umask(0777); //- OK?>