Acquire.Service._service module

class Service

Bases: object

This class represents a service in the system. Services will either be identity services, access services, storage services or accounting services.

assert_admin_authorised(authorisation, resource=None)

Validate that the passed authorisation is valid for the (optionally) specified resource, and that this has been authorised by one of the admin accounts of this service

assert_unlocked()

Assert that this service object is unlocked

bucket()

Return the bucket you can use to read/write data to the object store associated with this service account

call_function(function, args=None)

Call the function ‘func’ on this service, optionally passing in the arguments ‘args’. This is a simple wrapper around Acquire.Service.call_function which automatically gets the correct URL, encrypts the arguments using the service’s public key, and supplies a key to encrypt the response (and automatically then decrypts the response)

can_identify_users()

Return whether or not this service can identify users. Most services can, at a minimum, identify their admin users. However, only true Identity Services can register and manage normal users

canonical_url()

Return the canonical URL for this service (this is the URL the service thinks it has, and which it has used to register itself with all other services)

static create(service_type, service_url, _testing=False)

Conduct stage1 of the construction of a new service. This creates the initial setup, creating a service with sufficient info to survive registration with a Registry. The second stage is performed automatically when the Registry confirms registration

create_stage2(service_uid, response)

Perform stage 2 of construction. This is called by the registry that registered this service, which will provide the service_uid

decrypt(message)

Decrypt the passed message

decrypt_data(data)

Decrypt the passed data that has been encrypted and sent to this service (encrypted via the ‘encrypt_data’ function). This will return a json-deserialisable dictionary. Note that the ‘service_uid’ should match the UID of this service. The data should also contain the fingerprint of the key used to encrypt the data, enabling the service to perform key rotation and management.

dump_keys(include_old_keys=False)

Return a dump of the current key and certificate, so that we can keep a record of all keys that have been used. The returned json-serialisable dictionary contains the keys, their fingerprints, and the datetime when they were generated. If this is run on the service, then the keys are encrypted the password which is encrypted using the master key

encrypt(message)

Encrypt the passed message

encrypt_data(data)

Encrypt the passed data, ready for transport to the service. Data should be a json-serialisable dictionary. This will return a new json-serialisable dictionary, which will contain the UID of the service this should be sent to (together with the canonical URL, which enables this data to be forwarded to where it needs to go), and the encrypted data, e.g. as;

data = {“service_uid” : “SERVICE_UID”,

“canonical_url” : “CANONICAL_URL”, “fingerprint” : “KEY_FINGERPRINT”, “encrypted_data” : “ENCRYPTED_DATA”}

static from_data(data, password=None, verify_data=False)

Deserialise this object from the passed data. This will only deserialise the private key and private certificate if the password is supplied.

If ‘verify_data’ is True, then extract the signature of the data and verify that that signature is correct. You should always verify data that has been transmitted over a network.

static get_canonical_url(service_url, service_type=None)

Return the canonical URL from the passed service_url. If ‘service_type’ is specified, then this will also add on extra paths needed for the services. For example,

get_canonical_url(“fn.acquire-aaai.com”, service_type=”identity”)

would return

“fn.acquire-aaai.com/identity”

get_key(fingerprint)

Return the key matching the passed fingerprint

get_session_info(session_uid, scope=None, permissions=None)

Return information about the passed session, optionally limited to the provided scope and permissions

get_trusted_service(service_url=None, service_uid=None)

Return the trusted service info for the service with specified service_url or service_uid

hostname()

Return the hostname of the canonical URL that provides this service

is_access_service()

Return whether or not this is an access service

is_accounting_service()

Return whether or not this is an accounting service

is_compute_service()

Return whether or not this is a compute service

is_evolution_of(other)

Return whether or not this service is an evolution of ‘other’. Evolving means that this service is the same service as ‘other’, but at a later point in time with newer keys

is_identity_service()

Return whether or not this is an identity service

