Disk ARchive: libdar::secu_string Class Reference

| Disk ARchive 2.8.1 Full featured and portable backup and archiving tool

Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | Private Member Functions | Private Attributes | List of all members
libdar::secu_string Class Reference
API

class secu_string More...

`#include <secu_string.hpp>`

## Public Member Functions
| secu_string (U_I storage_size=0)
| constructor 1
| secu_string (const char *ptr, U_I size)
| constructor 2
| secu_string (const secu_string &ref)
| the copy constructor
| secu_string (secu_string &&ref) noexcept
| the move constructor
secu_string & | operator= (const secu_string &ref)
| the assignment operator
secu_string & | operator= (secu_string &&ref) noexcept
| the move operator
| ~secu_string () noexcept
| the destructor (set memory to zero before releasing it)
bool | operator!= (const std::string &ref) const
bool | operator!= (const secu_string &ref) const
bool | operator== (const std::string &ref) const
bool | operator== (const secu_string &ref) const
void | set (int fd, U_I size)
| fill the object with data
void | append_at (U_I offset, const char *ptr, U_I size)
| append some data to the string at a given offset
void | append_at (U_I offset, int fd, U_I size)
| append some data to the string
void | append (const char *ptr, U_I size)
| append some data at the end of the string
void | append (int fd, U_I size)
| append some data at the end of the string
void | reduce_string_size_to (U_I pos)
void | expand_string_size_to (U_I size)
| set the string size within the allocated secure memory
void | clear ()
| clear the string (set to an empty string)
void | resize (U_I size)
| clear and resize the string to the defined allocated size
void | randomize (U_I size)
| set the string to randomize string of given size
const char * | c_str () const
| get access to the secure string
char * | c_str ()
void | set_size (U_I size)
char * | get_array ()
| non constant flavor of direct secure memory access
char & | operator[] (U_I index)
| get access to the secure string by index
char | operator[] (U_I index) const
U_I | get_size () const
| get the size of the string
bool | empty () const
| tell whether string is empty
U_I | get_allocated_size () const
| get the size of the allocated secure space

## Static Public Member Functions
static bool | is_string_secured ()
| to know if secure memory is available

## Private Member Functions
void | nullifyptr () noexcept
void | init (U_I size)
| to be used at creation time or after clean_and_destroy() only
void | copy_from (const secu_string &ref)
| to be used at creation time or after clean_and_destroy() only
void | move_from (secu_string &&ref) noexcept
bool | compare_with (const char *ptr, U_I size) const
void | clean_and_destroy ()

## Private Attributes
bool | zero_length
| true if none of the other field are set due to zero byte length string requested
U_I * | allocated_size
| stores the allocated size of the secu_string
char * | mem
| pointer to allocated block of data
U_I * | string_size
| stores the string info size in the secu string (*string_size < *allocated_size)

## Detailed Description

class secu_string

it manages the allocation/release of a given size block of memory the memory block is forbidden to be swapped (if is_strin_secured() is true) and is zeroed before being released

Definition at line 53 of file secu_string.hpp.

## Constructor & Destructor Documentation

## ◆ secu_string() [1/4]

libdar::secu_string::secu_string | ( | U_I | storage_size = 0 | ) |
| inline

constructor 1

create the allocated string in secure memory

Parameters

  [in] | storage_size | is the amount of secured memory to obtain when creating the object

Definition at line 68 of file secu_string.hpp.

References init().

Referenced by copy_from(), operator=(), operator=(), operator[](), secu_string(), and secu_string().

## ◆ secu_string() [2/4]

libdar::secu_string::secu_string | ( | const char * | ptr,
|  | U_I | size )
| inline

constructor 2

create the string from a pointer to a (secure) string or from a portion of it

Definition at line 73 of file secu_string.hpp.

References append_at(), and init().

## ◆ secu_string() [3/4]

libdar::secu_string::secu_string | ( | const secu_string & | ref | ) |
| inline

the copy constructor

Definition at line 76 of file secu_string.hpp.

References copy_from(), and secu_string().

## ◆ secu_string() [4/4]

libdar::secu_string::secu_string | ( | secu_string && | ref | ) |
| inlinenoexcept

the move constructor

Definition at line 79 of file secu_string.hpp.

References secu_string().

## ◆ ~secu_string()

libdar::secu_string::~secu_string | ( |  | ) |
| inlinenoexcept

the destructor (set memory to zero before releasing it)

Definition at line 88 of file secu_string.hpp.

## Member Function Documentation

## ◆ append() [1/2]

void libdar::secu_string::append | ( | const char * | ptr,
|  | U_I | size )
| inline

append some data at the end of the string

Definition at line 121 of file secu_string.hpp.

References append_at(), and get_size().

## ◆ append() [2/2]

void libdar::secu_string::append | ( | int | fd,
|  | U_I | size )
| inline

append some data at the end of the string

Definition at line 124 of file secu_string.hpp.

References append_at(), and get_size().

## ◆ append_at()

void libdar::secu_string::append_at | ( | U_I | offset,
|  | const char * | ptr,
|  | U_I | size )

append some data to the string at a given offset

Parameters

  [in] | offset | defines at which offset in the secu_string will be placed the string to append
  [in] | ptr | is the address of the string to append
  [in] | size | is the number of byte to append

