class ref name: vettra1_crypt_o
class name: vettra1_crypt
category-group: security
layer: 2
header file: z_crypt.h
libraries: libz00.lib libz01.lib libz02.lib

synopsis.
vettra1_crypt_o is a simple symmetric block cipher. It does not require a specific block size - it simply does one byte at a time. Thus, the size of the block to encrypt can be as small as 1 byte. The password length must be in [1 .. 4095]. A longer password is, as always, considered better.

The cipher algorithm was originally created and implemented in 1984, as an experiment. The encoding technique is quite different from most other encryption algorithms (DES, Rijndael, blowfish, etc) and is being kept secret. There are plans to implement another cipher, based on the same methodology, in the future. Hence, this particular cipher is called "vettra-1". The next cipher Vettrasoft creates would be called "vettra-2".

member functions (primary)

vettra1_crypt_o()
SIGNATURE: vettra1_crypt_o ()
SYNOPSIS: creates a a new vettra1_crypt encryption object.
 

vettra1_crypt_o(vettra1_crypt_o)
SIGNATURE: vettra1_crypt_o (const vettra1_crypt_o &that)
SYNOPSIS:
creates a a new (vettra1_crypt) encryption object. the password for the new object will be the same as for the copied object (parameter 'that').
 

operator = (vettra1_crypt_o)
SIGNATURE: const vettra1_crypt_o &operator = (const vettra1_crypt_o &that)
SYNOPSIS:
copies the encryption object 'that' into the current encryption object. The password for the current object will be the same as for the copied object ('that').
 

destructor
SIGNATURE: ~vettra1_crypt_o ()
SYNOPSIS:
virtual destructor. The instance settings are reset (password is reset to nothing). also, the base class variables are reset.
 

input_chunksize()
SIGNATURE: size_t input_chunksize (int *pi = NULL) const
SYNOPSIS:
returns the value of the input string's "chunk size" for this algorithm, in bytes. The size of the input block must be a multiple of this value. For the vettra1 class, this is simply 1.
 

output_chunksize()
SIGNATURE: size_t output_chunksize (int *pi = NULL) const
SYNOPSIS: returns the value of the output string's "chunk size". in this case, it is 1 byte.
 

set_key()
SIGNATURE: int set_key (const string_o &s, int *pi = NULL)
SYNOPSIS: sets the password. This function must be invoked prior to any encryption or decryption.
PARAMETERS

  • s: the password. Must be at least 1 byte long, and no more than 4095 bytes in length.
  • pi: [optional] error indicator [output] variable. Values:
    0: operation successful
    zErr_Param_OuttaBounds: invalid key size
 

reset()
SIGNATURE: int reset ()
SYNOPSIS:
resets the object instance. The internal contents are wiped clean. Also, base class variables (in crypto_o) are reset.
 

clone()
SIGNATURE: crypto_o *clone () const
SYNOPSIS: creates a copy of the current object and returns a pointer to the newly created object.
 

encrypt()
SIGNATURE: int encrypt (const string_o &si, string_o &so, size_t *nb, int *pi = NULL)
SYNOPSIS: encrypts the string "si". The resultant encrypted output is put into output variable 'so'.
PARAMETERS

  • si: [input]: the data to encrypt. it can be text or binary. the contents must be at least as long as that specified by the 3rd parameter, 'nb'.
  • so: [output]: the encrypted data. this is basically binary bytes. the size of the string object may be expanded to accomodate this data.
  • nb: [input and output] the number of bytes to encrypt. it must be set prior to invoking this function. the output value is the number of bytes in the encrypted string (basically equal to 'so.size()')
  • pi: [output] error indicator. values:
    0: successful encryption
    zErr_NotConfigured: key was not set
RETURNS:
0: successful encryption
-1: otherwise (see value of 'pi')
 

decrypt()
SIGNATURE: int decrypt (const string_o &si, string_o &so, size_t *nb, int *pi = NULL)
SYNOPSIS: decrypts ciphered data in 'si'. The resultant decrypted data is put into 'so'. The converse of encrypt().
PARAMETERS

  • si: [input]: the encrypted data to decrypt. The contents must be at least as long as that specified by the 3rd parameter, 'nb'.
  • so: [output]: the decrypted data. the size of the string object may be expanded to accomodate this data.
  • nb: [input and output] the number of bytes in the decrypted output string.
  • pi: [output] error indicator. values:
    0: successful decryption
    zErr_NotConfigured: key was not set
RETURNS:
0: successful decryption
-1: otherwise (see value of 'pi')
 

usage.
Using vettra1_crypt_o is about as easy as it gets with the ciphers of the Z Directory. Just set the password, encrypt, then decrypt. the same instance that encrypted must be used for decryption (or a copy of the object), since the [encoded] password is stored in the object.

examples.
The following complete program uses the vettra1_crypt_o in a straightforward case of encrypting and decrypting a text string:

#include "z_crypt.h"

static char *my_text =
"Cryptography - the science of secret writing - is an ancient art. \
The first use of cryptography in writing dates back to 1900 BC, when an \
Egyptian scribe used non-standard hieroglyphs in an inscription.\n";

static char *my_pass =
"it is better to try and fail, then to never have tried at all. as for the \
vettra-1 password, make it long! But then, the biggest problem will be to \
remember it.";

int main (const int argc, const char *argv[])
{
    int ie0, ie1, ie2;
    size_t len;
    boolean passed = FALSE;
    string_o ssin, senc, sout;

    vettra1_crypt_o x;

    ssin  = my_text;
    len = ssin.size();

    ie0 = x.set_key (my_pass);
    ie1 = x.encrypt (ssin, senc, &len);
    ie2 = x.decrypt (senc, sout, &len); // note that 'len' does not change
    if (ie0 < 0 || ie1 || ie2)
    {
        std::cout << "error in setting key, encryption, or decryption.\n";
        exit(1);
    }

    if (ssin == sout)
        { passed = TRUE; std::cout << "vettra1 cipher test: PASSED\n"; }
    else
        { passed = FALSE; std::cout << "vettra1 cipher test: FAILED\n"; }

    return (passed) ? 0 : 1;
}