| 1 | 6 | ▶ | use v5.20; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 2 | 6 | ▶ | use utf8; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 3 | |||||||||||||||||||||
| 4 | package String::Redactable; | ||||||||||||||||||||
| 5 | 6 | ▶ | use experimental qw(signatures); | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 6 | 6 | ▶ | use warnings::register; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 7 | |||||||||||||||||||||
| 8 | 6 | ▶ | use Carp qw(carp); | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 9 | 6 | ▶ | use Encode (); | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 10 | |||||||||||||||||||||
| 11 | 6 | our $VERSION = '1.088'; | |||||||||||||||||||
| 12 | |||||||||||||||||||||
| 13 | =encoding utf8 | ||||||||||||||||||||
| 14 | |||||||||||||||||||||
| 15 | =head1 NAME | ||||||||||||||||||||
| 16 | |||||||||||||||||||||
| 17 | String::Redactable - A string that automatically redacts itself | ||||||||||||||||||||
| 18 | |||||||||||||||||||||
| 19 | =head1 SYNOPSIS | ||||||||||||||||||||
| 20 | |||||||||||||||||||||
| 21 | use String::Redactable; | ||||||||||||||||||||
| 22 | |||||||||||||||||||||
| 23 | my $string = String::Redactable->new( $sensitive_text ); | ||||||||||||||||||||
| 24 | |||||||||||||||||||||
| 25 | say $string; # '<redacted string>' | ||||||||||||||||||||
| 26 | say $string->to_str_unsafe; # unredacted text | ||||||||||||||||||||
| 27 | |||||||||||||||||||||
| 28 | =head1 DESCRIPTION | ||||||||||||||||||||
| 29 | |||||||||||||||||||||
| 30 | C<String::Redactable> tries to prevent you from accidentally exposing | ||||||||||||||||||||
| 31 | a sensitive string, such as a password, in a larger string, such as a | ||||||||||||||||||||
| 32 | log message or data dump. | ||||||||||||||||||||
| 33 | |||||||||||||||||||||
| 34 | When you carelessly use this as a simple string, you get back the | ||||||||||||||||||||
| 35 | literal string C<*redacted data*>. To get the actual string, you call | ||||||||||||||||||||
| 36 | C<to_str_unsafe>: | ||||||||||||||||||||
| 37 | |||||||||||||||||||||
| 38 | $password->to_str_unsafe; | ||||||||||||||||||||
| 39 | |||||||||||||||||||||
| 40 | This is not designed to completely protect the sensitive data from | ||||||||||||||||||||
| 41 | prying eyes. This is simply the UTF-8 encoded version of the value that | ||||||||||||||||||||
| 42 | is XOR-ed by an object-specific key that is not stored with the object. | ||||||||||||||||||||
| 43 | All of that is undone by C<to_str_unsafe>. | ||||||||||||||||||||
| 44 | |||||||||||||||||||||
| 45 | Beyond that, this module uses L<overload> and other tricks to prevent | ||||||||||||||||||||
| 46 | the actual string from showing up in output and other strings. | ||||||||||||||||||||
| 47 | |||||||||||||||||||||
| 48 | =head2 Notes on serializers | ||||||||||||||||||||
| 49 | |||||||||||||||||||||
| 50 | C<String::Redactable> objects resist serialization to the best of | ||||||||||||||||||||
| 51 | their ability. At worst, the serialization shows the internal string | ||||||||||||||||||||
| 52 | for the object, which does not expose the key used to XOR the UTF-8 | ||||||||||||||||||||
| 53 | encoded string. | ||||||||||||||||||||
| 54 | |||||||||||||||||||||
| 55 | Since the XOR keys are not stored in the object (and those keys are | ||||||||||||||||||||
| 56 | removed when the object goes out of scope), these values cannot be | ||||||||||||||||||||
| 57 | serialized and re-inflated. But, that's what you want. | ||||||||||||||||||||
| 58 | |||||||||||||||||||||
| 59 | =over 4 | ||||||||||||||||||||
| 60 | |||||||||||||||||||||
| 61 | =item * L<Data::Dumper> - cannot use C<$Data::Dump::Freezer> because that | ||||||||||||||||||||
| 62 | requires the | ||||||||||||||||||||
| 63 | |||||||||||||||||||||
| 64 | =item * L<Storable> - | ||||||||||||||||||||
| 65 | |||||||||||||||||||||
| 66 | =item * JSON modules - this supports C<TO_JSON> | ||||||||||||||||||||
| 67 | |||||||||||||||||||||
| 68 | =item * YAML - | ||||||||||||||||||||
| 69 | |||||||||||||||||||||
| 70 | |||||||||||||||||||||
| 71 | =back | ||||||||||||||||||||
| 72 | |||||||||||||||||||||
| 73 | =head2 Methods | ||||||||||||||||||||
| 74 | |||||||||||||||||||||
| 75 | =over 4 | ||||||||||||||||||||
| 76 | |||||||||||||||||||||
| 77 | =item new | ||||||||||||||||||||
| 78 | |||||||||||||||||||||
| 79 | =cut | ||||||||||||||||||||
| 80 | |||||||||||||||||||||
| 81 | use overload | ||||||||||||||||||||
| 82 | 24 | ▶ | q("") => sub { $_[0]->placeholder }, | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.5
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 83 | 0 | ▶ | '0+' => sub { 0 }, | ||||||||||||||||||
|
Subroutine
__ANON__: not called CC=1 SCAR=6.9
| |||||||||||||||||||||
| 84 | 0 | ▶ | '-X' => sub { () }, | ||||||||||||||||||
|
Subroutine
__ANON__: not called CC=1 SCAR=6.9
| |||||||||||||||||||||
| 85 | |||||||||||||||||||||
| 86 | 0 | ▶ | map { $_ => sub { () } } qw( | ||||||||||||||||||
|
Subroutine
__ANON__: not called CC=1 SCAR=0.4
| |||||||||||||||||||||
| 87 | <=> cmp | ||||||||||||||||||||
| 88 | lt le gt ge eq ne | ||||||||||||||||||||
| 89 | ~~ | ||||||||||||||||||||
| 90 | ) | ||||||||||||||||||||
| 91 | 6 | ; | |||||||||||||||||||
| 92 | |||||||||||||||||||||
| 93 | 6 | my %keys = (); | |||||||||||||||||||
| 94 | |||||||||||||||||||||
| 95 | 8 | ▶ | my $new_key = sub ($class, $length = 512) { | ||||||||||||||||||
|
Subroutine
__ANON__: called CC=2 SCAR=6.9
| |||||||||||||||||||||
| 96 | 8 | state $rc = require List::Util; | |||||||||||||||||||
| 97 | substr( | ||||||||||||||||||||
| 98 | join( '', | ||||||||||||||||||||
| 99 | List::Util::shuffle( | ||||||||||||||||||||
| 100 | 8 | map { List::Util::shuffle( 'A' .. 'Z', 'a' .. 'z', qw(= ! : ;) ) } 1 .. 25 | |||||||||||||||||||
| 101 | ) | ||||||||||||||||||||
| 102 | ), | ||||||||||||||||||||
| 103 | 0, $length | ||||||||||||||||||||
| 104 | ) | ||||||||||||||||||||
| 105 | ; | ||||||||||||||||||||
| 106 | 6 | }; | |||||||||||||||||||
| 107 | |||||||||||||||||||||
| 108 | =item new( STRING ) | ||||||||||||||||||||
| 109 | |||||||||||||||||||||
| 110 | Creates an object that hides that string by XOR-ing it with another string that | ||||||||||||||||||||
| 111 | is not stored in the object, and is not a package variable. | ||||||||||||||||||||
| 112 | |||||||||||||||||||||
| 113 | This does not mean that the original string can't be recovered in other ways if | ||||||||||||||||||||
| 114 | someone wanted to try hard enough, but it keeps you from unintentionally dumping | ||||||||||||||||||||
| 115 | it into output where it shouldn't be. | ||||||||||||||||||||
| 116 | |||||||||||||||||||||
| 117 | =cut | ||||||||||||||||||||
| 118 | |||||||||||||||||||||
| 119 | 10 | ▶ | sub new ($class, $string, $opts={}) { | ||||||||||||||||||
|
Subroutine
new: called CC=4 SCAR=14.4
Pod
documented
| |||||||||||||||||||||
| 120 | 10 | ▶ | unless( length $string ) { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 121 | 0 | carp sprintf "Argument to %s::new is zero length", __PACKAGE__; | |||||||||||||||||||
| 122 | 0 | return; | |||||||||||||||||||
| 123 | } | ||||||||||||||||||||
| 124 | |||||||||||||||||||||
| 125 | 10 | ▶ | my $key = $opts->{'key'} // $new_key->( 5 * length $string ); | ||||||||||||||||||
|
Condition66%2/3
$opts->{"key"} // &$new_key(5 * length($string))
MC/DC0%0/2
$opts->{"key"} // &$new_key(5 * length($string))
$opts->{"key"}
&$new_key(5 * length($string))
Truth table66%2/3
A // B
A= $opts->{"key"}B= &$new_key(5 * length($string))
| |||||||||||||||||||||
| 126 | |||||||||||||||||||||
| 127 | 10 | my $encoded = Encode::encode( 'UTF-8', $string ); | |||||||||||||||||||
| 128 | 10 | my $hidden = ($encoded ^ $key); | |||||||||||||||||||
| 129 | 10 | my $self = bless \$hidden, $class; | |||||||||||||||||||
| 130 | 10 | ▶ | { local $SIG{__WARN__} = sub {}; $keys{overload::StrVal($self)} = $key }; | ||||||||||||||||||
|
Subroutine
__ANON__: not called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 131 | 10 | $self; | |||||||||||||||||||
| 132 | } | ||||||||||||||||||||
| 133 | |||||||||||||||||||||
| 134 | 10 | ▶ | sub DESTROY ($self) { | ||||||||||||||||||
|
Subroutine
DESTROY: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 135 | 10 | ▶ | local $SIG{__WARN__} = sub {}; | ||||||||||||||||||
|
Subroutine
__ANON__: not called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 136 | 10 | delete $keys{overload::StrVal($self)}; | |||||||||||||||||||
| 137 | } | ||||||||||||||||||||
| 138 | |||||||||||||||||||||
| 139 | =item placeholder | ||||||||||||||||||||
| 140 | |||||||||||||||||||||
| 141 | The value that is substituted for the actual string. | ||||||||||||||||||||
| 142 | |||||||||||||||||||||
| 143 | =cut | ||||||||||||||||||||
| 144 | |||||||||||||||||||||
| 145 | 54 | ▶ | sub placeholder ( $class ) { | ||||||||||||||||||
|
Subroutine
placeholder: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||||||||||||
| 146 | 54 | state $rc = require Carp; | |||||||||||||||||||
| 147 | 54 | ▶ | Carp::cluck( | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 148 | "Possible unintended interpolation of a redactable string", | ||||||||||||||||||||
| 149 | ) if warnings::enabled(); | ||||||||||||||||||||
| 150 | 54 | '<redacted data>' | |||||||||||||||||||
| 151 | } | ||||||||||||||||||||
| 152 | |||||||||||||||||||||
| 153 | =item STORABLE_freeze | ||||||||||||||||||||
| 154 | |||||||||||||||||||||
| 155 | Redact strings used in L<Storable>. | ||||||||||||||||||||
| 156 | |||||||||||||||||||||
| 157 | =cut | ||||||||||||||||||||
| 158 | |||||||||||||||||||||
| 159 | 0 | ▶ | sub STORABLE_freeze ($self, $cloning) { | ||||||||||||||||||
|
Subroutine
STORABLE_freeze: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||||||||||||
| 160 | 0 | $self->placeholder; | |||||||||||||||||||
| 161 | } | ||||||||||||||||||||
| 162 | |||||||||||||||||||||
| 163 | =item TO_JSON | ||||||||||||||||||||
| 164 | |||||||||||||||||||||
| 165 | Redact the string in serializers that respect C<TO_JSON>. | ||||||||||||||||||||
| 166 | |||||||||||||||||||||
| 167 | =cut | ||||||||||||||||||||
| 168 | |||||||||||||||||||||
| 169 | 0 | ▶ | sub TO_JSON { | ||||||||||||||||||
|
Subroutine
TO_JSON: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||||||||||||
| 170 | 0 | $_[0]->placeholder; | |||||||||||||||||||
| 171 | } | ||||||||||||||||||||
| 172 | |||||||||||||||||||||
| 173 | =item to_str_unsafe | ||||||||||||||||||||
| 174 | |||||||||||||||||||||
| 175 | Returns the string that you are trying to hide. | ||||||||||||||||||||
| 176 | |||||||||||||||||||||
| 177 | =cut | ||||||||||||||||||||
| 178 | |||||||||||||||||||||
| 179 | 12 | ▶ | sub to_str_unsafe ($self) { | ||||||||||||||||||
|
Subroutine
to_str_unsafe: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 180 | 12 | ▶ | local $SIG{__WARN__} = sub {}; | ||||||||||||||||||
|
Subroutine
__ANON__: not called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 181 | 12 | my $encoded = ($$self ^ $keys{overload::StrVal($self)}) =~ s/\000+\z//r; | |||||||||||||||||||
| 182 | 12 | Encode::decode( 'UTF-8', $encoded ); | |||||||||||||||||||
| 183 | } | ||||||||||||||||||||
| 184 | |||||||||||||||||||||
| 185 | =back | ||||||||||||||||||||
| 186 | |||||||||||||||||||||
| 187 | =head1 TO DO | ||||||||||||||||||||
| 188 | |||||||||||||||||||||
| 189 | |||||||||||||||||||||
| 190 | =head1 SEE ALSO | ||||||||||||||||||||
| 191 | |||||||||||||||||||||
| 192 | |||||||||||||||||||||
| 193 | =head1 SOURCE AVAILABILITY | ||||||||||||||||||||
| 194 | |||||||||||||||||||||
| 195 | This source is on Github: | ||||||||||||||||||||
| 196 | |||||||||||||||||||||
| 197 | http://github.com/briandfoy/string-redactable | ||||||||||||||||||||
| 198 | |||||||||||||||||||||
| 199 | =head1 AUTHOR | ||||||||||||||||||||
| 200 | |||||||||||||||||||||
| 201 | brian d foy, C<< <briandfoy@pobox.com> >> | ||||||||||||||||||||
| 202 | |||||||||||||||||||||
| 203 | =head1 COPYRIGHT AND LICENSE | ||||||||||||||||||||
| 204 | |||||||||||||||||||||
| 205 | Copyright © 2025-2026, brian d foy, All Rights Reserved. | ||||||||||||||||||||
| 206 | |||||||||||||||||||||
| 207 | You may redistribute this under the terms of the Artistic License 2.0. | ||||||||||||||||||||
| 208 | |||||||||||||||||||||
| 209 | =cut | ||||||||||||||||||||
| 210 | |||||||||||||||||||||
| 211 | 6 | __PACKAGE__; | |||||||||||||||||||