Version: 3.1.1
wxSecretValue Class Reference

#include <wx/secretstore.h>

Detailed Description

Represents the value of a secret in wxSecretStore.

Immutable value-like class which tries to ensure that the secret value will be removed once it's not needed any more.

Library:  wxBase
Category:  Miscellaneous
Since
3.1.1

Public Member Functions

 wxSecretValue ()
 Creates an empty secret value (not the same as an empty password). More...
 
 wxSecretValue (size_t size, const void *data)
 Creates a secret value from the given data. More...
 
 wxSecretValue (const wxString &secret)
 Creates a secret value from the given string. More...
 
 wxSecretValue (const wxSecretValue &other)
 Creates a copy of an existing secret. More...
 
wxSecretValueoperator= (const wxSecretValue &other)
 Assigns another secret to this one. More...
 
 ~wxSecretValue ()
 Wipes out the secret value from memory before destroying the object. More...
 
bool IsOk () const
 Check if a secret is not empty. More...
 
bool operator== (const wxSecretValue &other) const
 Compare with another secret for equality. More...
 
bool operator!= (const wxSecretValue &other) const
 Compare with another secret for inequality. More...
 
size_t GetSize () const
 Get the size, in bytes, of the secret data. More...
 
const void * GetData () const
 Get read-only access to the secret data. More...
 
wxString GetAsString (const wxMBConv &conv=wxConvWhateverWorks) const
 Get the secret data as a string. More...
 

Static Public Member Functions

static void Wipe (size_t size, void *data)
 Erase the given area of memory overwriting its presumably sensitive content. More...
 
static void WipeString (wxString &str)
 Overwrite the contents of the given string. More...
 

Constructor & Destructor Documentation

wxSecretValue::wxSecretValue ( )

Creates an empty secret value (not the same as an empty password).

wxSecretValue::wxSecretValue ( size_t  size,
const void *  data 
)

Creates a secret value from the given data.

The data argument may contain NUL bytes and doesn't need to be NUL-terminated.

Notice that at least under MSW the maximal size of the secret is limited. The exact limit depends on the OS version and is e.g. 2560 for Windows 7.

wxSecretValue::wxSecretValue ( const wxString secret)
explicit

Creates a secret value from the given string.

The secret argument may contain NUL bytes.

The secret value will stored serialized in UTF-8 encoding.

wxSecretValue::wxSecretValue ( const wxSecretValue other)

Creates a copy of an existing secret.

wxSecretValue::~wxSecretValue ( )

Wipes out the secret value from memory before destroying the object.

This method doesn't provide any real security guarantee, but it does reduce the likelihood that secret value is leaked if the program crashes and ends in a core or a minidump file, for example.

See Wipe() method if you need to overwrite another region of memory where the secret was copied to or from.

Member Function Documentation

wxString wxSecretValue::GetAsString ( const wxMBConv conv = wxConvWhateverWorks) const

Get the secret data as a string.

This is a more convenient but less secure alternative to using GetSize() and GetData(), as this function creates another copy of a secret which won't be wiped when this object is destroyed and you will need to call WipeString() to overwrite the content of the returned string, as well all its copies, if any, manually to avoid the secret being left in memory.

This function uses the specified conv object to convert binary secret data to string form. As the secret data may have been created by external programs not using wxWidgets API, it may be not a valid UTF-8-encoded string, so by default wxConvWhateverWorks, which tries to interpret it in any way not avoiding loss of data, is used. However if the secrets are only saved by the program itself and are known to be always encoded in UTF-8, it may be better to pass ::wxConvUTF8 as the converter to use.

const void* wxSecretValue::GetData ( ) const

Get read-only access to the secret data.

Don't assume it is NUL-terminated, use GetSize() instead.

See also
GetAsString()
size_t wxSecretValue::GetSize ( ) const

Get the size, in bytes, of the secret data.

May return 0.

See also
GetData()
bool wxSecretValue::IsOk ( ) const

Check if a secret is not empty.

bool wxSecretValue::operator!= ( const wxSecretValue other) const

Compare with another secret for inequality.

wxSecretValue& wxSecretValue::operator= ( const wxSecretValue other)

Assigns another secret to this one.

bool wxSecretValue::operator== ( const wxSecretValue other) const

Compare with another secret for equality.

static void wxSecretValue::Wipe ( size_t  size,
void *  data 
)
static

Erase the given area of memory overwriting its presumably sensitive content.

static void wxSecretValue::WipeString ( wxString str)
static

Overwrite the contents of the given string.