README
¶
peercred 
import "toolman.org/net/peercred"
Install
go get toolman.org/net/peercred
Overview
Package peercred provides a net.Listener implementation leveraging the Linux SO_PEERCRED socket option to acquire the PID, UID, and GID of the foreign process connected to each socket. According to the socket(7) manual,
This is possible only for connected AF_UNIX stream
sockets and AF_UNIX stream and datagram socket pairs
created using socketpair(2).
Therefore, peercred.Listener only supports Unix domain sockets and IP connections are not available.
peercred.Listener is intended for use cases where a Unix domain server needs to reliably identify the process on the client side of each connection. By itself, peercred provides support for simple "unix" socket connections. Additional support for gRPC over Unix domain sockets is available with the subordinate package toolman.org/net/peercred/grpcpeer.
A simple, unix-domain server can be written similar to the following:
// Create a new Listener listening on socketName
lsnr, err := peercred.Listen(ctx, socketName)
if err != nil {
return err
}
// Wait for and accept an incoming connection
conn, err := lsnr.AcceptPeerCred()
if err != nil {
return err
}
// conn.Ucred has fields Pid, Uid and Gid
fmt.Printf("Client PID=%d UID=%d\n", conn.Ucred.Pid, conn.Ucred.Uid)
Index
Package files
Constants
const ErrAddrInUse = unix.EADDRINUSE
ErrAddrInUse is a convenience wrapper around the Posix errno value for EADDRINUSE.
type Conn
type Conn struct {
Ucred *unix.Ucred
net.Conn
}
Conn is a net.Conn containing the process credentials for the client side of a Unix domain socket connection.
type Listener
type Listener struct {
net.Listener
}
Listener is an implementation of net.Listener that extracts the identity (i.e. pid, uid, gid) from the connection's client process. This information is then made available through the Ucred member of the *Conn returned by AcceptPeerCred or Accept (after a type assertion).
func Listen
func Listen(ctx context.Context, addr string) (*Listener, error)
Listen returns a new Listener listening on the Unix domain socket addr.
func (*Listener) Accept
func (pcl *Listener) Accept() (net.Conn, error)
Accept is a convenience wrapper around AcceptPeerCred allowing Listener callers that utilize net.Listener to function as expected. The returned net.Conn is a *Conn which may be accessed through a type assertion. See AcceptPeerCred for details on possible error conditions.
Accept contributes to implementing the net.Listener interface.
func (*Listener) AcceptPeerCred
func (pcl *Listener) AcceptPeerCred() (*Conn, error)
AcceptPeerCred accepts a connection from the receiver's listener returning a *Conn containing the process credentials for the client. If the underlying Accept fails or if process credentials cannot be extracted, AcceptPeerCred returns nil and an error.
Documentation
¶
Overview ¶
Package peercred provides Listener - a net.Listener implementation leveraging the Linux SO_PEERCRED socket option to acquire the PID, UID, and GID of the foreign process connected to each socket. According to the socket(7) manual,
This is possible only for connected AF_UNIX stream sockets and AF_UNIX stream and datagram socket pairs created using socketpair(2).
Therefore, peercred.Listener only supports Unix domain sockets and IP connections are not available.
peercred.Listener is intended for use cases where a Unix domain server needs to reliably identify the process on the client side of each connection. By itself, peercred provides support for simple "unix" socket connections. Additional support for gRPC over Unix domain sockets is available with the subordinate package toolman.org/net/peercred/grpcpeer.
A simple, unix-domain server can be written similar to the following:
// Create a new Listener listening on socketName
lsnr, err := peercred.Listen(ctx, socketName)
if err != nil {
return err
}
// Wait for and accept an incoming connection
conn, err := lsnr.AcceptPeerCred()
if err != nil {
return err
}
// conn.Ucred has fields Pid, Uid and Gid
fmt.Printf("Client PID=%d UID=%d\n", conn.Ucred.Pid, conn.Ucred.Uid)
NOTE: Currently, this package only works on Linux. MacOS and FreeBSD are on the todo list. Windows isn't (nor are other OSs).
Index ¶
Constants ¶
const ErrAddrInUse = unix.EADDRINUSE
ErrAddrInUse is a convenience wrapper around the Posix errno value for EADDRINUSE.
Variables ¶
This section is empty.
Functions ¶
func SDListenNames ¶ added in v0.6.0
SDListenNames returns a map of SocketName -> *Listener for each systemd activated socket provided to the current process.
The SocketName map key is defined by the FileDescriptorName directive in the associated socket's systemd unit -- or, if unspecified, the value defaults to the name of the socket unit, including its '.socket' suffix.
Types ¶
type Conn ¶
Conn is a net.Conn containing the process credentials for the client side of a Unix domain socket connection.
type Listener ¶
Listener is an implementation of net.Listener that extracts peer credentials (i.e. PID, UID, GID) of the foreign process connected to each socket. Since the underlying features making this possible are only available for "unix" sockets, no "network" argument is required here ("unix" is implied). The acquired peer credentials are made available through the "Ucred" member of the *Conn returned by AcceptPeerCred.
See 'SO_PEERCRED' in socket(7) for further details.
func SDListen ¶ added in v0.5.0
SDListen returns a new *Listener for the systemd activated socket provided to the current process. If systemd provides more than one socket, SDListen will close them all and return an error. Use SDListenNames if you need to acquire multiple Listeners.
func (*Listener) Accept ¶
Accept is a convenience wrapper around AcceptPeerCred allowing callers utilizing the net.Listener interface to function as expected. The returned net.Conn is a *peercred.Conn that may be accessed with a type assertion. See AcceptPeerCred for details on possible error conditions.
Accept contributes to implementing the net.Listener interface.
func (*Listener) AcceptContext ¶ added in v0.5.0
AcceptContext behaves the same as AcceptPeerCred except it immediately returns nil and ctx.Err() if the Context is canceled. Note that the underlying Accept call is unblocked by closing the listening socket so, if this method is interrupted by a canceled Context, this *Listener will accept no new connections.
func (*Listener) AcceptPeerCred ¶
AcceptPeerCred accepts a connection on the listening socket returning a *Conn containing the process credentials for the client. If the underlying Accept fails or if no peer process credentials can be extracted, AcceptPeerCred returns nil and an error.
Source Files
Directories