/ 
Acme-Evil-0.003002
River stage zero No dependents
/ evil

NAME

evil - RFC 3514 (evil bit) implementation for Perl modules

SYNOPSIS

# in A.pm
package A;
use evil;

# in B.pm
package B;
no evil ':strict';
use A; # <dies>

# in C.pm
package C;
use A;

# in D.pm
package D;
no evil;
use C; # <dies>

# in E.pm
package E;
no evil ':lax';
use C; # does not die, as C is not evil

# in F.pm
package F;
use C;
no evil;
# does not die, as modules loaded before the pragma are ignored

DESCRIPTION

RFC3514 introduces a new flag called the "evil bit" in all IP packets. The intention is to simplify the work of firewalls. Software that sends IP packets with malicious intent must set the evil bit to true, and firewalls can simply drop such packets.

The evil pragma is a Perl implementation of the same concept. With this pragma malicious modules can declare their evil intent while critical modules can request that they will only use / run alongside non-evil code.

The pragma can be used in the following ways:

use evil;

Marks the current package as evil. All malicious modules MUST use this directive to ensure the full functionality of this pragma.

no evil ':strict';

The calling module function properly if malignant code is loaded anywhere in the program. Throws an exception if an evil module is loaded, whether at the moment of calling this pragma or in the future.

no evil ':disable';

Removes the effect of any previous no evil ':something' used in this module, thus stating the module does not care about evil code.

no evil ':intermediate'

The calling module cannot function properly if it is using evil code, whether directly or indirectly. Throws an exception if an evil module is subsequently loaded by the calling module or by one of the children modules (or by one of their children modules, etc). Also throws an exception if the current module is evil.

no evil ':lax';

The calling module cannot function properly if it is using evil code direcly. Throws an exception if the calling module subsequently loads an evil module, or if the current module is evil.

no evil;

Synonym for no evil ':intermediate'.

BUGS

The following does not die:

# Evil.pm
package Evil;
use evil;

# A.pm
package A;
use Evil;

# B.pm
package B;
no evil ':intermediate';
use Evil;

# script.pl
#!/usr/bin/perl
use A;
use B;

Since Evil was loaded by A, B does not load Evil and therefore does not detect that Evil is... evil. If we loaded B before A in script.pl, we would get an exception. So order of loading modules matters for intermediate and lax modes. Strict mode is unaffected by this bug.

CAVEATS

When using intermediate and lax modes, any evil modules loaded before the pragma is enabled are ignored. This is by design, to allow temporarily disabling the pragma. An example:

package MyModule;
no evil;
use Some::Module;
use Another::Module;

no evil ':disable';
use Evil::Module; # does not die
no evil;

use Some::More::Modules;
...

Correct functioning of this pragma depends critically on the evil bit being set properly. If a faulty evil module fails to use evil;, the pragma will not function properly.

AUTHOR

Marius Gavrilescu, <marius@ieval.ro>

COPYRIGHT AND LICENSE

Copyright (C) 2016-2017 by Marius Gavrilescu

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.22.2 or, at your option, any later version of Perl 5 you may have available.