NAME

Linux::WireGuard - WireGuard in Perl

SYNOPSIS

my @names = Linux::WireGuard::list_device_names();

my %device = map { $_ => Linux::WireGuard::get_device($_) } @names;

DESCRIPTION

Linux::WireGuard provides an interface to WireGuard via Linux’s embedded WireGuard C library.

NB: Although WireGuard itself is cross-platform, its embedded C library is Linux-specific.

CHARACTER ENCODING

All strings into & out of this module are byte strings.

ERROR HANDLING

Failures become Perl exceptions. Currently those exceptions are plain strings. Errors that come from WireGuard also manifest as changes to Perl’s $! global; for example, if you try to get_device() while non-root, you’ll probably see (besides the thrown exception) $! become Errno::EPERM.

FUNCTIONS

@names = list_device_names()

Returns a list of strings.

$dev_hr = get_device( $NAME )

Returns a reference to a hash that describes the $NAME’d device:

• name

• ifindex

• public_key and private_key (raw strings, or undef)

• fwmark (can be undef)

• listen_port (can be undef)

• peers - reference to an array of hash references. Each hash is:

  • public_key and preshared_key (raw strings, or undef)

  • endpoint - Raw sockaddr data (a string), or undef. To parse the sockaddr, use Socket’s sockaddr_family() to determine the address family, then unpack_sockaddr_in() for Socket::AF_INET or unpack_sockaddr_in6() for Socket::AF_INET6.

  • rx_bytes and tx_bytes

  • persistent_keepalive_interval (can be undef)

  • last_handshake_time_sec and last_handshake_time_nsec

  • allowed_ips - reference to an array of hash references. Each hash is:

    • family - Socket::AF_INET or Socket::AF_INET6

    • addr - A packed IPv4 or IPv6 address. Unpack with Socket’s inet_ntoa() or inet_ntop().

    • cidr

add_device( $NAME )

Adds a WireGuard device with the given $NAME.

del_device( $NAME )

Deletes a WireGuard device with the given $NAME.

$bin = generate_private_key()

Returns a newly-generated private key (raw string).

$bin = generate_public_key( $PRIVATE_KEY )

Takes a private key and returns its public key. (Both raw strings.)

$bin = generate_preshared_key()

Returns a newly-generated preshared key (raw string).

TODO

An implementation of set_device() would be nice to have.

LICENSE & COPYRIGHT

Copyright 2022 Gasper Software Consulting. All rights reserved.

Linux::WireGuard is licensed under the same terms as Perl itself (cf. perlartistic); HOWEVER, the embedded C wireguard library has its own copyright terms. Use of Linux::WireGuard may imply acceptance of that embedded C library’s own copyright terms. See this distribution’s wireguard-tools/contrib/embeddable-wg-library/README for details.

cpanm Linux::WireGuard

perl -MCPAN -e shell
install Linux::WireGuard