File Coverage

blib/lib/Linux/WireGuard.pm
Criterion Covered Total %
statement 9 9 100.0
branch n/a
condition n/a
subroutine 3 3 100.0
pod n/a
total 12 12 100.0


line stmt bran cond sub pod time code
1             package Linux::WireGuard;
2              
3 3     3   1127 use strict;
  3         14  
  3         66  
4 3     3   12 use warnings;
  3         5  
  3         69  
5              
6             =encoding utf-8
7              
8             =head1 NAME
9              
10             Linux::WireGuard - L in Perl
11              
12             =head1 SYNOPSIS
13              
14             my @names = Linux::WireGuard::list_device_names();
15              
16             my %device = map { $_ => Linux::WireGuard::get_device($_) } @names;
17              
18             =head1 DESCRIPTION
19              
20             Linux::WireGuard provides an interface to WireGuard via
21             L.
22              
23             NB: Although WireGuard itself is cross-platform, its embedded C
24             library is Linux-specific.
25              
26             =head1 CHARACTER ENCODING
27              
28             All strings into & out of this module are byte strings.
29              
30             =head1 ERROR HANDLING
31              
32             Failures become Perl exceptions. Currently those exceptions are
33             plain strings. Errors that come from WireGuard also manifest as
34             changes to Perl’s C<$!> global; for example, if you try to
35             C while non-root, you’ll probably see (besides the
36             thrown exception) C<$!> become Errno::EPERM.
37              
38             =cut
39              
40             #----------------------------------------------------------------------
41              
42 3     3   13 use XSLoader;
  3         4  
  3         167  
43              
44             our $VERSION = '0.02';
45              
46             XSLoader::load( __PACKAGE__, $VERSION );
47              
48             #----------------------------------------------------------------------
49              
50             =head1 FUNCTIONS
51              
52             =head2 @names = list_device_names()
53              
54             Returns a list of strings.
55              
56             =head2 $dev_hr = get_device( $NAME )
57              
58             Returns a reference to a hash that describes the $NAME’d device:
59              
60             =over
61              
62             =item * C
63              
64             =item * C
65              
66             =item * C and C (raw strings, or undef)
67              
68             =item * C (can be undef)
69              
70             =item * C (can be undef)
71              
72             =item * C - reference to an array of hash references. Each hash is:
73              
74             =over
75              
76             =item * C and C (raw strings, or undef)
77              
78             =item * C - Raw sockaddr data (a string), or undef. To parse
79             the sockaddr, use L’s C to determine the
80             address family, then C for Socket::AF_INET or
81             C for Socket::AF_INET6.
82              
83             =item * C and C
84              
85             =item * C (can be undef)
86              
87             =item * C and C
88              
89             =item * C - reference to an array of hash references. Each hash is:
90              
91             =over
92              
93             =item * C - Socket::AF_INET or Socket::AF_INET6
94              
95             =item * C - A packed IPv4 or IPv6 address. Unpack with L’s
96             C or C.
97              
98             =item * C
99              
100             =back
101              
102             =back
103              
104             =back
105              
106             =head2 add_device( $NAME )
107              
108             Adds a WireGuard device with the given $NAME.
109              
110             =head2 del_device( $NAME )
111              
112             Deletes a WireGuard device with the given $NAME.
113              
114             =head2 $bin = generate_private_key()
115              
116             Returns a newly-generated private key (raw string).
117              
118             =head2 $bin = generate_public_key( $PRIVATE_KEY )
119              
120             Takes a private key and returns its public key. (Both raw strings.)
121              
122             =head2 $bin = generate_preshared_key()
123              
124             Returns a newly-generated preshared key (raw string).
125              
126             =head1 TODO
127              
128             An implementation of C would be nice to have.
129              
130             =head1 LICENSE & COPYRIGHT
131              
132             Copyright 2022 Gasper Software Consulting. All rights reserved.
133              
134             Linux::WireGuard is licensed under the same terms as Perl itself (cf.
135             L); B, the embedded C wireguard library has its
136             own copyright terms. Use of Linux::WireGuard I imply acceptance of
137             that embedded C library’s own copyright terms. See this distribution’s
138             F for details.
139              
140             =cut
141              
142             1;