Welcome to unix-cred’s documentation!

Cross-platform interfaces

For most use cases, these interfaces (in particular get_peer_uid_gid()) should be enough.

get_peer_uid_gid(sock)

Returns the (uid, gid) of the peer connected to the given stream socket.

get_peer_pid_uid_gid(sock)

Returns the (pid, uid, gid) of the peer connected to the given stream socket.

On some platforms, this function is not available. On other platforms, the returned PID may be None if the current version of that platform does not support retrieving the PID (for example, FreeBSD prior to version 13 does not, and will always return None).

Availability: Linux, OpenBSD, NetBSD, FreeBSD (PID only available on version 13+), macOS, Solaris, Illumos

Platform-specific interfaces

In most cases, you should use the cross-platform interfaces. However, the platform-specific interfaces may be useful (for example, they may provide additional information).

get_peerpid(sock)

Returns the PID of the process that last accessed the given stream socket.

Availability: macOS

ucred

The ucred module provides an interface to the ucred interface on Linux, the sockpeecred interface on OpenBSD, or the unpcbid interface on NetBSD.

The reason that the interfaces for all three of these are in one module is that they are all essentially the same interface, with only minor implementation differences (such as the order of the fields in the C struct, or the name of the socket option used to retrieve them).

Note

This module is only here for completeness. In nearly all cases, you should use get_peer_pid_uid_gid() (which has slightly better cross-platform support) instead.

class ucred.Ucred

Availability: Linux, OpenBSD, NetBSD

pid
Type

int

The PID of the connected peer.

uid
Type

int

The effective UID of the connected peer.

gid
Type

int

The effective GID of the connected peer.

ucred.get_ucred(sock)

Returns a Ucred object representing the credentials of the peer connected to the given socket.

Availability: Linux, OpenBSD, NetBSD

xucred

The xucred module provides an interface to the xucred interface on FreeBSD, DragonflyBSD, and macOS.

class xucred.Xucred

Availability: FreeBSD, DragonFlyBSD, macOS

pid
Type

int or None

The PID of the connected peer.

This attribute is only set on FreeBSD 13+. On macOS/DragonFlyBSD, and on previous versions of FreeBSD, it is always None. Always make sure to check for a None value.

To get the PID on macOS, use get_peerpid().

Availability: FreeBSD 13+

uid
Type

int

The effective UID of the connected peer.

gid
Type

int

The effective GID of the connected peer.

groups
Type

list[int]

The supplementary groups of the connected peer.

Note

On macOS, the value placed in this attribute differs from that of os.getgroups(). Effectively, it always behaves as if the deployment target is less than 10.5.

Note

On FreeBSD, this group list is truncated to the first 16 supplementary groups. (Technically, it’s also truncated on DragonflyBSD and macOS, but they only support 16 groups normally.)

xucred.get_xucred(sock)

Returns a Xucred object representing the credentials of the peer connected to the given socket.

Availability: FreeBSD, DragonFlyBSD, macOS

peerucred

The peerucred module provides an interface to the getpeerucred() function on Solaris/Illumos.

Warning

This module is experimental and has undergone no testing whatsoever. Use with caution.

class peerucred.Ucred

Availability: Solaris, Illumos

pid
Type

int

The PID of the connected peer.

ruid
Type

int

The real UID of the connected peer.

euid
Type

int

The effective UID of the connected peer.

suid
Type

int

The saved UID of the connected peer.

rgid
Type

int

The real GID of the connected peer.

egid
Type

int

The effective GID of the connected peer.

sgid
Type

int

The saved GID of the connected peer.

groups
Type

list[int]

The supplementary groups of the connected peer.

peerucred.getpeerucred(sock)

Returns a Ucred object representing the credentials of the peer connected to the given socket.

Availability: Solaris, Illumos

Indices and tables