is_locked()

Return whether or not this service object is locked. Locked service objects don’t contain copies of any private keys, and can be safely shared as a means of distributing public keys and certificates

is_null()

Return whether or not this is null

is_registry_service()

Return whether or not this is a registry service

is_storage_service()

Return whether or not this is a storage service

is_unlocked()

Return whether or not this service object is unlocked. Unlocked service objects have access to the skeleton key and other private keys. They should only run on the service. Locked service objects are what are returned by services to provide public keys and public certificates

key_update_interval()

Return the time delta between server key updates

last_certificate()

Return the old public certificate for this service. This was the certificate used before the last key update, and we store it in case we need to verify data signed using the old private certificate

last_key()

Return the old private key for this service (if it has been unlocked). This was the key used before the last key update, and we store it in case we have to decrypt data that was recently encrypted using the old public key

last_key_update()

Return the datetime when the key and certificate of this service were last updated

load_keys(data)

Return the keys that were dumped by ‘self.dump_keys()’. This returns a dictionary of the keys and datetime that they were created, indexed by their key fingerprints

login_service_user()

Return a logged in Acquire.Client.User for the service user. This can only be called inside the service, and when you have unlocked this service object

private_certificate()

Return the private signing certificate (if it has been unlocked)

private_key()

Return the private key (if it has been unlocked)

public_certificate()

Return the public signing certificate for this service

public_key()

Return the public key for this service

public_skeleton_key()

Return the public skeleton key. This is the public key for the matching private skeleton key, which is stored internally, and which should never be shared outside this service. It is used to encrypt data that should only be decryptable by the skeleton key

refresh_keys()

Refresh the keys and certificates

registry_uid()

Return the uid of the registry service that registered this service

service_type()

Return the type of this service

service_url(prefer_https=True)

Return the URL used to access this service. This includes the scheme, port etc. This is in contrast to the canonical url which just includes the URL

service_user_account_uid(accounting_service_url=None, accounting_service=None)

Return the UID of the financial account associated with this service on the passed accounting service

service_user_name()

Return the name of the service user account for this service

service_user_secrets()

Return the (encrypted) secrets for the service user account. These will only be returned if you have unlocked this service. You need access to the skeleton key to decrypt these secrets

service_user_uid()

Return the UID of the service user account for this service

should_refresh_keys()

Return whether the keys and certificates need to be refreshed - i.e. more than ‘key_update_interval’ has passed since the last key update, or the service has changed in some marked way

sign(message)

Sign the specified message

sign_data(data)

Sign the passed data, ready for transport. Data should be a json-serialisable dictionary. This will return a new json-serialisable dictionary, which will contain the signature and json-serialised original data, e.g. as;

data = {“service_uid” : “SERVICE_UID”,

“fingerprint” : “KEY_FINGERPRINT”, “signed_data” : “JSON_ENCODED_DATA”, “signature” : “SIG OF JSON_ENCODED_DATA”}

skeleton_key()

Return the skeleton key used by this service. This is an unchanging key which is stored internally, should never be shared outside the service, and which is used to decrypt all data. Unlocking the service involves loading and decrypting this skeleton key

to_data(password=None)

Serialise this key to a dictionary, using the supplied password to encrypt the private key and certificate

uid()

Return the uuid of this service. This MUST NEVER change, as the UID uniquely identifies this service to all other services

uses_https()

Return whether or not the canonical URL of this service is connected to via https

validation_string()

Return a string created from this object that can be signed to verify that all information was transmitted correctly

verify(signature, message)

Verify that this service signed the message

verify_data(data)

Verify the passed data has been signed by this service. The passed data should have the same format as that produced by ‘sign_data’. If the data is verified then this will return a json-deserialised dictionary of the verified data. Note that the ‘service_uid’ should match the UID of this service. The data should also contain the fingerprint of the key used to encrypt the data, enabling the service to perform key rotation and management.