Machina Client SDK Version 2.1.2
Ionic Security Machina Client SDK for Python users
Public Member Functions | Static Public Attributes | List of all members
ionicsdk.keyvault.KeyVault Class Reference

KeyVault service object. More...

Inheritance diagram for ionicsdk.keyvault.KeyVault:
ionicsdk.keyvault.KeyVaultAppleKeyChain ionicsdk.keyvault.KeyVaultCustom ionicsdk.keyvault.KeyVaultLinux ionicsdk.keyvault.KeyVaultMac ionicsdk.keyvault.KeyVaultWindowsDpApi

Public Member Functions

def __init__ (self)
 Constructs a default key vault.
 
def SetKey (self, keyVaultKeyRecord, addIfNotFound)
 
def GetKey (self, keyid)
 Get a single key from the key vault. More...
 
def GetKeys (self, keyids)
 Get multiple keys from the key vault. More...
 
def GetAllKeyIds (self)
 Get the list of all key IDs in the key vault. More...
 
def GetAllKeys (self)
 Get the list of all key objects in the key vault. More...
 
def GetKeyCount (self)
 Get the number of keys in the key vault. More...
 
def HasKey (self, keyid)
 Determine if a key exists in the key vault. More...
 
def RemoveKey (self, keyid)
 Remove a single key from the key vault. More...
 
def RemoveKeys (self, keyids)
 Remove one or more keys from the key vault. More...
 
def ClearAllKeys (self)
 Remove all keys from the key vault. More...
 
def ExpireKeys (self)
 Remove all keys which have expired. More...
 
def Sync (self)
 
def HasChanges (self)
 Determine if there are any changes to the key vault in memory that necessitate a sync(). More...
 
def CleanVaultStore (self)
 Deletes any long term storage used by the particular key vault. More...
 

Static Public Attributes

int ISKEYVAULT_OK = 0
 Key Vault Error Codes - Success code.
 
int ISKEYVAULT_ERROR_BASE = 16000
 Key Vault Error Codes - error code range base.
 
int ISKEYVAULT_ERROR = 16001
 Key Vault Error Codes - A general error occurred, but its specific problem is not represented with its own code.
 
int ISKEYVAULT_UNKNOWN = 16002
 Key Vault Error Codes - An unknown and unexpected error occurred.
 
int ISKEYVAULT_NOMEMORY = 16003
 Key Vault Error Codes - A memory allocation failed. More...
 
int ISKEYVAULT_MISSINGVALUE = 16004
 Key Vault Error Codes - An expected and required value was not found. More...
 
int ISKEYVAULT_INVALIDVALUE = 16005
 Key Vault Error Codes - A value was found that is invalid. More...
 
int ISKEYVAULT_KEY_NOT_FOUND = 16006
 Key Vault Error Codes - A key was not found. More...
 
int ISKEYVAULT_KEY_UPDATE_IGNORED = 16007
 Key Vault Error Codes - A key update request was ignored. More...
 
int ISKEYVAULT_OPENFILE = 16008
 Key Vault Error Codes - A file failed to open. More...
 
int ISKEYVAULT_EOF = 16009
 Key Vault Error Codes - The end of a file was found before it was expected. More...
 
int ISKEYVAULT_NOHEADER = 16010
 Key Vault Error Codes - A file header could not be found where it was expected. More...
 
int ISKEYVAULT_PARSEFAILED = 16011
 Key Vault Error Codes - The parsing of some serialized data failed. More...
 
int ISKEYVAULT_HEADER_MISMATCH = 16012
 Key Vault Error Codes - A key vault file header has values which were not expected. More...
 
int ISKEYVAULT_LOAD_NOT_NEEDED = 16013
 Key Vault Error Codes - A key vault load operation was skipped because it was not needed. More...
 
int ISKEYVAULT_CREATE_PATH = 16014
 Key Vault Error Codes - A key vault save operation could not create the required file path. More...
 
int ISKEYVAULT_INVALID_KEY = 16015
 Key Vault Error Codes - A key is invalid in some way (key ID, key bytes, etc). More...
 
int ISKEYVAULT_RESOURCE_NOT_FOUND = 16016
 Key Vault Error Codes - A resource was not found. More...
 
int ISKEYVAULT_FILE_VERSION = 16017
 Key Vault Error Codes - A key vault file load operation failed due to unsupported file version. More...
 

Detailed Description

KeyVault service object.

This serves as the base class for the Mac, iOS, Windows and Custom version. All the basic functionality of managing keys is here.

Error Codes:

Member Function Documentation

◆ CleanVaultStore()

def ionicsdk.keyvault.KeyVault.CleanVaultStore (   self)

Deletes any long term storage used by the particular key vault.

In the general case, this mean deleting a file. Useful when the Key Vault becomes corrupted.

Returns
None

Reimplemented in ionicsdk.keyvault.KeyVaultCustom.

◆ ClearAllKeys()

def ionicsdk.keyvault.KeyVault.ClearAllKeys (   self)

Remove all keys from the key vault.

Returns
ISKEYVAULT_OK; there is no error condition for this function.

◆ ExpireKeys()

