diff --git a/Makefile-man.am b/Makefile-man.am index 35874e0b84..950207bd4e 100644 --- a/Makefile-man.am +++ b/Makefile-man.am @@ -227,6 +227,7 @@ MANPAGES_ALIAS += \ man/reboot.8 \ man/sd_bus_creds_get_audit_login_uid.3 \ man/sd_bus_creds_get_audit_session_id.3 \ + man/sd_bus_creds_get_augmented_mask.3 \ man/sd_bus_creds_get_cgroup.3 \ man/sd_bus_creds_get_cmdline.3 \ man/sd_bus_creds_get_comm.3 \ @@ -252,6 +253,7 @@ MANPAGES_ALIAS += \ man/sd_bus_creds_get_uid.3 \ man/sd_bus_creds_get_unique_name.3 \ man/sd_bus_creds_get_unit.3 \ + man/sd_bus_creds_get_user_slice.3 \ man/sd_bus_creds_get_user_unit.3 \ man/sd_bus_creds_get_well_known_names.3 \ man/sd_bus_creds_has_bounding_cap.3 \ @@ -511,6 +513,7 @@ man/poweroff.8: man/halt.8 man/reboot.8: man/halt.8 man/sd_bus_creds_get_audit_login_uid.3: man/sd_bus_creds_get_pid.3 man/sd_bus_creds_get_audit_session_id.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_augmented_mask.3: man/sd_bus_creds_new_from_pid.3 man/sd_bus_creds_get_cgroup.3: man/sd_bus_creds_get_pid.3 man/sd_bus_creds_get_cmdline.3: man/sd_bus_creds_get_pid.3 man/sd_bus_creds_get_comm.3: man/sd_bus_creds_get_pid.3 @@ -536,6 +539,7 @@ man/sd_bus_creds_get_tty.3: man/sd_bus_creds_get_pid.3 man/sd_bus_creds_get_uid.3: man/sd_bus_creds_get_pid.3 man/sd_bus_creds_get_unique_name.3: man/sd_bus_creds_get_pid.3 man/sd_bus_creds_get_unit.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_user_slice.3: man/sd_bus_creds_get_pid.3 man/sd_bus_creds_get_user_unit.3: man/sd_bus_creds_get_pid.3 man/sd_bus_creds_get_well_known_names.3: man/sd_bus_creds_get_pid.3 man/sd_bus_creds_has_bounding_cap.3: man/sd_bus_creds_get_pid.3 @@ -925,6 +929,9 @@ man/sd_bus_creds_get_audit_login_uid.html: man/sd_bus_creds_get_pid.html man/sd_bus_creds_get_audit_session_id.html: man/sd_bus_creds_get_pid.html $(html-alias) +man/sd_bus_creds_get_augmented_mask.html: man/sd_bus_creds_new_from_pid.html + $(html-alias) + man/sd_bus_creds_get_cgroup.html: man/sd_bus_creds_get_pid.html $(html-alias) @@ -1000,6 +1007,9 @@ man/sd_bus_creds_get_unique_name.html: man/sd_bus_creds_get_pid.html man/sd_bus_creds_get_unit.html: man/sd_bus_creds_get_pid.html $(html-alias) +man/sd_bus_creds_get_user_slice.html: man/sd_bus_creds_get_pid.html + $(html-alias) + man/sd_bus_creds_get_user_unit.html: man/sd_bus_creds_get_pid.html $(html-alias) diff --git a/man/sd_bus_creds_get_pid.xml b/man/sd_bus_creds_get_pid.xml index 13f885cd5d..4162fab065 100644 --- a/man/sd_bus_creds_get_pid.xml +++ b/man/sd_bus_creds_get_pid.xml @@ -61,8 +61,9 @@ sd_bus_creds_get_cmdline sd_bus_creds_get_cgroup sd_bus_creds_get_unit - sd_bus_creds_get_user_unit sd_bus_creds_get_slice + sd_bus_creds_get_user_unit + sd_bus_creds_get_user_slice sd_bus_creds_get_session sd_bus_creds_get_owner_uid sd_bus_creds_has_effective_cap @@ -192,6 +193,12 @@ const char **unit + + int sd_bus_creds_get_slice + sd_bus_creds *c + const char **slice + + int sd_bus_creds_get_user_unit sd_bus_creds *c @@ -199,7 +206,7 @@ - int sd_bus_creds_get_slice + int sd_bus_creds_get_user_slice sd_bus_creds *c const char **slice @@ -288,9 +295,9 @@ Description - These functions return information from an - sd_bus_creds credential object. Credential - objects may be created with + These functions return credential information from an + sd_bus_creds object. Credential objects may + be created with sd_bus_creds_new_from_pid3, in which case they describe the credentials of the process identified by the specified PID, with @@ -301,7 +308,13 @@ in which case they describe the credentials of the creator of a bus, or with sd_bus_message_get_creds3, - in which case they describe the credentials of the sender of the message. + in which case they describe the credentials of the sender of the + message. + + Not all credential fields are part of every + sd_bus_creds object. Use + sd_bus_creds_get_mask3 + to determine the mask of fields available. sd_bus_creds_get_pid() will retrieve the PID (process identifier). Similar, @@ -374,19 +387,22 @@ sd_bus_creds_get_slice() will retrieve the systemd slice (a unit in the system instance of systemd) that the process is part of. See - systemd.slice5. + systemd.slice5. Similar, + sd_bus_creds_get_user_slice() retrieves the + systemd slice of the process, in the user instance of systemd. sd_bus_creds_get_session() will - retrieve the logind session that the process is part of. See + retrieve the identifier of the login session that the process is + part of. See systemd-logind.service8. For processes that are not part of a session returns -ENXIO. sd_bus_creds_get_owner_uid() will retrieve the numeric UID (user identifier) of the user who owns - the session that the process is part of. See - systemd.slice5 + the login session that the process is part of. See + systemd-logind.service8. For processes that are not part of a session returns -ENXIO. @@ -395,7 +411,7 @@ capability was set in the effective capabilities mask. A positive return value means that is was set, zero means that it was not set, and a negative return - value signifies an error. See + value indicates an error. See capabilities7 and Capabilities= and CapabilityBoundingSet= settings in @@ -427,8 +443,8 @@ processes that are not part of an audit session. sd_bus_creds_get_tty() will retrieve - the controlling TTY. Returns -ENXIO for processes that have no - controlling TTY. + the controlling TTY, without the prefixing "/dev/". Returns -ENXIO + for processes that have no controlling TTY. sd_bus_creds_get_unique_name() will retrieve the D-Bus unique name. See Given field is not specified for the described process or peer. This will be returned by sd_bus_get_unit(), - sd_bus_get_user_unit(), sd_bus_get_slice(), + sd_bus_get_user_unit(), + sd_bus_get_user_slice(), sd_bus_get_session(), and sd_bus_get_owner_uid() if the process is not part of a systemd system unit, systemd user unit, systemd @@ -526,10 +543,11 @@ Notes - sd_bus_open_user() and other functions - described here are available as a shared library, which can be - compiled and linked to with the - libsystemd pkg-config1 + sd_bus_creds_get_pid() and the other + functions described here are available as a shared library, which + can be compiled and linked to with the + libsystemd pkg-config1 file. @@ -539,8 +557,9 @@ systemd1, sd-bus3, - fork2, - execve2, + sd_bus_creds_new_from_pid2, + fork2, + execve2, credentials7, free3, proc5, diff --git a/man/sd_bus_creds_new_from_pid.xml b/man/sd_bus_creds_new_from_pid.xml index 8c054a5905..a78d3f5717 100644 --- a/man/sd_bus_creds_new_from_pid.xml +++ b/man/sd_bus_creds_new_from_pid.xml @@ -45,6 +45,7 @@ sd_bus_creds_new_from_pid sd_bus_creds_get_mask + sd_bus_creds_get_augmented_mask sd_bus_creds_ref sd_bus_creds_unref @@ -67,6 +68,11 @@ const sd_bus_creds *c + + uint64_t sd_bus_creds_get_augmented_mask + const sd_bus_creds *c + + sd_bus_creds *sd_bus_creds_ref sd_bus_creds *c @@ -80,17 +86,26 @@ SD_BUS_CREDS_PID, + SD_BUS_CREDS_PPID, SD_BUS_CREDS_TID, SD_BUS_CREDS_UID, + SD_BUS_CREDS_EUID, + SD_BUS_CREDS_SUID, + SD_BUS_CREDS_FSUID, SD_BUS_CREDS_GID, + SD_BUS_CREDS_EGID, + SD_BUS_CREDS_SGID, + SD_BUS_CREDS_FSGID, + SD_BUS_CREDS_SUPPLEMENTARY_GIDS, SD_BUS_CREDS_COMM, SD_BUS_CREDS_TID_COMM, SD_BUS_CREDS_EXE, SD_BUS_CREDS_CMDLINE, SD_BUS_CREDS_CGROUP, SD_BUS_CREDS_UNIT, - SD_BUS_CREDS_USER_UNIT, SD_BUS_CREDS_SLICE, + SD_BUS_CREDS_USER_UNIT, + SD_BUS_CREDS_USER_SLICE, SD_BUS_CREDS_SESSION, SD_BUS_CREDS_OWNER_UID, SD_BUS_CREDS_EFFECTIVE_CAPS, @@ -100,8 +115,11 @@ SD_BUS_CREDS_SELINUX_CONTEXT, SD_BUS_CREDS_AUDIT_SESSION_ID, SD_BUS_CREDS_AUDIT_LOGIN_UID, + SD_BUS_CREDS_TTY, SD_BUS_CREDS_UNIQUE_NAME, SD_BUS_CREDS_WELL_KNOWN_NAMES, + SD_BUS_CREDS_DESCRIPTION, + SD_BUS_CREDS_AUGMENT, _SD_BUS_CREDS_ALL @@ -109,25 +127,39 @@ Description - sd_bus_creds_new_from_pid() creates a new - credentials object and fills it with information about the process - pid. This pointer to this object will - be stored in ret pointer. + sd_bus_creds_new_from_pid() creates a + new credentials object and fills it with information about the + process pid. The pointer to this object + will be stored in ret pointer. Note that + credential objects may also be created and retrieved via + sd_bus_get_name_creds3, + sd_bus_get_owner_creds3 + and + sd_bus_message_get_creds3. The information that will be stored is determined by creds_mask. It may contain a subset of ORed constants SD_BUS_CREDS_PID, + SD_BUS_CREDS_PPID, SD_BUS_CREDS_TID, SD_BUS_CREDS_UID, + SD_BUS_CREDS_EUID, + SD_BUS_CREDS_SUID, + SD_BUS_CREDS_FSUID, SD_BUS_CREDS_GID, + SD_BUS_CREDS_EGID, + SD_BUS_CREDS_SGID, + SD_BUS_CREDS_FSGID, + SD_BUS_CREDS_SUPPLEMENTARY_GIDS, SD_BUS_CREDS_COMM, SD_BUS_CREDS_TID_COMM, SD_BUS_CREDS_EXE, SD_BUS_CREDS_CMDLINE, SD_BUS_CREDS_CGROUP, SD_BUS_CREDS_UNIT, - SD_BUS_CREDS_USER_UNIT, SD_BUS_CREDS_SLICE, + SD_BUS_CREDS_USER_UNIT, + SD_BUS_CREDS_USER_SLICE, SD_BUS_CREDS_SESSION, SD_BUS_CREDS_OWNER_UID, SD_BUS_CREDS_EFFECTIVE_CAPS, @@ -137,34 +169,71 @@ SD_BUS_CREDS_SELINUX_CONTEXT, SD_BUS_CREDS_AUDIT_SESSION_ID, SD_BUS_CREDS_AUDIT_LOGIN_UID, + SD_BUS_CREDS_TTY, SD_BUS_CREDS_UNIQUE_NAME, SD_BUS_CREDS_WELL_KNOWN_NAMES, - or _SD_BUS_CREDS_ALL to indicate - all known fields. + SD_BUS_CREDS_DESCRIPTION. Use the special + value _SD_BUS_CREDS_ALL to request all + supported fields. The SD_BUS_CREDS_AUGMENT + may not be ORed into the mask for invocations of + sd_bus_creds_new_from_pid(). Fields can be retrieved from the credentials object using sd_bus_creds_get_pid3 and other functions which correspond directly to the constants listed above. - A mask of fields which were actually successfully set - (acquired from /proc, etc.) can be retrieved - with sd_bus_creds_get_mask(). If the - credentials object was created with + A mask of fields which were actually successfully retrieved + can be retrieved with + sd_bus_creds_get_mask(). If the credentials + object was created with sd_bus_creds_new_from_pid(), this will be a subset of fields requested in creds_mask. - sd_bus_creds_ref creates a new + Similar to sd_bus_creds_get_mask() the + function sd_bus_creds_get_augmented_mask() + returns a bitmask of field constants. The mask indicates which + credential fields have been retrieved in a non-atomic fashion. For + credential objects created via + sd_bus_creds_new_from_pid() this mask will be + identical to the mask returned by + sd_bus_creds_get_mask(). However, for + credential objects retrieved via + sd_bus_get_name_creds() this mask will be set + for the credential fields that could not be determined atomically + at peer connection time, and which were later added by reading + augmenting credential data from + /proc. Similar, for credential objects + retrieved via sd_bus_get_owner_creds() the + mask is set for the fields that could not be determined atomically + at bus creation time, but have been augmented. Similar, for + credential objects retrieved via + sd_bus_message_get_creds() the mask is set + for the fields that could not be determined atomically at message + send time, but have been augmented. The mask returned by + sd_bus_creds_get_augmented_mask() is always a + subset of (or identical to) the mask returned by + sd_bus_creds_get_mask() for the same + object. The latter call hence returns all credential fields + available in the credential object, the former then marks the + subset of those that have been augmented. Note that augmented + fields are unsuitable for authorization decisions as they may be + retrieved at different times, thus being subject to races. Hence + augmented fields should be used exclusively for informational + purposes. + + + sd_bus_creds_ref() creates a new reference to the credentials object c. This object will not be destroyed until - sd_bus_creds_unref has been called as many + sd_bus_creds_unref() has been called as many times plus once more. Once the reference count has dropped to zero, c cannot be used anymore, so further calls to sd_bus_creds_ref(c) or sd_bus_creds_unref(c) are illegal. - sd_bus_creds_unref destroys a reference + sd_bus_creds_unref() destroys a reference to c. @@ -178,10 +247,15 @@ sd_bus_creds_get_mask() returns the mask of successfully acquired fields. - sd_bus_creds_ref always returns the + sd_bus_creds_get_augmented_mask() + returns the mask of fields that have been augmented from data in + /proc, and are thus not suitable for + authorization decisions. + + sd_bus_creds_ref() always returns the argument. - sd_bus_creds_unref always returns + sd_bus_creds_unref() always returns NULL. @@ -222,16 +296,23 @@ Memory allocation failed. + + + -EOPNOTSUPP + + One of the requested fields is unknown to the local system. + Notes - sd_bus_creds_new_from_pid() is - available as a shared library, which can be compiled and linked to - with the - libsystemd pkg-config1 + sd_bus_creds_new_from_pid() and the + other calls described here are available as a shared library, + which can be compiled and linked to with the + libsystemd pkg-config1 file. @@ -241,31 +322,10 @@ systemd1, sd-bus3, - sd_bus_creds_ref3, - sd_bus_creds_unref3, sd_bus_creds_get_pid3, - sd_bus_creds_get_tid3, - sd_bus_creds_get_uid3, - sd_bus_creds_get_gid3, - sd_bus_creds_get_comm3, - sd_bus_creds_get_tid_comm3, - sd_bus_creds_get_exe3, - sd_bus_creds_get_cmdline3, - sd_bus_creds_get_cgroup3, - sd_bus_creds_get_unit3, - sd_bus_creds_get_user_unit3, - sd_bus_creds_get_slice3, - sd_bus_creds_get_session3, - sd_bus_creds_get_owner_uid3, - sd_bus_creds_has_effective_cap3, - sd_bus_creds_has_permitted_cap3, - sd_bus_creds_has_inheritable_cap3, - sd_bus_creds_has_bounding_cap3, - sd_bus_creds_get_selinux_context3, - sd_bus_creds_get_audit_session_id3, - sd_bus_creds_get_audit_login_uid3, - sd_bus_creds_get_unique_name3, - sd_bus_creds_get_well_known_names3 + sd_bus_get_name_creds3, + sd_bus_get_owner_creds3, + sd_bus_message_get_creds3