man/keyctl_grant_permission.3

.\"
.\" Copyright (C) 2019 Red Hat, Inc. All Rights Reserved.
.\" Written by David Howells (dhowells@redhat.com)
.\"
.\" This program is free software; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License
.\" as published by the Free Software Foundation; either version
.\" 2 of the License, or (at your option) any later version.
.\"
.TH KEYCTL_GRANT_PERMISSION 3 "15 Aug 2019" Linux "Linux Key Management Calls"
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH NAME
keyctl_grant_permission \- Alter the ACL on a key
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH SYNOPSIS
.nf
.B #include <keyutils.h>
.sp
.BI "long keyctl_grant_permission(key_serial_t " key ,
.BI "                             enum key_ace_subject_type " type
.BI "                             unsigned int " subject ,
.BI "                             unsigned int " perm ");"
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH DESCRIPTION
.BR keyctl_grant_permission ()
alters the ACL attached to a key to grant or remove permissions to a specific
subject.  This supersedes
.BR keyctl_setperm ().
The Linux kernel maintains the ACL, allowing this call to add, modify or delete
a single ACE to, in or from the ACL.
.P
A process that does not have the
.B SysAdmin
capability may not change the permissions mask on a key that doesn't have the
same UID as the caller.
.P
The caller must have
.B SET_SECURITY
permission on a key to be able change the ACL.
.P
The subject is specified by a combination of the
.IR type " and " subject
parameters.  The type is one of:
.TP
.B KEY_ACE_SUBJ_STANDARD
This indicates that the subject specifies one of a number 'macroised'
subjects:
.RS
.TP
.B KEY_ACE_EVERYONE
Unconditially grant permits to every process on the system.
.TP
.B KEY_ACE_OWNER
Grant permits to any process whose
.I fsuid
matches the owner of the key.
.TP
.B KEY_ACE_GROUP
Grant permits to any process for whom the key's group matches the process's
.I fsgid
or one of its
.I groups
list.
.TP
.B KEY_ACE_POSSESSOR
Grant permits to any process that has the key somewhere in it's keyrings.
.RE
.P
The permissions mask
.I perm
is a bitwise-OR of the following permits, where any permit not given will be
removed from the ACE for the specified subject.
.TP
.B KEY_ACE_VIEW
Grant permission to view the attributes of a key.
.TP
.B KEY_ACE_READ
Grant permission to read the payload of a key or to list a keyring.
.TP
.B KEY_ACE_WRITE
Grant permission to modify the payload of a key or to add or remove links
to/from a keyring.
.TP
.B KEY_ACE_SEARCH
Grant permission to find a key or to search a keyring.
.TP
.B KEY_ACE_LINK
Grant permission to make links to a key.
.TP
.B KEY_ACE_SET_SECURITY
Grant permission to change the ownership and ACL of a key.
.TP
.B KEY_ACE_INVAL
Grant permission to invalidate a key.
.TP
.B KEY_ACE_REVOKE
Grant permission to revoke a key.
.TP
.B KEY_ACE_JOIN
Grant permission to join a keyring.
.TP
.B KEY_ACE_CLEAR
Grant permission to clear a keyring.
.TP
.B KEY_ACE__PERMS
Grant all the above.
.P
All grants are cumulative.  There are currently no ACEs that explicitly deny
access to a permit.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH RETURN VALUE
On success
.BR keyctl_grant_permission ()
returns
.B 0 .
On error, the value
.B -1
will be returned and
.I errno
will have been set to an appropriate error.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH ERRORS
.TP
.B ENOKEY
The specified key does not exist.
.TP
.B EKEYEXPIRED
The specified key has expired.
.TP
.B EKEYREVOKED
The specified key has been revoked.
.TP
.B EACCES
The named key exists, but does not grant
.B setattr
permission to the calling process.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH LINKING
This is a library function that can be found in
.IR libkeyutils .
When linking,
.B \-lkeyutils
should be specified to the linker.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH SEE ALSO
.ad l
.nh
.BR keyctl (1),
.BR add_key (2),
.BR keyctl (2),
.BR request_key (2),
.BR keyctl (3),
.BR keyctl_setperm (3),
.BR keyrings (7),
.BR keyutils (7)