Secret::Simple - Secure secrets in configurations and code
This document describes Secret::Simple version 0.11
# OOP style my $ss = Secret::Simple->new(); my $ciphertext = $ss->encrypt($plaintext); my $plaintext = $ss->decrypt($ciphertext); # procedural style my $ciphertext = ssencrypt($plaintext); my $plaintext = ssdecrypt($ciphertext);
This module implements a straightforward interface for encrypting and decrypting secret information such as user IDs and passwords (e.g. database connection or remote account credentials). Secret::Simple can also be used on a limited basis to protect arbitrary data. By default the ciphertext returned is Base 64 encoded so as to be easily embedded within configurations or scripts. A command-line utility called sstool is included to facilitate easy manipulation of cipher and plaintext snippets.
Secret::Simple
sstool
The encryption mechanism utilizes the strong AES algorithm, so any weaknesses in Secret::Simple predominantly lie in how keys are protected. A balance must be struck between key accessibility, key protection, and overall complexity. The calling code can supply a key, series of keys, key files, or a combination. If no key information is explicitly passed, the module will attempt to use the OS user's private SSH DSA key file by default if it exists.
The major goal of this module is to be as secure as possible while being simple and convenient enough to encourage its use. Psychology does factor in: simple is a very important consideration. If the security methods are too onerous or complicated to use, many sysadmins or developers may simply use plaintext (no protection other that OS file permissions) or simple ciphers like rot13. The security of the Secret::Simple method is not perfect, but it does represent a significant improvement over commonly-used nonsecure methods of embedding credentials and other secrets in Perl configurations and scripts. If used appropriately, Secret::Simple can greatly improve application and configuration security. Even so, care must always be taken to protect files and file permissions.
new()
my $ss = Secret::Simple->new(); # default to user's private SSH DSA key my $ss = Secret::Simple->new('my secret key'); my $ss = Secret::Simple->new( %options ); my $ss = Secret::Simple->new( \%options );
The constructor returns a Secret::Simple object. Valid options are:
The value of this parameter can be a scalar or array reference. Multiple elements will simply be concatenated together. This option accepts raw key data by default, but can also accept file-based key data according to the following parameter value syntax:
'secret key phrase' - string is the literal key (default) '{sskeyfile}/path/key.raw' - read raw key from file '{sskeyfile}' - read raw key from default file
Specifying {sskeyfile} by itself will designate the same behavior as the default of passing no key information: the constructor will attempt to use the literal contents of the current user's ~/.ssh/id_dsa file as a key.
{sskeyfile}
~/.ssh/id_dsa
Specifies the maximum number of bytes to read from a single key file. The default value of 0 is unlimited, but performance problems may quickly arise if large files (e.g. MP3) are utilized as keys.
decrypt()
Returns the literal plaintext of the supplied encrypted and Base 64 encoded value.
Example:
my $DBCRED = 'zzpjnDlUqz3+KCke5Rr4dA=='; # plaintext is jblow^secret my $ss = Secret::Simple->new(); my ($user, $pass) = split /\^/, $ss->decrypt($DBCRED);
decryptraw()
Performs identically to the decrypt() method except that the value passed is assumed to be raw ciphertext (no Base 64 encoding).
encrypt()
Returns the Base 64 encoded ciphertext of the supplied literal plaintext.
my $ss = Secret::Simple->new(); my $ciphertext = $ss->encrypt('jblow^secret'); # ciphertext will resemble: zzpjnDlUqz3+KCke5Rr4dA==
encryptraw()
Performs identically to the encrypt() method except the resulting ciphertext is returned without the Base 64 encoding.
key()
This method can be invoked without an argument to obtain the current key specification value(s). Note that this is not necessarily the same as the information returned by the keydata() method. Invoking with an argument will establish new settings. See the description of the new() method's -key option for more details.
keydata()
-key
Returns the combined raw key data. The returned data represents the aggregate raw key if multiple keys and key files were specified.
keyfilesize()
The maximum number of bytes to read from a single key file. This method can be invoked without an argument to obtain the current limit setting (default 0 is unlimited). Invoking with an argument will establish the new setting.
Secret::Simple exports some functions you may use to avoid the OOP interface if you wish.
ssdecrypt($b64ciphertext, [key1], [key2], ...)
This function requires a minimum of one argument: the Base 64 encoded ciphertext to be decrypted. Any number of optional additional arguments may be specified as key values that follow the same rules as the new() constructor's -key option.
Examples:
my $DBCRED = 'zzpjnDlUqz3+KCke5Rr4dA=='; # plaintext is jblow^secret # 1. simple my ($user, $pass) = split /\^/, ssdecrypt($DBCRED); # 2. id_rsa instead of id_dsa my ($user, $pass) = split /\^/, ssdecrypt($DBCRED, '{sskeyfile}~/.ssh/id_rsa'); # 3. more complex example my ($user, $pass) = split /\^/, ssdecrypt($DBCRED, '{sskeyfile}', '{sskeyfile}/path/otherkey');
ssdecryptraw($ciphertext, [key1], [key2], ...)
Performs identically to the ssdecrypt() function except that the value passed must be raw ciphertext without Base 64 encoding.
ssdecrypt()
ssencrypt($plaintext, [key1], [key2]...)
This function requires a minimum of one argument: the plaintext to be encrypted. Any number of optional additional arguments may be specified as key values that follow the same rules as the new() constructor's -key option.
# use default ~/.ssh/id_dsa key my $ciphertext = ssencrypt('jblow^secret'); # use explicit passphrase my $ciphertext = ssencrypt('jblow^secret', 'secret key'); # use combination of two key files my $ciphertext = ssencrypt('jblow^secret', '{sskeyfile}/path1/key1', '{sskeyfile}/path2/key2');
ssencryptraw($plaintext, [key1], [key2], ...)
Performs identically to the ssencrypt() function except the resulting ciphertext is returned without the Base 64 encoding.
ssencrypt()
This module requires the following other modules:
Carp
Crypt::CBC
Crypt::Rijndael_PP
Exporter
MIME::Base64
Adam G. Foust, <nospam-agf@cpan.org>
Copyright (c) 2006, Adam G. Foust. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Secret::Simple, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Secret::Simple
CPAN shell
perl -MCPAN -e shell install Secret::Simple
For more information on module installation, please visit the detailed CPAN module installation guide.