synopsis.
RSA_crypt_o is the Vettrasoft class that provides RSA encryption. Using this encryption algorithm under the Vettrasoft-normalized API works great; there is a peculiarity with this one in that 2 passwords are required (at least for decryption): public and private. This is cleanly handled using the same APIs as with the symmetric algorithms (eg Nile-crypt, AES, DES, etc).

Keys (passwords) for this object are strings with format "#". for example: "655370EB85C4F1BBA2AF09#190CEBF7715F669CA61CC7". Note that this constitutes 1 entire key - it is not just one part [set of hex numbers] or the other. thus, the sequence "655370EB85C4F1BBA2AF09" is not a key - just part of the key.

member functions (primary)

RSA_crypt_o()
SIGNATURE: RSA_crypt_o ()
SYNOPSIS: creates a a new pair crypt object. the object instance has no password(s) but is ready to use.
 

RSA_crypt_o(RSA_crypt_o)
SIGNATURE: RSA_crypt_o (const RSA_crypt_o &that)
SYNOPSIS: creates a a new pair crypt object. the passwords are cloned from pair crypt object 'that'.
 

operator = (RSA_crypt_o)
SIGNATURE: const pair crypt baredisk_o &operator = (const baredisk_o &rhs)
SYNOPSIS:
copies exactly the RHS [Right Hand Side] object 'rhs'. The resultant pair crypt baredisk instance is the same as if the copy constructor was used.
PARAMETERS

rhs: [input] the object to be copied

 

input_chunksize()
SIGNATURE: size_t input_chunksize (int *pi = NULL) const
SYNOPSIS: defines the number of bytes that the size of the input string [to be encoded] must be a multiple of. The value is 10.
PARAMETERS

pi: [output] error indicator variable. in this case the value is always 0

DESCRIPTION:
if a string is to be encrypted, the number of characters must be a multiple of 10 (10, 20, 30, ... [etc] characters long, including any terminating new-lines).
RETURNS: 10 (a constant)
TRAITS: this function redefines the [pure] virtual function from the base class
 

output_chunksize()
SIGNATURE: size_t output_chunksize (int *pi = NULL) const
SYNOPSIS: the size of the output string will be a multiple of this value, which is 11.
PARAMETERS

pi: [output] error indicator variable. in this case the value is always 0

RETURNS: 11 (a constant)
TRAITS: this function redefines the base class [pure] virtual function
 

set_keys()
SIGNATURE: int set_keys (const string_o &pubkey, const string_o &privkey, int *pi = NULL)
SYNOPSIS: set the object's public and private keys with this function. Any previous passwords are overwritten.
PARAMETERS

• pubkey: a string containing the RSA public key. This key looks akin to this: "2FD464CDCD6FCF73CB88E7#79E33DD8F9EDD3AA676F8"
• privkey: a string containing the RSA private key. This value is optional. to de-activate (unset) the private key, provide an empty string for privkey ("").
• pi: [output] error indicator variable. Values:
  0: success
  zcrypERR_BADKEY: one or both of the input string formats do not conform to the correct syntax used here for RSA keys

 

set_key()
SIGNATURE: int set_key (const string_o &s, int *pi = NULL)
SYNOPSIS:
set the object's public key, or set both the object's public and private keys with this function. This function can be used in lieu of set_keys(), and is the "normal" way to set a crypto_o class object's password. this function interface is defined in the base class.
PARAMETERS

• s:
• pi: [output] error indicator variable. Values:
  0: success
  zcrypERR_BADKEY: the input string format does not conform to the correct syntax used here for RSA keys

DESCRIPTION:
to set both public and private keys via this API. If providing both keys, simply concatenate them using a ' ' (space character).
TRAITS: this function redefines the base class [pure] virtual function
 

clone()
SIGNATURE: crypto_o *clone () const
SYNOPSIS:
copies the current object [via new], and provides a pointer to the newly-allocated object. It is the client application's responsibility to delete this object.
TRAITS: this function redefines the [pure] virtual function from the base class. it is an inline function.
 