def ionicsdk.keyvault.KeyVault.ExpireKeys (   self)

Remove all keys which have expired.

Returns
A list of the string ids that were removed. Can be None.

◆ GetAllKeyIds()

def ionicsdk.keyvault.KeyVault.GetAllKeyIds (   self)

Get the list of all key IDs in the key vault.

Returns
A list of string keyids which represent all the data protection keys that are contained in the key vault.

◆ GetAllKeys()

def ionicsdk.keyvault.KeyVault.GetAllKeys (   self)

Get the list of all key objects in the key vault.

Returns
KeyVaultKeyReordList of all the data protection keys in the key vault.

◆ GetKey()

def ionicsdk.keyvault.KeyVault.GetKey (   self,
  keyid 
)

Get a single key from the key vault.

Searches for a key identified by keyId. On success, key will be returned. If the key is not found, then None will be returned.

Parameters
keyid- The data protection key ID (also known as the key tag).
Returns
keyVaultKeyRecord - Output key object that is populated with the retrieved key or None.

◆ GetKeyCount()

def ionicsdk.keyvault.KeyVault.GetKeyCount (   self)

Get the number of keys in the key vault.

Returns
The number of keys in the key vault.

◆ GetKeys()

def ionicsdk.keyvault.KeyVault.GetKeys (   self,
  keyids 
)

Get multiple keys from the key vault.

Searches for each key identifier in the keyids list. On success, a list of keys found will be returned. If no key is not found, then an empty list will be returned.

Parameters
keyids- A list of data protection key ID's (also known as the key tag).
Returns
(keyVaultKeyRecordList) Output key object list that is populated with the found and retrieved keys. If nothing is found, the list will be empty.

◆ HasChanges()

def ionicsdk.keyvault.KeyVault.HasChanges (   self)

Determine if there are any changes to the key vault in memory that necessitate a sync().

Returns
True if changes have been made to the key vault in memory that have not yet been put into permanent storage via Sync(). For example, if a key is added, update, or removed, then a call to Sync() is needed in order to reflect the relevant change(s) to permanent storage.

◆ HasKey()

def ionicsdk.keyvault.KeyVault.HasKey (   self,
  keyid 
)

Determine if a key exists in the key vault.

Parameters
keyid- (string) The data protection key ID to look for.
Returns
True if a key with the specified ID exists. Otherwise, returns False.

◆ RemoveKey()

def ionicsdk.keyvault.KeyVault.RemoveKey (   self,
  keyid 
)

Remove a single key from the key vault.

Parameters
keyid- (string) The key object to remove.
Returns
ISKEYVAULT_OK on success. Otherwise, returns ISKEYVAULT_KEY_NOT_FOUND if the specified key was not found.

◆ RemoveKeys()

def ionicsdk.keyvault.KeyVault.RemoveKeys (   self,
  keyids 
)

Remove one or more keys from the key vault.

Parameters
keyids- (list of strings) The set of data protection key IDs to remove.
Returns
A list of the string ids that were not found. Can be None.

◆ SetKey()

def ionicsdk.keyvault.KeyVault.SetKey (   self,
  keyVaultKeyRecord,
  addIfNotFound 
)

Add or update a key into the key vault.

Attempts to update the provided key into the key vault and returns ISKEYVAULT_OK on success.

If the key does not exist and addIfNotFound is set to true, then the key will be added to the vault.

If the key does not exist and addIfNotFound is set to false, then ISKEYVAULT_KEY_NOT_FOUND will be returned.

If the key is found, but its 'issued' time (KeyVaultKeyRecord.issuedServerTimeUtcSeconds) is unchanged, then the key will NOT be updated and ISKEYVAULT_KEY_UPDATE_IGNORED will be returned.

If some aspect of the key itself is invalid, such as the key ID being empty, the key data not being 32 bytes in size, etc. then ISKEYVAULT_INVALID_KEY will be returned.

Parameters
keyVaultKeyRecord- The data protection key.
addIfNotFound- Determines if the key should be added in the case that it is not found.
Returns
Returns one of the return codes listed above.

◆ Sync()

def ionicsdk.keyvault.KeyVault.Sync (   self)

Perform synchronization to permanent storage.

This function first loads any detected changes to the key vault from permanent storage, then merges those changes (if any) with the key vault in memory, and finally saves the merged changes to permanent storage.

This synchronization is both process-safe and thread-safe to ensure that no changes are lost, and more importantly that the permanent storage is never corrupted.

See KeyVaultCustom for details on how to customize this process.

Returns
Returns ISKEYVAULT_OK on success. Otherwise, returns an error code.

Member Data Documentation

◆ ISKEYVAULT_CREATE_PATH

int ionicsdk.keyvault.KeyVault.ISKEYVAULT_CREATE_PATH = 16014
static

Key Vault Error Codes - A key vault save operation could not create the required file path.

This happens when a save operation is requested on a key vault, but the vault is unable to create the necessary folder path to store the file. For example, if the destination file path is /a/b/c/vault.dat, and the folder /a/b/c does not exist (or some part of it), then the key vault attempts to create the path. If the path cannot be created, then ISKEYVAULT_CREATE_PATH is returned.

