toolman.org/net/peercred

peercred

import "toolman.org/net/peercred"

• Install
• Overview
• Index
• Subdirectories

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

• Constants
• type Conn
• type Listener
  • func Listen(ctx context.Context, addr string) (*Listener, error)
  • func (pcl *Listener) Accept() (net.Conn, error)
  • func (pcl *Listener) AcceptPeerCred() (*Conn, error)

Package files

listener.go

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.