encrypt()
SIGNATURE: int encrypt (const string_o &sin, string_o &sot, size_t *nb)
SYNOPSIS:
does the actual encryption. the object must be initialized with a public key password prior. the input and output strings should be set to binary mode and the output string should have a pre-allocated buffer set to the appropriate size, big enough to recieve the output (see string_o's functions setmode_binary() and force_size()). The signiture of this API function is set in the base class and is common to all Z Directory encryptors.
TRAITS: this function redefines the base class [pure] virtual function
 

decrypt()
SIGNATURE: int decrypt (const string_o &sin, string_o &sot, size_t *nb)
SYNOPSIS:
does the actual decryption. this function is the converse of encrypt(). the object must be initialized with both public and private keys.
TRAITS: this function redefines the base class [pure] virtual function
 

set_generator()
SIGNATURE: int set_generator (int less, int more, int accuracy)
SYNOPSIS:
set parameters for keys generation. All variables must be positive integers and 'more' > 'less'. The default values of these are:
more: 11
less: 10
accuracy: 90
 

generate_keys()
SIGNATURE: int generate_keys (string_o &pubb, string_o &priv, int *pi = NULL)
SYNOPSIS: this function should be called just once, to initialize parameters in the 'pair crypt' system.
PARAMETERS

pi: [output] error indicator variable. Values:
0: success
zErr_Data_Unexpected: internal error in key generation

TRAITS: this function is static
 

key_looksgood()
SIGNATURE: boolean key_looksgood (const string_o &, int *, int *pi = NULL)
SYNOPSIS:
this tells if the string "s" looks like an RSA key, or if it looks like 2 RSA keys separated by a '#' or a ' ' (space character).
PARAMETERS

pi: [output] error indicator variable. Values:
0: all ok, format is good
1: bad input - empty string
2: string has letter, but not in [A..F]
3: string has illegal char (not hex, nor '#' or ' ')
4: too much whitespace (there can be only 1)
5: no '#' in input (falta string?)
6: 1 sharp, got space(s) - (huh?) syntax error
7: 2 sharps, but not exactly 1 space. expect 2 keys
8: 3 sharps, must be no spaces (0). expect 2 keys
9: panic, corruption in logic

TRAITS: this function is static
 

extract_pubkey()
SIGNATURE: string_o extract_pubkey (const string_o &s, int *pi = NULL)
SYNOPSIS:
given a string containing either 1 or 2 RSA keys, this gets the first key (the only key, if it has 1) and returns it, as a string.
PARAMETERS

• s: string containing either 1 or 2 RSA keys
• pi: [output] error indicator variable. Values:
  0: success
  zcrypERR_BADKEY: error in format of 's'

RETURNS: [string] contains the public key. it is empty ("") if an error ocurred
TRAITS: this function is static
 

extract_privkey()
SIGNATURE: string_o extract_privkey (const string_o &s, int *pi = NULL)
SYNOPSIS:
given a string containing 2 RSA keys, this gets the second key and returns it. the string must have 2 (both public and private) keys.
PARAMETERS

• s: string containing passwords
• pi: [output] error indicator variable. Values:
  0: success

TRAITS: this function is static
 

warnings.
There are rumors that the authors of RSA have been paid millions of dollars to construct a "back door" enabling American federal government agencies a method to decrypt RSA encryptions. Thus, Vettrasoft warns that this algorithm may be unsecure. We can neither confirm nor deny this; use with caution (you can of course encrypt the encryption with another algorithm, which we encourage).

From Wikipedia:
"The relationship [with the NSA] shifted from adversarial to cooperative after RSA president James Bidzos stepped down as CEO in 1999, according to Victor Chan, who led RSA's department engineering until 2005: 'When I joined there were 10 people in the labs, and we were fighting the NSA. It became a very different company later on... RSA was reported to have accepted $10 million from the NSA in 2004 in a deal to use the NSA-designed Dual_EC_DRBG ("Dual Elliptic Curve Deterministic Random Bit") random number generator in their BSAFE library."

Vettrasoft's pair crypt implementation dates to approximately 2000, and the default random number generation in this implementation of RSA has been replaced with Vettrasoft's own, so we believe the source code for pair crypt is probably safe, but it cannot be guaranteed.

examples.
Here is a simple example of encrypting, then decrypting a string using this algorithm.

    #include "z_crypt.h"
    #define TEST_STR "Was ist das, Damen und Herren? (-a short German phrase)"

    void main()
    {
        int ie0, ie1, ie2;
        string_o priv, pubb;

        RSA_crypt_o c1, c2;

        RSA_crypt_o::generate_keys (pubb, priv, &ie1);
        if (ie1)
            { std::cerr << "keys generated are wrong" << std::endl; return -1; }

        c1.set_keys (pubb, priv);
        c2.set_keys (pubb, priv);

        string_o encr, decr, orig = TEST_STR;
        size_t nb = orig.size();
        encr.setmode_binary();
        decr.setmode_binary();
        // encr.force_size(nb);
        decr.force_size(nb);

        ie0 = c1.encrypt (orig, encr, &nb);
        ie0 = c2.decrypt (encr, decr, &nb);

        std::cout << "original  \'" << orig << "\'" << std::endl;
        std::cout << "decrypted \'" << decr << "\'" << std::endl;

        if (decr.substring(0, orig.size() - 1) != orig)
            { std::cout << "error in encryption\n"; return -1; }

        exit(0);
        return 0;
    }

history.

??? 11/22/1988: original source code written
Tue 11/19/2002: incorporated into the "crypt" object
Wed 04/06/2011: de-activated from the z directory
Tue 04/12/2011: Z Directory randomizer installed
??? 01/06/2011: set_keys() - RSA private key made optional