lib/evil.pm

   1 #!/usr/bin/perl
   2 package evil;
   3
   4 use 5.008009;
   5 use strict;
   6 use warnings;
   7
   8 use Carp;
   9
  10 our $VERSION = 0.001;
  11
  12 our %tainted;
  13 our $strict;
  14
  15 sub import {
  16         $tainted{caller()} = 1;
  17         croak "Cannot load evil module when \"no evil ':strict'\" is in effect" if $strict;
  18 }
  19
  20 sub unimport {
  21         my $strict_arg = grep /^:strict$/, @_;
  22         my $disable_arg = grep /^:disable/, @_;
  23         carp 'no evil; interpreted as no evil ":strict". This will change in a future version of Acme::Evil' unless $strict_arg || $disable_arg;
  24         $strict = 1 unless $disable_arg; # To be changed when other modes are implemented
  25         $strict = 0 if $disable_arg;
  26         if ($strict && %tainted) {
  27                 croak "Evil module already loaded. Cannot enforce \"no evil ':strict'\"";
  28         }
  29 }
  30
  31 1;
  32 __END__
  33
  34 =encoding utf-8
  35
  36 =head1 NAME
  37
  38 evil - RFC 3514 (evil bit) implementation for Perl modules
  39
  40 =head1 SYNOPSIS
  41
  42   # in A.pm
  43   package A;
  44   use evil;
  45   ...
  46
  47   # in B.pm
  48   package B;
  49   no evil ':strict';
  50   use A; # <dies>
  51   ...
  52
  53
  54 =head1 DESCRIPTION
  55
  56 L<RFC3514|https://www.ietf.org/rfc/rfc3514.txt> introduces a new flag
  57 called the "evil bit" in all IP packets. The intention is to simplify
  58 the work of firewalls. Software that sends IP packets with malicious
  59 intent must set the evil bit to true, and firewalls can simply drop
  60 such packets.
  61
  62 The evil pragma is a Perl implementation of the same concept. With
  63 this pragma malicious modules can declare their evil intent while
  64 critical modules can request that they will only use / run alongside
  65 non-evil code.
  66
  67 The pragma can be used in the following ways:
  68
  69 =over
  70
  71 =item use B<evil>;
  72
  73 Marks the current package as evil. All malicious modules MUST use this
  74 directive to ensure the full functionality of this module.
  75
  76 =item no B<evil> ':strict';
  77
  78 The calling module function properly if malignant code is loaded
  79 anywhere in the program. Throws an exception if an evil module is
  80 loaded, whether at the moment of calling this pragma or in the future.
  81
  82 =item no B<evil> ':disable';
  83
  84 Removes the effect of any previous C<no B<evil> ':strict'>. In other
  85 words evil modules will now be allowed to be loaded.
  86
  87 =item no B<evil> ':intermediate'; (TODO)
  88
  89 Not yet implemented. The calling module cannot function properly if it
  90 is using evil code, whether directly or indirectly. Throws an
  91 exception if an evil module is loaded by the calling module or by one
  92 of the children modules (or by one of their children modules, etc).
  93
  94 =item no B<evil> ':lax'; (TODO)
  95
  96 Not yet implemented. The calling module cannot function properly if it
  97 is using evil code direcly. Throws an exception if the calling module
  98 loads an evil module.
  99
 100 =item no B<evil>;
 101
 102 This would normally be equivalent to C<no evil ':intermediate';> but
 103 since that mode is not yet implemented this call does the same as
 104 C<no evil ':strict';> while also emitting a warning saying that this
 105 behaviour will change in a future version.
 106
 107 =back
 108
 109 =head1 AUTHOR
 110
 111 Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
 112
 113 =head1 COPYRIGHT AND LICENSE
 114
 115 Copyright (C) 2016 by Marius Gavrilescu
 116
 117 This library is free software; you can redistribute it and/or modify
 118 it under the same terms as Perl itself, either Perl version 5.22.2 or,
 119 at your option, any later version of Perl 5 you may have available.
 120
 121
 122 =cut