windows-server-2003/admin/burnslib/inc/encryptedstring.hpp

// Copyright (c) 2002 Microsoft Corporation
// 
// Encrypted string class
// 
// 18 March 2002 



#ifndef ENCRYPTEDSTRING_HPP_INCLUDED
#define ENCRYPTEDSTRING_HPP_INCLUDED



// A class that has a similar public interface as class Burnslib::String, but
// is represented as an encrypted blob, produced by CryptProtectMemory.
// 
// This class can be used to represent sensitive data like password strings
// in-memory, instead of holding them as cleartext, which is a security hole
// if the memory pages are swapped to disk, the machine is hibernated, etc.
// 
// You should convert any cleartext data into an instance of this class, then
// scribble out your cleartext source copy with SecureZeroMemory.

class EncryptedString
{
   public:

   // no string may be longer than this many characters, not including the
   // terminating null, or it will be truncated.
   
   static const size_t MAX_CHARACTER_COUNT = 1024 * 2 - 1;


   
   // constructs an empty string.

   explicit
   EncryptedString();


   
   // constructs a copy of an existing, already encoded string

   EncryptedString(const EncryptedString& rhs);



   // scribbles out the text, and deletes it.
   
   ~EncryptedString()
   {
      // when the object dies, it had better not have any outstanding
      // cleartext copies.
      
      ASSERT(cleartextCopyCount == 0);
      
      Reset();
   }



   // disposes of the encrypted text, and sets the string to be empty.
   
   void
   Clear()
   {
      // when the object dies, it had better not have any outstanding
      // cleartext copies.
      
      ASSERT(cleartextCopyCount == 0);

      Reset();
   }


   // Scribbles out and de-allocates a clear text copy of the string. The
   // caller is required to balance each call to GetClearTextCopy with a call
   // to DestroyClearTextCopy lest he leak memory and leave cleartext hanging
   // around.
   // 
   // cleartext - the same pointer returned by a previous call to
   // GetClearTextCopy on the same instance.
   
   void
   DestroyClearTextCopy(WCHAR* cleartext) const;

   

   // thrown by GetClearTextCopy if decryption fails.
   
   class DecryptionFailureException
   {
      public:

      DecryptionFailureException()
      {
      }
   };

   
         
   // Extracts the decoded cleartext representation of the text, including
   // null terminator.  The caller must invoke DestroyClearTextCopy on the
   // result, even if the result is null.
   //
   // Throws a DecryptionFailureException on failure.
   //
   // Example:
   // WCHAR* cleartext = encoded.GetDecodedCopy();
   // if (cleartext)
   // {
   //    // ... use the cleartext
   // }
   // encoded.DestroyClearTextCopy();
   
   WCHAR* 
   GetClearTextCopy() const;


   
   // Returns true if the string is zero-length, false if not.
   
   bool
   IsEmpty() const
   {
      return (GetLength() == 0);
   }



   // Sets the contents of self to the encoded representation of the
   // cleartext, replacing the previous value of self.  The encoded
   // representation will be the same length, in characters, as the
   // cleartext.
   //
   // clearText - in, un-encoded text to be encoded.  May be empty string,
   // but not a null pointer.
   
   void
   Encrypt(const WCHAR* cleartext);
      

   
   // Returns the length, in unicode characters, of the cleartext, not
   // including the null terminator.

   size_t
   GetLength() const;


   
   // Replaces the contents of self with a copy of the contents of rhs.
   // Returns *this.
   
   const EncryptedString&
   operator= (const EncryptedString& rhs);



   // Compares the cleartext representations of self and rhs, and returns
   // true if they are lexicographically the same: the lengths are the same
   // and all the characters are the same.
      
   bool
   operator== (const EncryptedString& rhs) const;



   bool
   operator!= (const EncryptedString& rhs) const
   {
      return !(operator==(rhs));
   }
   

   
   private:

   
   void
   Clone(const EncryptedString& rhs);

   void
   Init(const WCHAR* clearText);

   WCHAR*
   InternalDecrypt() const;
   
   void
   InternalDestroy(WCHAR* cleartext) const;
   
   void
   Reset();

   
      
   // We deliberately do not implement conversion to or from WCHAR* or
   // String.  This is to force the user of the class to be very deliberate
   // about decoding the string.  class String is a copy-on-write shared
   // reference implementation, and we don't want to make it easy to create
   // "hidden" copies of cleartext, or move from one representation to
   // another, or accidentally get a string filled with encrypted text.

   // deliberately commented out
   // explicit
   // EncryptedString(const String& cleartext);

   // deliberately commented out
   // operator WCHAR* ();
   // operator String ();



   size_t clearTextLength;
   
   // In the course of en[de]crypting, and assigning to the instance, we
   // may reallocate the memory pointed to here, but logically the string
   // is still "const"   

   mutable WCHAR* cypherText;
   
   // a logically const instance may have cleartext copies made

   mutable int cleartextCopyCount;

   // indicates that the encryption worked.
   
   bool isEncrypted;
};



#endif   // ENCRYPTEDSTRING_HPP_INCLUDED