◆ ISKEYVAULT_EOF

int ionicsdk.keyvault.KeyVault.ISKEYVAULT_EOF = 16009
static

Key Vault Error Codes - The end of a file was found before it was expected.

This normally happens if the file has been truncated or is zero length.

◆ ISKEYVAULT_FILE_VERSION

int ionicsdk.keyvault.KeyVault.ISKEYVAULT_FILE_VERSION = 16017
static

Key Vault Error Codes - A key vault file load operation failed due to unsupported file version.

This happens when a key vault attempts to load a file from disk, but the version of that file is not supported. This may happen when an older version of the SDK is used to load a file that was saved by a newer version of the SDK.

◆ ISKEYVAULT_HEADER_MISMATCH

int ionicsdk.keyvault.KeyVault.ISKEYVAULT_HEADER_MISMATCH = 16012
static

Key Vault Error Codes - A key vault file header has values which were not expected.

This typically happens when a key vault attempts to open a file that was saved by a different key vault type. For example, if a Windows DPAPI key vault object attempts to open a file that was saved by a different key vault type (e.g. Apple Keychain key vault).

◆ ISKEYVAULT_INVALID_KEY

int ionicsdk.keyvault.KeyVault.ISKEYVAULT_INVALID_KEY = 16015
static

Key Vault Error Codes - A key is invalid in some way (key ID, key bytes, etc).

This may happen if a key was found to be invalid. For example, if the key is the wrong size (any size other than 32 bytes), the key ID string is empty or contains invalid characters, etc.

◆ ISKEYVAULT_INVALIDVALUE

int ionicsdk.keyvault.KeyVault.ISKEYVAULT_INVALIDVALUE = 16005
static

Key Vault Error Codes - A value was found that is invalid.

For example, a string value was expected, but it was actually an integer. This is typically emitted from functions that are responsible for parsing deserializing data.

◆ ISKEYVAULT_KEY_NOT_FOUND

int ionicsdk.keyvault.KeyVault.ISKEYVAULT_KEY_NOT_FOUND = 16006
static

Key Vault Error Codes - A key was not found.

This happens when attempting to access a key that does not exist, for example when trying to retrieve via GetKey(..) or update a key via SetKey(..).

◆ ISKEYVAULT_KEY_UPDATE_IGNORED

int ionicsdk.keyvault.KeyVault.ISKEYVAULT_KEY_UPDATE_IGNORED = 16007
static

Key Vault Error Codes - A key update request was ignored.

This happens when attempting to update a key via SetKey(), and the provided key is not newer than the key which already exists in the vault. This is not an error, per se, but it is informing the caller that the requested update is not needed, and as such is ignored. The determination is made by comparing key issuance UTC time (KeyVaultKeyRecord.issuedServerTimeUtcSeconds).

◆ ISKEYVAULT_LOAD_NOT_NEEDED

int ionicsdk.keyvault.KeyVault.ISKEYVAULT_LOAD_NOT_NEEDED = 16013
static

Key Vault Error Codes - A key vault load operation was skipped because it was not needed.

This happens when a load operation is requested on a key vault, but the vault skipped the operation because it determined that the underlying storage data has not changed since the previous load operation. A key vault may do this in order to optimize execution time by avoiding costly loads from disk when possible.

◆ ISKEYVAULT_MISSINGVALUE

int ionicsdk.keyvault.KeyVault.ISKEYVAULT_MISSINGVALUE = 16004
static

Key Vault Error Codes - An expected and required value was not found.

This is typically emitted from functions that are responsible for parsing / deserializing data.

◆ ISKEYVAULT_NOHEADER

int ionicsdk.keyvault.KeyVault.ISKEYVAULT_NOHEADER = 16010
static

Key Vault Error Codes - A file header could not be found where it was expected.

This normally happens when trying to decrypt a file that is not encrypted, or the encrypted file has been corrupted.

◆ ISKEYVAULT_NOMEMORY

int ionicsdk.keyvault.KeyVault.ISKEYVAULT_NOMEMORY = 16003
static

Key Vault Error Codes - A memory allocation failed.

This can happen if there is not a sufficient amount of memory available to perform an operation.

◆ ISKEYVAULT_OPENFILE

int ionicsdk.keyvault.KeyVault.ISKEYVAULT_OPENFILE = 16008
static

Key Vault Error Codes - A file failed to open.

This normally happens because the file path provided does not exist or it is not accessible due to lack of permission.

◆ ISKEYVAULT_PARSEFAILED

int ionicsdk.keyvault.KeyVault.ISKEYVAULT_PARSEFAILED = 16011
static

Key Vault Error Codes - The parsing of some serialized data failed.

This typically happens if a file or block of data is corrupted or of an unexpected format.

◆ ISKEYVAULT_RESOURCE_NOT_FOUND

int ionicsdk.keyvault.KeyVault.ISKEYVAULT_RESOURCE_NOT_FOUND = 16016
static

Key Vault Error Codes - A resource was not found.

This happens when attempting to access a resource that does not exist.


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