#include <safe_string.h>

Public Member Functions
	SafeString (IKeyProvider *keyProvider=nullptr, const String &str=String(), bool cryptic=true)

	SafeString (const SafeString &copytron)

virtual	~SafeString ()
	Will IKeyProvider::deregister if a key provider is available.

SafeString &	operator= (const SafeString &copytron)

SafeString &	operator= (const String &str)

SafeString &	operator= (const char *str)

int	compare (const SafeString &rhs) const

bool	cryptic () const

void	setCryptic (bool val)

IKeyProvider *	keyProvider () const

void	setKeyProvider (IKeyProvider *provider)

const unsigned char *	iv () const

void	setIv (unsigned char *iv)

void	resetIv ()

bool	stateless () const

void	setStateless (bool val)

size_t	length () const

String	text () const

size_t	text (char *bufferOut) const

void	setText (const String &str=String())

void	setText (const char *str, size_t len)

void	setText (const String &str, bool cryptic)

void	setText (const char *str, size_t len, bool cryptic)

void	clear ()

Static Public Member Functions
static int	encrypt (const String &plainText, const unsigned char key[32], const unsigned char iv[16], unsigned char tagOut[16], unsigned char *bufferOut)

static int	encrypt (const char plain, size_t plainLen, const unsigned char key[32], const unsigned char iv[16], unsigned char tagOut[16], unsigned char bufferOut)

static String	decrypt (const unsigned char *encrypted, int encryptedLength, const unsigned char key[32], const unsigned char iv[16], const unsigned char tag[])

static size_t	decrypt (const unsigned char encrypted, int encryptedLength, const unsigned char key[32], const unsigned char iv[16], const unsigned char tag[], char bufferOut)

static void	randomize (unsigned char *bufferOut, int bufferSize)

static void	sha (const String &text, unsigned char bufferOut[32])

static void	sha (const char *text, size_t textLen, unsigned char bufferOut[32])

static void	initialize ()

static void	deinitialize ()

static void	generateKey (unsigned char keyOut[32])

static void	initializer (unsigned char ivOut[16])

Detailed Description

A string that can be encrypted in memory

Definition at line 65 of file safe_string.h.

Constructor & Destructor Documentation

§ SafeString()

mcr::SafeString::SafeString	(	IKeyProvider *	keyProvider = `nullptr`,
		const String &	str = `String()`,
		bool	cryptic = `true`
	)

inline

Parameters

keyProvider	opt Provider of encryption keys. If null then encryption is not possible and text will remain plain text.
str	opt Initial text
cryptic	opt Initial encryption state

Definition at line 73 of file safe_string.h.

Member Function Documentation

§ clear()

void mcr::SafeString::clear ( )

Clear all strings, allocated data, and tag. iv will not be changed.

§ compare()

int mcr::SafeString::compare ( const SafeString & rhs ) const

Compare cryptic and strcmp plain text

§ cryptic()

bool mcr::SafeString::cryptic ( ) const

inline

True for encrypted, otherwise plain text

Definition at line 236 of file safe_string.h.

§ decrypt() [1/2]

static String mcr::SafeString::decrypt	(	const unsigned char *	encrypted,
		int	encryptedLength,
		const unsigned char	key[32],
		const unsigned char	iv[16],
		const unsigned char	tag[]
	)

inlinestatic

Encrypted text => plain text

Parameters

encrypted	Encrypted bytes to decrypt as a string
encryptedLength	Bytes to decrypt from encrypted string
key	Encryption key, randomized bytes or hashed password
iv	opt Initializer that should not be shared between texts encrypted with the same key.
tag	opt A paired value will write to this buffer, required for encryption state and added security. Set to null for stateless encryption.

Returns: Decrypted string

Definition at line 151 of file safe_string.h.

§ decrypt() [2/2]

static size_t mcr::SafeString::decrypt	(	const unsigned char *	encrypted,
		int	encryptedLength,
		const unsigned char	key[32],
		const unsigned char	iv[16],
		const unsigned char	tag[],
		char *	bufferOut
	)

static

mcr_platform Encrypted text => plain text

This is usually defined in the ssl directory. Redefine if not linking to a libcrypto- or libssl-compatible library.

Returns: Length of decrypted bytes written to bufferOut.

§ deinitialize()

static void mcr::SafeString::deinitialize ( )

static

mcr_platform This is called in library cleanup

This is usually defined in the ssl directory. Redefine if not linking to a libcrypto- or libssl-compatible library.

§ encrypt() [1/2]

static int mcr::SafeString::encrypt	(	const String &	plainText,
		const unsigned char	key[32],
		const unsigned char	iv[16],
		unsigned char	tagOut[16],
		unsigned char *	bufferOut
	)

inlinestatic

Plain text => encrypted text

Parameters

plainText	String to be encrypted
key	Encryption key, randomized bytes or hashed password
iv	opt Initializer that should not be shared between texts encrypted with the same key.
tagOut	opt A paired value will write to this buffer, required for encryption state and added security. Set to null for stateless encryption.
bufferOut	Buffer to hold encrypted bytes. Encrypted text can be greater than plain text length. To be safe the byte length of this buffer should be at least 1.5 times the plain text string length.

Returns: Length of encrypted bytes written to bufferOut. Will be -1 for any errors.

Definition at line 122 of file safe_string.h.

§ encrypt() [2/2]

