--- name: "KEYCTL_SETPERM" section: "2const" platform: "linux" package: "man-pages" version: "6.19-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/KEYCTL_SETPERM" --- # KEYCTL\_SETPERM(2const) change the permissions mask on a key ## NAME KEYCTL\_SETPERM - change the permissions mask on a key ## LIBRARY Standard C library (*libc*, *-lc*) ## SYNOPSIS ``` #include /* Definition of KEY* constants */ #include /* Definition of SYS_* constants */ #include ``` **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)](/keyrings/7.md). - *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)](/KEYCTL_DESCRIBE/2const.md) 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)](/KEYCTL_READ/2const.md) 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_UPDATE/2const.md), [**KEYCTL\_REVOKE**(2const)](/KEYCTL_REVOKE/2const.md), [**KEYCTL\_CLEAR**(2const)](/KEYCTL_CLEAR/2const.md), [**KEYCTL\_LINK**(2const)](/KEYCTL_LINK/2const.md), and [**KEYCTL\_UNLINK**(2const)](/KEYCTL_UNLINK/2const.md) 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_GET_KEYRING_ID/2const.md), [**KEYCTL\_JOIN\_SESSION\_KEYRING**(2const)](/KEYCTL_JOIN_SESSION_KEYRING/2const.md), [**KEYCTL\_SEARCH**(2const)](/KEYCTL_SEARCH/2const.md), 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)](/KEYCTL_LINK/2const.md) and [**KEYCTL\_SESSION\_TO\_PARENT**(2const)](/KEYCTL_SESSION_TO_PARENT/2const.md) 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_REVOKE/2const.md), [**KEYCTL\_CHOWN**(2const)](/KEYCTL_CHOWN/2const.md), 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)](/keyctl_setperm/3.md). ## STANDARDS Linux. ## HISTORY Linux 2.6.10. ## SEE ALSO [**keyctl**(2)](/keyctl/2.md), [**keyctl\_setperm**(3)](/keyctl_setperm/3.md)