class KMD5

Public Types

• enum DigestType { BIN, HEX }
• enum ErrorType { ERR_NONE, ERR_ALREADY_FINALIZED, ERR_NOT_YET_FINALIZED, ERR_CANNOT_READ_FILE, ERR_CANNOT_CLOSE_FILE }

Public Methods

•  KMD5 ()
•  KMD5 (Q_UINT8 * in)
•  KMD5 (FILE *file)
•  KMD5 (const QByteArray& a )
•  KMD5 (const QCString& in)
•  KMD5 (const QString& in)
• void  update (const QByteArray& in )
• void  update (FILE *file, bool closeFile = false )
• void  update (Q_UINT8 * in, int len = -1 )
• void  update ( const QCString& in )
• void  update ( const QString& in )
• void  finalize ()
• bool  verify ( const QCString& in, const char * msg_digest, DigestType type = HEX )
• bool  verify ( const QString& in, const char * msg_digest, DigestType type = HEX )
• bool  verify ( FILE* f, const char * msg_digest, DigestType type = HEX )
• bool  verify ( const char* msg_digest, DigestType type = HEX )
• void  reset ()
• Q_UINT8*  rawDigest ()
• void  rawDigest ( HASH bin )
• char *  hexDigest ()
• void  hexDigest ( HASHHEX hex )
• bool  hasErrored () const
• int  error () const

Protected Methods

• void  init ()
• void  transform ( Q_UINT8 * buffer )
• bool  isDigestMatch ( const char * msg_digest, DigestType type )

Detailed Description

Provides an easy to use C++ implementation of RSA's MD5 algorithm.

The default constructor is designed to provide much the same functionality as the most commonly used C-implementation while the other three constructors are meant to further simplify the message digest calculations by calculating the result in one single step. Additionally, you have the ability to obtain the result in either raw (16-bytes) or hexidecimal formats (33-bytes) using rawDigest and hexDigest respectivelly, you can also reuse a single instance to make multiple message digest calculations by simply invoking @reset().

Useage:

A common useage of this class:

  HASH rawResult;
  HASHHEX hexResult;
  QCString 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 );

To cut down on the unnecessary overhead of creating multiple KMD5 objects, you can simply invoke reset() to resue the same object in making another calculation:

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

NOTE: Invoke reset() deletes the previously calculated message digest value. Thus, be sure to copy the previous result before you reuse the same object! Also, if you use one of the convienence constructors you must first invoke reset(), before calling any of the update functions. Otherwise, the call to update will fail.

Here is an of KMD5 useage much along the same lines of how one would use the commonly available C-implementations of the MD5 algorithm:

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

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

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.

Default constructor that only performs initialization. Unlike the other constructors

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.

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,

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

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

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

IMPORTANT: 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!

Updates the message to be digested.

Parameters:

input

message to be added to the digest (QByteArray).

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:

file	a pointer to FILE as returned by calls like f{d,re}open
closeFile	if true closes the file using fclose.

Updates the message to be digested.

Parameters:

input	message to be added to digest (unsigned char*)
len	the length of the given message.

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

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

IMPORTANT: 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!!

Finalizes the message digest calculation.

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

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

NOTE: 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:

input	the message to be added to the digest value
msg_digest	the digest to compare the result against
type	the format of the result for comparison (binary or hexidecimal).

Returns: true if the digests match, otherwise false.

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

IMPORTANT: 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!!

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

NOTE: 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.

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.

NOTE: 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_digest	the digest to compare the result against
type	the format of the result for comparison (binary or hexidecimal).

Returns: true if the digests match, otherwise false.

Re-initializes internal paramters.

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

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.

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:

bin	an array of 16 characters ( char[16] )

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

NOTE: 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.

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. This is the reason why the hexDigest is 33 characters long.

Parameters:

bin	an array of 33 characters ( char[33] )

[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

[const]

Returns the type of error that occurred.

Returns: the error type. See ErrorType for details.

[protected]

Initializer called by all constructors

[protected]

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

[protected]

Returns true if the current message digest matches msg_digest.

• Author: Dawit Alemayehu
• Generated: dfaure on kde.faure.org on Thu Jan 17 22:15:01 2002, using kdoc 2.0a53.