9.1. PluginConfiguration¶

The PluginConfiguration service implements parsing and accessing the textual configuration set for plugin instances. The API is built on Python configparser.ConfigParser module with some additional functionality.

class safeguard.sessions.plugin.plugin_configuration.PluginConfiguration(configuration, defaults=None)¶

The PluginConfiguration class represents the plugin configuration service.

Parameters

configuration (str) – runtime configuration
defaults (str) – design time configuration defaults

get(section, option, default=None, required=False)¶

The get() method returns a configuration option as a string value. If the value of the option is $ the secret identified by the section and option pair is retrieved from the configured credential store

Parameters

section (str) – which [section] to search
option (str) – which option to get
default – return value if section or option is not present
required (boolean) – whether to throw an exception on missing option

Returns

the value of the option or None

Return type

str

Raises

RequiredConfigurationSettingNotFound

get_options(section)¶

The get_options() method returns a list containing the names of the options given for the [section].

New in version 1.3.0.

Parameters: section (str) – which section’s options to return
Returns: list of the option names or empty list if section is not present
Return type: list

get_key(section, option, default=None, required=False)¶

The get_key() method returns a configuration option as string value. If the value of the option is $ the certificate identified by the section and option pair is retrieved from the configured credential store When the private key is given in the configuration it should be in PEM format and key should not be encrypted and all the new lines must be indentet with one whitespace

New in version 1.2.0.

Example configuration:

[foo]
private_key = -----BEGIN RSA PRIVATE KEY-----
 key
 identified
 -----END RSA PRIVATE KEY-----

Parameters

section (str) – which [section] to search
option (str) – which option to get
default – return value if section or option is not present
required (boolean) – whether to throw an exception on missing option

Returns

private key and type parsed as dict

Return type

dict

Raises

RequiredConfigurationSettingNotFound

Raises

Pluginsdkvalueerror

get_certificate(section, option, default=None, required=False)¶

The get_certificate() method returns a configuration option as a dict value. If the value of the option is $ the certificate identified by the section and option pair is retrieved from the configured credential store When the certificate and private key is given in the configuration it should be in PEM format and all the new lines must be indented with one whitespace

Example configuration:

[foo]
certificate = -----BEGIN CERTIFICATE-----
 cert
 -----END CERTIFICATE-----
 -----BEGIN RSA PRIVATE KEY-----
 key
 -----END RSA PRIVATE KEY-----

Parameters

section (str) – which [section] to search
option (str) – which option to get
default – return value if section or option is not present
required (boolean) – whether to throw an exception on missing option

Returns

private key, certificate and type parsed as dict

Return type

dict

Raises

RequiredConfigurationSettingNotFound

Raises

Pluginsdkvalueerror

get_ca_certificate(section, option, default=None, required=False)¶

The get_ca_certificate() method returns a configuration option as a dict value. If the value of the option is $[name] then certificates will be retrieved from the trusted CA list by that name When the CA certificates are given in the configuration it should be in PEM format and all the new lines must be indented with one whitespace

New in version 1.3.0.

Example configuration:

[foo]
certificate = -----BEGIN CERTIFICATE-----
 cert
 -----END CERTIFICATE-----
 -----BEGIN CERTIFICATE-----
 rootCert
 -----END CERTIFICATE-----

Parameters

section (str) – which [section] to search
option (str) – which option to get
default – return value if section or option is not present
required (boolean) – whether to throw an exception on missing option

Returns

certificates in a list and type parsed as dict

Return type

dict

Raises

RequiredConfigurationSettingNotFound

Raises

Pluginsdkvalueerror

getboolean(section, option, default=None, required=False)¶

The getboolean() method returns the boolean value of a configuration option. The configuration option may have the values “yes” and “no” or their upper case variants. In case of invalid value, a PluginSDKValueError exception is raised.

Parameters

section (str) – which [section] to search
option (str) – which option to get
default – value if section or option is not present
required (boolean) – whether to throw exception on missing option

Returns

the value of the option or None

Return type

boolean

Raises

RequiredConfigurationSettingNotFound

Raises

PluginSDKValueError

getint(section, option, default=None, required=False)¶

The getint() method returns the integer value of a configuration option. If the configuration option cannot be converted to an integer value, then a PluginSDKValueError exception is raised.

Parameters

section (str) – which [section] to search
option (str) – which option to get
default – value if section or option is not present
required (boolean) – whether to throw exception on missing option

Returns

the value of the option or None

Return type

int

Raises

RequiredConfigurationSettingNotFound

Raises

PluginSDKValueError

getfloat(section, option, default=None, required=False)¶

The getfloat() method returns the floating point value of a configuration option. If the configuration option cannot be converted to a floating point value, then a PluginSDKValueError exception is raised.

Parameters

section (str) – which [section] to search
option (str) – which option to get
default – value if section or option is not present
required (boolean) – whether to throw exception on missing option

Returns

the value of the option or None

Return type

float

Raises

RequiredConfigurationSettingNotFound

Raises

PluginSDKValueError

getienum(section, option, value_set, default=None, required=False)¶

The getienum() method returns the value of an option that may only assume certain lower case string values. In other words the lower case value of the configuration option is checked against a list of possible values. In case the configuration value is not one of the allowed values, then a PluginSDKValueError exception is raised.

from safeguard.sessions.plugin import PluginConfiguration

config = PluginConfiguration("""
                      [foobar]
                      color1 = LightGreen
                      color2 = LightBlue
                       """)

# next line is ok, returns 'lightgreen'
config.getienum('foobar', 'color1', ('green', 'lightgreen'))

# next line throws PluginSDKValueError exception
config.getienum('foobar', 'color2', ('green', 'lightgreen'))

Parameters

section (str) – which [section] to search
option (str) – which option to get
value_set (seq) – a container of possible lower case values (the container should implement the in operator)
default (str) – value if section or option is not present
required (boolean) – whether to throw exception on missing option

Returns

the value of the option or None

Return type

str

Raises

RequiredConfigurationSettingNotFound

Raises

PluginSDKValueError

getlist(section, option, default=None, required=False)¶

The getlist() method returns a list of “,” separated configuration values for that option.

from safeguard.sessions.plugin import PluginConfiguration

config = PluginConfiguration("""
                      [foobar]
                      colors = LightGreen, LightBlue
                       """)

# next line is ok, returns ['LightGreen', 'LightBlue']
config.getlist('foobar', 'colors')

Parameters

section (str) – which [section] to search
option (str) – which option to get
default (str) – ‘,’ separated strings of values if section or option is not present
required (boolean) – whether to throw exception on missing option

Returns

list of configured values

Return type

list

Raises

RequiredConfigurationSettingNotFound

9.1.1. Exceptions¶

exception safeguard.sessions.plugin.plugin_configuration_exceptions.RequiredConfigurationSettingNotFound(message, variables=None)¶: The RequiredConfigurationSettingNotFound excpetion is raised when a required configuration option is not present when requested by the plugin.

Table Of Contents

Previous topic

Next topic

9.1. PluginConfiguration¶

9.1.1. Exceptions¶