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 filenameRaises: 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 ofRemote
- 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 ofPKey
.RSAKey
by default. (the defaultkey_type
can change in the future.) - bits (
Optional
[int
]) – the number of bits the generated key should be. ifkey_type
isRSAKey
it has to be 512 at least. the default value isNone
, which means tokey_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 itskey_type
, the default value ofbits
becameNone
(from 2048).None
means to followkey_type
‘s own default (appropriate) bits.New in version 0.2.0: The
bits
optional parameter.-
terminate
()¶ Graceful termination.
- servers (
-
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 forwith
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 ofRemote
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 replaceold_key
- servers (
-
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
. Ifbits
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 ofPKey
.RSAKey
by default. (the defaultkey_type
can change in the future.) - bits – the number of bits the generated key should be.
if
key_type
isRSAKey
it has to be 512 at least. the default value isNone
, which means tokey_type
‘s own default (appropriate) bits
Returns: a generate key which is an instance of the given
key_type
Return type: Raises: KeyGenerationError – when it failed to generate a key using given options (
key_type
andbits
)New in version 0.4.0.
- key_type (
-
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 readReturns: 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 thekey_store
, and then makesservers
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 ofRemote
- 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 ofPKey
.RSAKey
by default. (the defaultkey_type
can change in the future.) - bits (
Optional
[int
]) – the number of bits the generated key should be. ifkey_type
isRSAKey
it has to be 512 at least. the default value isNone
, which means tokey_type
‘s own default (appropriate) bits
Returns: the created new master key
Return type: New in version 0.4.0: The
key_type
optional parameter.Changed in version 0.4.0: Since the appropriate
bits
depends on itskey_type
, the default value ofbits
becameNone
(from 2048).None
means to followkey_type
‘s own default (appropriate) bits.New in version 0.2.0: The
bits
optional parameter.- servers (