Note
  this call does not change the allocation size, (unlike set()), it adds the data pointed by the arguments to the object while there is enough place to do so. resize() must be used first to define enough secure memory to append the expected amount of data in one or several call to append.

Referenced by append(), append(), and secu_string().

## ◆ c_str() [1/2]

char * libdar::secu_string::c_str | ( |  | ) |
| inline

Definition at line 153 of file secu_string.hpp.

## ◆ c_str() [2/2]

const char * libdar::secu_string::c_str | ( |  | ) | const
| inline

get access to the secure string

Returns
  the address of the first byte of the string

Note
  check the "size" method to know how much bytes can be read

Definition at line 152 of file secu_string.hpp.

References mem, and zero_length.

## ◆ clear()

void libdar::secu_string::clear | ( |  | ) |
| inline

clear the string (set to an empty string)

Definition at line 136 of file secu_string.hpp.

References string_size, and zero_length.

## ◆ empty()

bool libdar::secu_string::empty | ( |  | ) | const
| inline

tell whether string is empty

Definition at line 169 of file secu_string.hpp.

References string_size, and zero_length.

## ◆ get_allocated_size()

U_I libdar::secu_string::get_allocated_size | ( |  | ) | const
| inline

get the size of the allocated secure space

Definition at line 172 of file secu_string.hpp.

References allocated_size, and zero_length.

## ◆ get_size()

U_I libdar::secu_string::get_size | ( |  | ) | const
| inline

get the size of the string

Definition at line 166 of file secu_string.hpp.

References string_size, and zero_length.

Referenced by append(), and append().

## ◆ is_string_secured()

bool libdar::secu_string::is_string_secured | ( |  | ) |
| static

to know if secure memory is available

it is advised that the user program of class secu_string uses this call before using objects of that class and if returned false, advise the user that the necessary support for secure memory is not present, that any sensitive data may be swapped out under heavy memory load and thus may lead secure password to be wrote to disk in clear.

## ◆ nullifyptr()

void libdar::secu_string::nullifyptr | ( |  | ) |
| inlineprivatenoexcept

Definition at line 180 of file secu_string.hpp.

## ◆ operator!=() [1/2]

bool libdar::secu_string::operator!= | ( | const secu_string & | ref | ) | const
| inline

Definition at line 92 of file secu_string.hpp.

## ◆ operator!=() [2/2]

bool libdar::secu_string::operator!= | ( | const std::string & | ref | ) | const
| inline

Definition at line 91 of file secu_string.hpp.

## ◆ operator=() [1/2]

secu_string & libdar::secu_string::operator= | ( | const secu_string & | ref | ) |
| inline

the assignment operator

Definition at line 82 of file secu_string.hpp.

References copy_from(), and secu_string().

## ◆ operator=() [2/2]

secu_string & libdar::secu_string::operator= | ( | secu_string && | ref | ) |
| inlinenoexcept

the move operator

Definition at line 85 of file secu_string.hpp.

References secu_string().

## ◆ operator[]() [1/2]

char & libdar::secu_string::operator[] | ( | U_I | index | ) |

get access to the secure string by index

Note
  index must be in the range [ 0 - size() [ to avoid throwing an exception

References secu_string().

## ◆ operator[]() [2/2]

char libdar::secu_string::operator[] | ( | U_I | index | ) | const
| inline

Definition at line 163 of file secu_string.hpp.

## ◆ randomize()

void libdar::secu_string::randomize | ( | U_I | size | ) |

set the string to randomize string of given size

Note
  the given size must be less than allocated size

## ◆ reduce_string_size_to()

void libdar::secu_string::reduce_string_size_to | ( | U_I | pos | ) |

shorten the string (do not change the allocated size)

Parameters

  [in] | pos | is the length of the string to set, it must be smaller or equal to the current size

## ◆ resize()

void libdar::secu_string::resize | ( | U_I | size | ) |
| inline

clear and resize the string to the defined allocated size

Parameters

  [in] | size | is the amount of secure memory to allocated

Definition at line 141 of file secu_string.hpp.

References init().

## ◆ set()

void libdar::secu_string::set | ( | int | fd,
|  | U_I | size )

fill the object with data

set at most size bytes of data directly from the filedescriptor,

Parameters

  [in] | fd | the filedescriptor to read data from
  [in] | size | is the maximum number of byte read

Note
  if current storage size is not larg enough to hold size bytes, allocated secure memory is released and larger allocation of secure memory is done.

## Member Data Documentation

## ◆ allocated_size

U_I* libdar::secu_string::allocated_size
| private

stores the allocated size of the secu_string

Definition at line 176 of file secu_string.hpp.

Referenced by get_allocated_size().

## ◆ mem

char* libdar::secu_string::mem
| private

pointer to allocated block of data

Definition at line 177 of file secu_string.hpp.

Referenced by c_str().

## ◆ string_size

U_I* libdar::secu_string::string_size
| private

stores the string info size in the secu string (*string_size < *allocated_size)

Definition at line 178 of file secu_string.hpp.

Referenced by clear(), empty(), and get_size().

## ◆ zero_length

bool libdar::secu_string::zero_length
| private

true if none of the other field are set due to zero byte length string requested

Definition at line 175 of file secu_string.hpp.

Referenced by c_str(), clear(), empty(), get_allocated_size(), and get_size().

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

- secu_string.hpp