NAME

    OpusVL::SimpleCrypto - Very simple encryption methods.

VERSION

    version 0.008

DESCRIPTION

    Simple encrypt and decrypt methods.

        my $s = OpusVL::SimpleCrypto->GenerateKey;
        print $s->key_string, "\n";
        print $s->deterministic_salt_string, "\n";
        my $ct = $s->encrypt('Test');
        my $ct2 = $s->encrypt_deterministic('Test');
    
    
        my $crypto = OpusVL::SimpleCrypto->new({
            key_string => $key_string
            deterministic_salt_string => $deterministic_salt_string
        });
        my $message = $crypto->decrypt($ct);
        my $message2 = $crypto->decrypt($ct2);

    This uses Crypt::Sodium under the hood to do simple symmetric
    (authenticated) encryption and decryption.

    This is for storing information encrypted in a database. Make sure the
    key is not in the database at the same time, otherwise this all becomes
    a bit academic.

    On debian derivative systems you probably need to install the
    libsodium-dev package.

 Choosing when to use encrypt or encrypt_deterministic.

    If you are simply storing a value securely, and will simply retrieve it
    to display it to the user, use encrypt. It's more secure and will allow
    the data to be stored as securely as a piece of software can.

    If you need to look up an exact value, for example the value is a key
    on the row, use encrypt_deterministic. This means that you can
    encrypt_deterministic the search value, and then search the database
    without needing to decrypt any of the data.

    If you want to search for text within an encrypted value, this library
    won't cut it. You'll need to look for searchable encryption. This
    normally involves indexes outside the main corpus that are also
    encrypted, but having some determinism while hopefully not leaking too
    much information. It requires some serious engineering, and is
    generally really hard to do right.

METHODS

 GenerateKey

    Create a key and salt and then return new OpusVL::SimpleCrypto
    initialized with it.

    Use the key_string method to get the key out in a format useful for
    storing.

    You could run a quick command to print off some newly generated keys
    like this,

        perl -MOpusVL::SimpleCrypto -e '$k = OpusVL::SimpleCrypto->GenerateKey; printf("Key: %s\nSalt: %s\n", $k->key_string, $k->deterministic_salt_string)'

 encrypt

    Encrypt text.

    The method should have these properties,

      * Encrpyting the same thing with the same key should not produce the
      same result.

      * Encrypting a very similar value should not produce a similar
      ciphertext.

      * The ciphertext is not malleable.

      It should not be possible to modify it to generate a different plain
      text.

 encrypt_deterministic

    This encrypts text like the encrypt function, except that the same
    thing encrypted with the same key will produce the same ciphertext.

    This is useful when you want to search for the exact thing again.

    The ciphertext produced by this will be decryptable by the same decrypt
    function.

    If you encrypt 2 similar strings, i.e. '000001' and '000002' the cipher
    text however should be very different.

    The properties of this function should make searching for an exact
    value possible, without needing to decrypt all the possible values. It
    will not allow for partial searches of the encrypted values without
    decrypting first.

    This method allows more potential attacks than the data encrypted by
    encrypt, so only use it where necessary.

    This method has the following properties,

      * Encrpyting the same thing with the same key *should* produce the
      same result.

      * Encrypting a very similar value should not produce a similar
      ciphertext.

      * The ciphertext is not malleable.

      It should not be possible to modify it to generate a different plain
      text.

      * It is slower than the encrypt method.

 decrypt

    Decrypt text. Note that ciphertext that has been meddled with will not
    decrypt, and the function will return undef instead.

ATTRIBUTES

    Either set the string values, or the raw binary values, you don't need
    to try setting all 4 at once. Pick 2.

    If you want to generate new info for a fresh configuration construct an
    object with them populated with the GenerateKey constructor.

 key_string

    The key in a text friendly format.

 key

    The key in binary.

 deterministic_salt_string

    This is the salt used for deterministic encrpytion in a text friendly
    format.

    This is required for the encrypt_deterministic function.

 deterministic_salt

    This is the binary of the salt used for deterministic encrpytion.

AUTHOR

    Colin Newell <colin@opusvl.com>

COPYRIGHT AND LICENSE

    This software is copyright (c) 2016 by OpusVL.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.