static int mcr::SafeString::encrypt	(	const char *	plain,
		size_t	plainLen,
		const unsigned char	key[32],
		const unsigned char	iv[16],
		unsigned char	tagOut[16],
		unsigned char *	bufferOut
	)

static

mcr_platform Plain text => encrypted text

This is usually defined in the ssl directory. Redefine if not linking to a libcrypto- or libssl-compatible library.

Returns: Length of encrypted bytes written to bufferOut. Will be -1 for any errors.

§ generateKey()

static void mcr::SafeString::generateKey ( unsigned char keyOut[32] )

inlinestatic

Use randomize to generate a key

Parameters

keyOut Byte array to use as an encryption key.

Definition at line 218 of file safe_string.h.

§ initialize()

static void mcr::SafeString::initialize ( )

static

mcr_platform This is called in library initialization

This is usually defined in the ssl directory. Redefine if not linking to a libcrypto- or libssl-compatible library.

§ initializer()

static void mcr::SafeString::initializer ( unsigned char ivOut[16] )

inlinestatic

Use randomize to generate an iv

Parameters

ivOut Byte array to write iv to

Definition at line 226 of file safe_string.h.

§ iv()

const unsigned char* mcr::SafeString::iv ( ) const

inline

Initialization vector, added security for encryption

Definition at line 258 of file safe_string.h.

§ keyProvider()

IKeyProvider* mcr::SafeString::keyProvider ( ) const

inline

Get encryption keys from this object

Definition at line 248 of file safe_string.h.

§ length()

size_t mcr::SafeString::length ( ) const

inline

Byte length of plain text string, such as strlen

Definition at line 287 of file safe_string.h.

§ randomize()

static void mcr::SafeString::randomize	(	unsigned char *	bufferOut,
		int	bufferSize
	)

static

mcr_platform Output pseudo randomized bytes

This is usually defined in the ssl directory. Redefine if not linking to a libcrypto- or libssl-compatible library.

Parameters

bufferOut	Write bytes to this buffer
bufferSize	Number of bytes to write to output buffer

§ resetIv()

void mcr::SafeString::resetIv ( )

Randomize iv

Current text will be preserved

§ setCryptic()

void mcr::SafeString::setCryptic ( bool val )

Set encryption state

If key provider is not available encryption state will always be false. Current text will be preserved

§ setIv()

void mcr::SafeString::setIv ( unsigned char * iv )

Set initialization vector

Current text will be preserved

§ setKeyProvider()

void mcr::SafeString::setKeyProvider ( IKeyProvider * provider )

Set encryption key provider

Current text will be preserved

§ setStateless()

void mcr::SafeString::setStateless ( bool val )

Set stateless ability of this string

Current text will be preserved

§ setText() [1/4]

void mcr::SafeString::setText ( const String & str = String() )

inline

Set string plain text, and will encrypt if currently encrypting

Definition at line 311 of file safe_string.h.

§ setText() [2/4]

void mcr::SafeString::setText	(	const char *	str,
		size_t	len
	)

Set string plain text, and will encrypt if currently encrypting

Parameters

len	strlen of string, or -1 for entire string

§ setText() [3/4]

void mcr::SafeString::setText	(	const String &	str,
		bool	cryptic
	)

inline

Set string plain text

Parameters

cryptic setCryptic

Definition at line 324 of file safe_string.h.

§ setText() [4/4]

void mcr::SafeString::setText	(	const char *	str,
		size_t	len,
		bool	cryptic
	)

Set string plain text

Parameters

cryptic setCryptic

§ sha() [1/2]

static void mcr::SafeString::sha	(	const String &	text,
		unsigned char	bufferOut[32]
	)

inlinestatic

Create a SHA hash suitable to use as an encryption key

Parameters

text	Plain text to compute hash for
bufferOut	Write hash to this buffer

Definition at line 191 of file safe_string.h.

§ sha() [2/2]

static void mcr::SafeString::sha	(	const char *	text,
		size_t	textLen,
		unsigned char	bufferOut[32]
	)

static

mcr_platform Create a SHA hash suitable to use as an encryption key

This is usually defined in the ssl directory. Redefine if not linking to a libcrypto- or libssl-compatible library.

§ stateless()

bool mcr::SafeString::stateless ( ) const

inline

A stateless string can always be decrypted to the same value, as long as the key and iv are the same. Tag is not used, or ignored.

Definition at line 276 of file safe_string.h.

§ text() [1/2]

String mcr::SafeString::text ( ) const

inline

Get string as plain text

Definition at line 292 of file safe_string.h.

§ text() [2/2]

size_t mcr::SafeString::text ( char * bufferOut ) const

Get string as plain text

Parameters

bufferOut Buffer to write plain text, must be at least length + 1 in byte size

Returns: String length of plain text

The documentation for this class was generated from the following file:

mcr/extras/safe_string.h

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

§ SafeString()

Member Function Documentation

§ clear()

§ compare()

§ cryptic()

§ decrypt() [1/2]

§ decrypt() [2/2]

§ deinitialize()

§ encrypt() [1/2]

§ encrypt() [2/2]

§ generateKey()

§ initialize()

§ initializer()

§ iv()

§ keyProvider()

§ length()

§ randomize()

§ resetIv()

§ setCryptic()

§ setIv()

§ setKeyProvider()

§ setStateless()

§ setText() [1/4]

§ setText() [2/4]

§ setText() [3/4]

§ setText() [4/4]

§ sha() [1/2]

§ sha() [2/2]

§ stateless()

§ text() [1/2]

§ text() [2/2]