`geofront.masterkey` — Master key management¶

Master key renewal process:

Create a new master key without updating the master key store.
Update every authorized_keys to authorize both the previous and the new master keys.
Store the new master key to the master key store, and remove the previous master key.
Update very authorized_keys to authorize only the new master key.

For more details, see also TwoPhaseRenewal.

Changed in version 0.2.0: CloudMasterKeyStore is moved from this module to geofront.backends.cloud. See CloudMasterKeyStore.

exception geofront.masterkey.EmptyStoreError¶: Exception that rises when there’s no master key yet in the store.

class geofront.masterkey.FileSystemMasterKeyStore(path: str) → None¶

Store the master key into the file system. Although not that secure, but it might help you to evaluate Geofront.

Parameters:	path (`str`) – the path to save file. it has to end with the filename
Raises:	OSError – when the `path` is not writable

exception geofront.masterkey.KeyGenerationError¶: A subtype of ValueError which rise when failed to generate a key.

New in version 0.4.0.

class geofront.masterkey.MasterKeyStore¶

The master key store backend interface. It can have only one master key at the most.

load() → paramiko.pkey.PKey¶

Load the stored master key.

Returns:	the stored master key
Return type:	`paramiko.pkey.PKey`
Raises:	geofront.masterkey.EmptyStoreError – when there’s no master key yet in the store

save(master_key: paramiko.pkey.PKey) → None¶

Remove the stored master key, and then save the new master key. The operation should be atomic.

Parameters:	master_key (`paramiko.pkey.PKey`) – the new master key to replace the existing master key

class geofront.masterkey.PeriodicalRenewal(servers: typing.AbstractSet[geofront.remote.Remote], key_store: geofront.masterkey.MasterKeyStore, interval: datetime.timedelta, key_type: typing.Type[paramiko.pkey.PKey] = <class 'paramiko.rsakey.RSAKey'>, bits: typing.Union[int, NoneType] = None, start: bool = True) → None¶

Periodically renew the master key in the separated background thread.

Parameters:

servers (AbstractSet[Remote]) – servers to renew the master key. every element has to be an instance of Remote
key_store (MasterKeyStore) – the master key store to update
interval (datetime.timedelta) – the interval to renew
key_type (Type[PKey]) – the type of a new master key. it has to be a subclass of PKey. RSAKey by default. (the default key_type can change in the future.)
bits (Optional[int]) – the number of bits the generated key should be. if key_type is RSAKey it has to be 512 at least. the default value is None, which means to key_type‘s own default (appropriate) bits
start (bool) – whether to start the background thread immediately. True by default

New in version 0.4.0: The key_type optional parameter.

Changed in version 0.4.0: Since the appropriate bits depends on its key_type, the default value of bits became None (from 2048). None means to follow key_type‘s own default (appropriate) bits.

New in version 0.2.0: The bits optional parameter.

terminate()¶: Graceful termination.

class geofront.masterkey.TwoPhaseRenewal(servers: typing.AbstractSet[geofront.remote.Remote], old_key: paramiko.pkey.PKey, new_key: paramiko.pkey.PKey) → None¶

Renew the master key for the given servers. It’s a context manager for with statement.

# State: servers allow only old_key;
#        old_key is in the master_key_store
with TwoPhaseRenewal(servers, old_key, new_key):
    # State: *servers allow both old_key and new_key;*
    #        old_key is in the master_key_store
    master_key_store.save(new_key)
    # State: servers allow both old_key and new_key;
    #        *new_key is in the master_key_store.*
# State: *servers allow only new_key;*
#        new_key is in the master_key_store

Parameters:	servers (`AbstractSet`[`Remote`]) – the set of `Remote` servers to renew their master key old_key (`paramiko.pkey.PKey`) – the previous master key to expire new_key (`paramiko.pkey.PKey`) – the new master key to replace `old_key`

geofront.masterkey.generate_key(key_type: typing.Type[paramiko.pkey.PKey] = <class 'paramiko.rsakey.RSAKey'>, bits: typing.Union[int, NoneType] = None) → paramiko.pkey.PKey¶

Generate a new key of the given key_type. If bits is omitted generate one with an appropriate bits.

Parameters:	key_type (`Type`[`PKey`]) – the type of a new master key. it has to be a subclass of `PKey`. `RSAKey` by default. (the default `key_type` can change in the future.) bits – the number of bits the generated key should be. if `key_type` is `RSAKey` it has to be 512 at least. the default value is `None`, which means to `key_type`‘s own default (appropriate) bits
Returns:	a generate key which is an instance of the given `key_type`
Return type:	`PKey`
Raises:	KeyGenerationError – when it failed to generate a key using given options (`key_type` and `bits`)

New in version 0.4.0.

geofront.masterkey.read_private_key_file(file_: typing.IO[str]) → paramiko.pkey.PKey¶

Read a private key file. Similar to PKey.from_private_key() except it guess the key type.

Parameters:	file (`IO`[`str`]) – a stream of the private key to read
Returns:	the read private key
Return type:	`paramiko.pkey.PKery`
Raises:	paramiko.ssh_exception.SSHException – when something goes wrong

geofront.masterkey.renew_master_key(servers: typing.AbstractSet[geofront.remote.Remote], key_store: geofront.masterkey.MasterKeyStore, key_type: typing.Type[paramiko.pkey.PKey] = <class 'paramiko.rsakey.RSAKey'>, bits: typing.Union[int, NoneType] = None) → paramiko.pkey.PKey¶

Renew the master key. It creates a new master key, makes servers to authorize the new key, replaces the existing master key with the new key in the key_store, and then makes servers to deauthorize the old key. All these operations are done in a two-phase renewal transaction.

Parameters:	servers (`AbstractSet`[`Remote`]) – servers to renew the master key. every element has to be an instance of `Remote` key_store (`MasterKeyStore`) – the master key store to update key_type (`Type`[`PKey`]) – the type of a new master key. it has to be a subclass of `PKey`. `RSAKey` by default. (the default `key_type` can change in the future.) bits (`Optional`[`int`]) – the number of bits the generated key should be. if `key_type` is `RSAKey` it has to be 512 at least. the default value is `None`, which means to `key_type`‘s own default (appropriate) bits
Returns:	the created new master key
Return type:	`paramiko.pkey.PKey`

New in version 0.4.0: The key_type optional parameter.

Changed in version 0.4.0: Since the appropriate bits depends on its key_type, the default value of bits became None (from 2048). None means to follow key_type‘s own default (appropriate) bits.

New in version 0.2.0: The bits optional parameter.

geofront.masterkey — Master key management¶

`geofront.masterkey` — Master key management¶