1#	$OpenBSD: Pledge.pm,v 1.2 2016/07/03 01:07:57 afresh1 Exp $	#
2package OpenBSD::Pledge;
3
4use 5.020002;
5use strict;
6use warnings;
7
8use parent 'Exporter';
9our %EXPORT_TAGS = ( 'all' => [qw( pledge pledgenames )] );
10our @EXPORT_OK   = ( @{ $EXPORT_TAGS{'all'} } );
11our @EXPORT      = qw( pledge );                           ## no critic 'export'
12
13our $VERSION = '0.01';
14
15require XSLoader;
16XSLoader::load( 'OpenBSD::Pledge', $VERSION );
17
18sub pledge
19{
20	my (@promises) = @_;
21
22	my $paths;
23	$paths = pop @promises if @promises and ref $promises[-1] eq 'ARRAY';
24
25	my %seen;
26	my $promises = join q{ },
27	    sort grep { !$seen{$_}++ } ( 'stdio', @promises );
28
29	return _pledge( $promises, $paths );
30}
31
321;
33
34## no critic 'pod sections'
35__END__
36
37=head1 NAME
38
39OpenBSD::Pledge - Perl interface to OpenBSD pledge(2)
40
41=head1 SYNOPSIS
42
43  use OpenBSD::Pledge;
44  my $file = "/usr/share/dict/words";
45  pledge(qw( rpath ), [$file]) || die "Unable to pledge: $!";
46
47  open my $fh, '<', $file or die "Unable to open $file: $!\n";
48  while ( readline($fh) ) {
49    print if /pledge/i;
50  }
51  close $fh;
52
53=head1 DESCRIPTION
54
55This module provides a perl interface to OpenBSD's L<pledge(2)> L<syscall(2)>.
56
57Once you promise that your program will only use certain syscalls
58the kernel will kill the program if it attempts to call any other
59interfaces.
60
61=head2 EXPORT
62
63Exports L</pledge> by default.
64
65C<:all> will also export L</pledgenames>
66
67=head1 METHODS
68
69=head2 pledge(@promises, [\@paths])
70
71With L<pledge(2)> you can promise what abilities your program will need.
72You can pledge multiple times with more restrictive promises,
73but abilities can never be regained.
74
75This interface always promises C<stdio> because L<perl(1)> itself uses some of
76the provided system calls.
77
78You can supply an optional array reference of paths to be used as a whitelist,
79all other paths will appear not to exist.
80You may only limit the paths once.
81
82Returns true on success, returns false and sets C<$!> on failure.
83
84=head2 pledgenames
85
86Returns a list of the possible promises you can pass to L</pledge>.
87
88=head1 BUGS AND LIMITATIONS
89
90Perl is particularly fond of C<stdio> so that promise is always added by
91L</pledge>.
92
93=head1 SEE ALSO
94
95L<pledge(2)>
96
97L<http://man.openbsd.org/pledge.2>
98
99=head1 AUTHOR
100
101Andrew Fresh, E<lt>afresh1@OpenBSD.orgE<gt>
102
103=head1 LICENSE AND COPYRIGHT
104
105Copyright (C) 2015 by Andrew Fresh E<lt>afresh1@OpenBSD.orgE<gt>
106
107Permission to use, copy, modify, and distribute this software for any
108purpose with or without fee is hereby granted, provided that the above
109copyright notice and this permission notice appear in all copies.
110
111THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
112WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
113MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
114ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
115WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
116ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
117OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
118
119=cut
120