class KMD5

 An adapted C++ implementation of RSA Data Securities MD5 algorithm. More...
Definition#include <kmdcodec.h>
List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

Public Types

Public Methods

Protected Methods

Detailed Description

This class provides an easy to use C++ implementation of the MD5 algorithm. It provides an easy way to use the class much like you would the plain C-implementations along with single shot constructors that automatically perform the update and call finalize.

The default constructor is intended to provide much the same functionality as the C-implementation while the other three constructors are used to perform quick digest calculations whenever the message to be does not require subsequent updating. Additionally, you can obtain either the result in a 16-byte binary format or 33-byte hexidecimal by invoking rawDigest and hexDigest respectivelly. The extra byte in the latter format is is a NULL character to terminate the string!

Useage:

The simplest way of using this class through one of the accessor methods: 


  HASH rawResult;
  HASHHEX hexResult;
  QByteArray array;
  QCString test1;

  test1 = "This is a simple test.";
  KMD5 context( test1 );
  context.rawDigest( rawResult );
  context.hexDigest( hexResult );
  printf ( "Raw Digest output: %s", rawResult );
  printf ( "Hex Digest output: %s", hexResult );

You can then invoke reset() to re-use the same class to perform another digest. This cuts down on the unnecessary overhead that would be generated from creating multiple KMD5 objects. 


  context.reset();
  context.update( QCString("TWO") );
  context.update( QCString("THREE") );
  printf ( "Raw Digest output: %s", static_cast<char*>(context.rawDigest()) );
  printf ( "Hex Digest output: %s", context.hexDigest() );

Once you invoke reset(), the previouly calculated digest value will be lost. Thus, be sure you copy the result if you need to use it again. Also, if you use one of the convienence constructors you must first invoke reset(), before calling any of the update functions. Otherwise, the update call will fail and return the already finalized error. As such if you need to update the message to be digested, it is hihgly recommended that you use the default constructor.

Another example much along the lines of how the c-implementation of this algorithm is usually used: 


  KMD5 context;
  context.update(QCString("ONE"));
  context.update(QCString("TWO"));
  context.update(QCString("THREE"));
  context.finalize();
  printf ( "Raw Digest output: %s", static_cast<char*>(context.rawDigest()) );
  printf ( "Hex Digest output: %s", context.hexDigest() );

enum DigestType {BIN, HEX }

HEX hexidecimal representation of the message digest BIN binary representation of the message digest

enum ErrorType {ERR_NONE, ERR_ALREADY_FINALIZED, ERR_NOT_YET_FINALIZED, ERR_CANNOT_READ_FILE, ERR_CANNOT_CLOSE_FILE }

ERR_NONE no error occured. [default] ERR_ALREADY_FINALIZED finalize() has already been invoked. ERR_NOT_YET_FINALIZED hexDigest() or rawDigest() invoked before finalize(). ERR_CANNOT_READ_FILE indicates a problem while trying to read the given file. ERR_CANNOT_CLOSE_FILE indicates a problem while trying to close the given file.

 KMD5 ()

Default constructor that only performs initialization. Unlike the other constructors

 KMD5 (Q_UINT8 * in)

Constructor that initializes, computes, and finalizes the message digest for the given string.

NOTE: This is a convience constructor. It is provided to allow compatiability with the C implementation of this digest.

 KMD5 (FILE *file)

Constructor that initializes, computes, and finalizes the message digest for the given file.

NOTE: This is a convience constructor. As such it does not allow the update of the message after it has been invoked. If you need to update the message after creating the constructor,

 KMD5 (const QByteArray& a )

Same as above except it accepts a QByteArray as its argument.

 KMD5 (const QCString& in)

Same as above except it accepts a QCString as its argument.

 KMD5 (const QString& in)

@deprcated. Use KMD5(const QCString& in) instead!

<u>IMPORTANT:</u> This constructor has been depricated and will be removed in future release. This is done to avoid loss of data from misuse of the function since it first converts the given data into Latin-1. Additionally, this conversion is very slow!

void  update (const QByteArray& in )

Updates the message to be digested.

Parameters:
inputmessage to be added to the digest (QByteArray).

void  update (FILE *file, bool closeFile = false )

Same as above except it accepts a pointer to FILE.

NOTE that the file must have been already opened. If you want the file to be automatically closed, set closeFile to TRUE.

Parameters:
filea pointer to FILE as returned by calls like f{d,re}open
closeFileif true closes the file using fclose.

