# KEYCTL_SETPERM

## NAME



           KEYCTL_SETPERM - change the permissions mask on a key
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <linux/keyctl.h>  **/* Definition of **KEY*** constants */
           **#include <sys/syscall.h>   **/* Definition of **SYS_*** constants */
           **#include <unistd.h>**
    
           **long syscall(SYS_keyctl, KEYCTL_SETPERM, key_serial_t** _key_**,**
                        **key_perm_t** _perms_**);**
    


## DESCRIPTION



           Change the permissions of the key with the ID provided in the _key_
           argument to the permissions provided in the _perms_ argument.
    
           If the caller doesn't have the **CAP_SYS_ADMIN** capability, it can
           change permissions only for the keys it owns.  (More precisely:
           the caller's filesystem UID must match the UID of the key.)
    
           The key must grant _setattr_ permission to the caller _regardless_ of
           the caller's capabilities.
    
           The permissions in _perms_ specify masks of available operations for
           each of the following user categories:
    
           _possessor_ (since Linux 2.6.14)
                  This is the permission granted to a process that possesses
                  the key (has it attached searchably to one of the process's
                  keyrings); see keyrings(7).
    
           _user_   This is the permission granted to a process whose
                  filesystem UID matches the UID of the key.
    
           _group_  This is the permission granted to a process whose
                  filesystem GID or any of its supplementary GIDs matches the
                  GID of the key.
    
           _other_  This is the permission granted to other processes that do
                  not match the _user_ and _group_ categories.
    
           The _user_ , _group_ , and _other_ categories are exclusive: if a process
           matches the _user_ category, it will not receive permissions granted
           in the _group_ category; if a process matches the _user_ or _group_
           category, then it will not receive permissions granted in the
           _other_ category.
    
           The _possessor_ category grants permissions that are cumulative with
           the grants from the _user_ , _group_ , or _other_ category.
    
           Each permission mask is eight bits in size, with only six bits
           currently used.  The available permissions are:
    
           _view_   This permission allows reading attributes of a key.
    
                  This permission is required for the KEYCTL_DESCRIBE(2const)
                  operation.
    
           The permission bits for each category are:
    
                  **KEY_POS_VIEW**
                  **KEY_USR_VIEW**
                  **KEY_GRP_VIEW**
                  **KEY_OTH_VIEW**
    
           _read_   This permission allows reading a key's payload.
    
                  This permission is required for the KEYCTL_READ(2const)
                  operation.
    
                  The permission bits for each category are
    
                  **KEY_POS_READ**
                  **KEY_USR_READ**
                  **KEY_GRP_READ**
                  **KEY_OTH_READ**
    
           _write_  This permission allows update or instantiation of a key's
                  payload.  For a keyring, it allows keys to be linked and
                  unlinked from the keyring,
    
                  This permission is required for the KEYCTL_UPDATE(2const),
                  KEYCTL_REVOKE(2const), KEYCTL_CLEAR(2const),
                  KEYCTL_LINK(2const), and KEYCTL_UNLINK(2const) operations.
    
                  The permission bits for each category are:
    
                  **KEY_POS_WRITE**
                  **KEY_USR_WRITE**
                  **KEY_GRP_WRITE**
                  **KEY_OTH_WRITE**
    
           _search_ This permission allows keyrings to be searched and keys to
                  be found.  Searches can recurse only into nested keyrings
                  that have _search_ permission set.
    
                  This permission is required for the
                  KEYCTL_GET_KEYRING_ID(2const),
                  KEYCTL_JOIN_SESSION_KEYRING(2const), KEYCTL_SEARCH(2const),
                  and **KEYCTL_INVALIDATE (2const)** operations.
    
                  The permission bits for each category are:
    
                  **KEY_POS_SEARCH**
                  **KEY_USR_SEARCH**
                  **KEY_GRP_SEARCH**
                  **KEY_OTH_SEARCH**
    
           _link_   This permission allows a key or keyring to be linked to.
    
                  This permission is required for the KEYCTL_LINK(2const) and
                  KEYCTL_SESSION_TO_PARENT(2const) operations.
    
                  The permission bits for each category are:
    
                  **KEY_POS_LINK**
                  **KEY_USR_LINK**
                  **KEY_GRP_LINK**
                  **KEY_OTH_LINK**
    
           _setattr_ (since Linux 2.6.15)
                  This permission allows a key's UID, GID, and permissions
                  mask to be changed.
    
                  This permission is required for the KEYCTL_REVOKE(2const),
                  KEYCTL_CHOWN(2const), and **KEYCTL_SETPERM (2const)**
                  operations.
    
                  The permission bits for each category are:
    
                  **KEY_POS_SETATTR**
                  **KEY_USR_SETATTR**
                  **KEY_GRP_SETATTR**
                  **KEY_OTH_SETATTR**
    
           As a convenience, the following macros are defined as masks for
           all of the permission bits in each of the user categories:
    
                  **KEY_POS_ALL**
                  **KEY_USR_ALL**
                  **KEY_GRP_ALL**
                  **KEY_OTH_ALL**
    


## RETURN VALUE



           On success, 0 is returned.
    
           On error, -1 is returned, and _errno_ is set to indicate the error.
    


## ERRORS



           **EINVAL** _operation_ was **KEYCTL_SETPERM** and an invalid permission bit
                  was specified in _perms_.
    


## VERSIONS



           A wrapper is provided in the _libkeyutils_ library:
           keyctl_setperm(3).
    


## STANDARDS



           Linux.
    


* * *