StoredSafe Python

Transparent Python wrapper for the StoredSafe REST-like API.

Full documentation of the API response signatures and more advanced parameters can be found at the StoredSafe API Documentation.

Install

Install storedsafe from pypi.

pip install storedsafe

Examples

Login

# Initial configurationapi=StoredSafe(host='my.site.com', apikey='my-apikey')
# Login using TOTPapi.login_totp(username='my-username', passphrase='my-passphrase', otp='my-timed-otp')
# Login using YubiKeyapi.login_yubikey(username='my-username', passphrase='my-passphrase', otp='my-yubico-otp')
# Login using client certificate# 3rd party software may be required to get the certificate data from your smartcardapi.login_smartcard(username='my-username', passphrase='my-passphrase', cert='/path/to/cert', key='/path/to/key')

In the event you already have a token, you can skip the previous step and input the token directly.

api=StoredSafe(host='my.site.com', token='my-storedsafe-token')

If you're using the StoredSafe tokenhandler, you can also retrieve the host, apikey and token from an rc-file:

# Default rc locationapi=StoredSafe.from_rc()
# Custom rc locationapi=StoredSafe.from_rc(path='/path/to/rc-file')

Programming styles

For create and edit methods, parameters can be easily passed as keyword arguments, for example:

api.create_vault(vaultname="My Vault", policy=7, description="Sercret")

Or if you're receiving data in dict-format, it can be unpacked into the method:

data=function_that_returns_data()
api.create_vault(**data)

Return types

The return value of all methods is a requests response object. To obtain the data returned by a successful response object, you can use the json() function:

res=api.list_vaults()
ifres.status_code<=403:
data=res.json()
ifres.ok:
print(data['VAULTS'])
else:
print(data['ERRORS'])

Files

Files are returned as a base64 string and must be decoded to restore the original state of the file.

importbase64res=api.get_file(object_id)
data=res.json()
filedata=base64.urlsafe_b64decode(data['FILEDATA'])
filedata_utf8=filedata.decode('utf-8') # If you want to use UTF-8 encodingwithopen(path, 'w') asf:
f.write(filedata_utf8)

Usage

fromstoredsafeimportStoredSafe# Manual configurationapi=StoredSafe(host='my.site.com', apikey='my-apikey', token='my-storedsafe-token')
# Automatic configurationapi=StoredSafe.from_rc() # Use default path ~/.storedsafe-client.rcapi=StoredSafe.from_rc(path='/path/to/rc-file')
# Authapi.login_totp(username='my-username', passphrase='my-passphrase', otp='my-otp')
api.login_yubikey(username='my-username', passphrase='my-passphrase', otp='my-otp')
api.login_smartcard(username='my-username', passphrase='my-passphrase', cert='/path/to/cert', key='/path/to/key')
api.logout()
api.check()
# Vaultsapi.list_vaults()
api.vault_objects(vault_id) # String or integerapi.vault_members(vault_id)
api.create_vault(**params) # See parameters in API documentationapi.edit_vault(vault_id, **params)
api.delete_vault(vault_id)
# Objectsapi.get_object(object_id) # String or integerapi.get_object(object_id, children=True) # children False by defaultapi.decrypt_object(object_id)
api.get_file(object_id) # Decrypt file and get base64 version of fileapi.get_mime_type(file_path) # Get mimetype and max file upload sizeapi.filecollect(file_path) # Get the suggested template for the fileapi.upload_file(file_path, **params)
api.create_object(**params)
api.edit_object(object_id, **params)
api.delete_object(object_id)
# Usersapi.list_users() # List all usersapi.list_users(search_string) # Search for any user matching search_stringapi.get_user(user_id)
api.create_user(**params)
api.edit_user(user_id, **params)
api.delete_user(user_id)
# Utilsapi.status_values()
api.password_policies()
api.version()
api.generate_password() # Use default settingsapi.generate_password(**params)

Requests parameters

In version 1.2.0+, parameters can be passed directly to the requests library through various methods.

Requests parameters can be applied directly to the StoredSafe API object:

fromstoredsafeimportStoredSaferequests_options= {
'timeout': 10,
'verify': ca_path
}
api=StoredSafe(host='my.site.com', apikey='my-apikey', token='my-storedsafe-token', **requests_options)
# Adjust requests can be adjusted later through the `requests_options` attributeapi.requests_options['timeout'] =5

Or when calling any of the API methods:

api.create_user(**user_params, timeout=10)

Options passed to one of the API methods will take precedence over the options defined on the StoredSafe object.