void  update (Q_UINT8 * in, int len = -1 )

Updates the message to be digested.

Parameters:
inputmessage to be added to digest (unsigned char*)
lenthe length of the given message.

void  update ( const QCString& in )

Same as above except it accepts a QCString as its argument.

void  update ( const QString& in )

Same as above except it accepts a QString as its argument.

<u>IMPORTANT:</u> This function is ONLY provided for convenience and backward compatability! Using it can result in an incorrect digest caclculation since the conversion of the QString input to latin-1 can and will result in data loss if the input data contains non-latin1 characters. As such it is highly recommended that you avoid this function unless you are absolutely certain that your input does not contain any non-latin1 character!!

void  finalize ()

Finalizes the message digest calculation.

If you used the default constructor, you must invoke this function before you can obtain the calculated digest value.

bool  verify ( const QCString& in, const char * msg_digest, DigestType type = HEX )

Compares the message digest supplied messaged digest msg_digest with the one calculated for the input QCString input.

<u>NOTE:</u> Calling this function will reset any previously calcualted digests. If you want to verify your token with the current digest value, use verify( const char*, DigestType ) instead.

Parameters:
inputthe message to be added to the digest value
msg_digestthe digest to compare the result against
typethe format of the result for comparison (binary or hexidecimal).

Returns: true if the digests match, otherwise false.

bool  verify ( const QString& in, const char * msg_digest, DigestType type = HEX )

Same as above except it takes a QString argument as its input.

<u>IMPORTANT:</u> This function is ONLY provided for convenience and backward compatability! Using it can result in an incorrect verification since the conversion of the QString input to latin-1 can and will result in data loss if the input data contains non- latin1 characters. As such it is highly recommended that you avoid this function unless you are absolutely certain that your input does not contain any non-latin1 character!!

bool  verify ( FILE* f, const char * msg_digest, DigestType type = HEX )

Same as above except it takes a pointer to a FILE as its input.

<u>NOTE:</u> Calling this function will reset any previously calcualted digests. If you want to verify your token with the current digest value, use verify(const char*, DigestType) instead.

bool  verify ( const char* msg_digest, DigestType type = HEX )

Compares the given string with with the current message digest.

Unlike the other verification functions this one does not reset the calculated message digest if one is already present. Rather it simply compares the given digest value against the calculated one.

<u>NOTE:</u> This function will return false if there was an error calculating the message digest as well as when the verification fails. You can use hasErrored() to determine which is the case.

Parameters:
msg_digestthe digest to compare the result against
typethe format of the result for comparison (binary or hexidecimal).

Returns: true if the digests match, otherwise false.

void  reset ()

Re-initializes internal paramters.

Note that calling this function will reset all internal variables and hence any calculated digest. Invoke this function only when you have to re-use the same object to perform another message digest calculation.

Q_UINT8*  rawDigest ()

Returns the raw 16-byte binary value of the message digest.

NOTE: you are responsible for making a copy of this string.

Returns: the raw represenation of the digest or NULL if there was error calculating the digest.

void  rawDigest ( HASH bin )

Fills the given array with the binary representation of the message digest.

Use this method if you do not want to worry about making copy of the digest once you obtain it.

Parameters:
binan array of 16 characters ( char[16] )

char *  hexDigest ()

Returns the value of the calculated message digest in a hexcidecimal representation.

The 32-byte hexidecimal value is terminated by a NULL character to form a properly terminated string. Also note that that if

<u>NOTE:</u> You are responsible for making a copy of this string!

Returns: the hex represenation of the digest or NULL if there was error calculating the digest.

void  hexDigest ( HASHHEX hex )

Fills the given array with the hexcidecimal representation of the message digest.

Use this method if you do not want to worry about making copy of the digest once you obtain it. Also note that this method appends a NULL charater to the end of the array to form a properly terminated string.

Parameters:
binan array of 33 characters ( char[33] )

bool  hasErrored ()

[const]

Indicates whether the message digest calculation failed or succeeded. Use error() to determine the error type.

Returns: false if errors are present, otherwise true

int  error ()

[const]

Returns the type of error that occurred.

Returns: the error type. See ErrorType for details.

void  init ()

[protected]

Initializer called by all constructors

void  transform ( Q_UINT8 * buffer )

[protected]

Performs the real update work. Note that length is implied to be 64.

bool  isDigestMatch ( const char * msg_digest, DigestType type )

[protected]

Returns true if the current message digest matches msg_digest.