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