crandas.connection_file

This module offers functions for reading and writing VDL connection files. A VDL connection file provides the client with all information that is needed to connect to the server. For example, it provides the URL endpoint that crandas connects to, as well as public keys of the servers.

The connection file a TOML (version 1.2.0) formatted file. Its format is versioned using semantic versioning. A crandas client should at least be able to support connection files that have a major version identical to crandas.connection_file.VERSION_TUPLE[0].

Version 1.3.0 of the connection file contains the following keys and corresponding types:

  • connection_file_version (str) - Equal to “1.3.0”

  • endpoint (str) - The URL (usually HTTPS) that serves the VDL API

  • keepalive (bool) - Whether to use HTTP keep alive for the connection. Defaults to true (added in version 1.1.0)

  • authorized_mode (bool) - Whether or not to connect to the server in authorized mode. This parameter is optional; if it is not given, the user has to specify the mode when using the file. (made optional in 1.3.0)

  • certificate (str) - PEM-encoded X.509 certificate for the endpoint TLS connection

  • api_token (str) - API Token to use to authenticate against the API. For now, it is a base64 encoded string containing username:password since we use HTTP(S) Basic authentication. This means that the username: password string should be base64 encoded before putting this in the config file. (added in version 1.2.0)

  • servers (list of length at least 1) - Each server contains the following keys:

    • public_key (str) - Base64-encoded public key of the server, that is used to encrypt PRSS keys for inputs.

An example file is the following:

connection_file_version = "1.2.0"
endpoint = "https://vdl-cluster-1.rosemancloud.com:9820/api/v1"
keepalive = true
authorized_mode = true
api_token = "cm9zZW1hbjp0ZXN0"
certificate = """
-----BEGIN CERTIFICATE-----
MIIFHzCCAwegAwIBAgIUKOUKG013Wy/BIRpeoQkDVBb72SgwDQYJKoZIhvcNAQEL
BQAwFDESMBAGA1UEAwwJbG9jYWxob3N0MB4XDTIzMDUwNTA3NDAxNFoXDTMzMDUw
MjA3NDAxNFowFDESMBAGA1UEAwwJbG9jYWxob3N0MIICIjANBgkqhkiG9w0BAQEF
AAOCAg8AMIICCgKCAgEAwrOwQxiRbuhNc1p21oviYHHSOs1XavLfuu7Vha2gFDZj
Fp9r5KH6a6B8Lr7olhYDH9zipBstLJ5NtRI0DpLyrr2Tk+jQiMVY7vfO5lyQ4FPK
YOgpWIM42wmGkmqZPLdQAgDI0KaOFcVnRlr6K0aqHFI9jRWjB0X8tFriGp9H2kgs
tp9nYxhrk9/NXp+rs6W8hZFiM2lGB2neaq+sSP6T89D1+H64Hef1YAWrcqrqhZF0
V4dfJIS/UMtMkkDTUNj/Jaxx6zIY5v2lIcLhUsAgYMzhDGZRdNUibRQlrvJCjJ6q
SYDHn1fxXdXUhiBm1BCOYslbWZCSSeZ0b6J54pZO4QF/tlSWEmmUE4oKZIGiMYwb
WW5Mst8Ofzy4VqY/ZfRBC/Mr8ox88DQexDq89IBZp7AZyPxUb8be/ZQTZZGmKul4
YKCf1VXi6KidcOGCMaS1O6XIWYBVWbo1L7i/MkBi0xNTU0neVc8xCtkJ+2QH2g6H
APcBxV8lC4nG/7LVATLaJs6qu2ObpzYXf3Hr5ZZfBhTjTtkhF1cTj2qN+spyLjFr
bGeo0hx3s7RRj78+lZTbzwxiFPnESRoct03AVfTdPCK6ixCNY1voEBENGIh0EN/w
NLmvDYl60XDZV+tW+0b/Z4Zee8xK12dghF2wiRAQZS+L5xgcjbf4UyD2pkEX3UkC
AwEAAaNpMGcwHQYDVR0OBBYEFC6eTdC4FcRFAE59ufDTvEtKj8QlMB8GA1UdIwQY
MBaAFC6eTdC4FcRFAE59ufDTvEtKj8QlMA8GA1UdEwEB/wQFMAMBAf8wFAYDVR0R
BA0wC4IJbG9jYWxob3N0MA0GCSqGSIb3DQEBCwUAA4ICAQB7Ocjdn1jFiKgKwVl7
gZ5S0VhaE+13YglXFpj7AZ9p9k9gdo3n4hvExO7NJNsQVkbcBxkgb0ssbYsMBvlv
wtviYWZFPtcsBwpXTzhf1UymQELxLiw3Sf1qDiAWXwwo5unnGB/VDbHZlnRl1G90
nrc5yOGya1x5D9vy/7Ig0d4z90CVUmFL+ipuJUaeLhnrZZGcmpjwq4VNtPen4vxz
RKddJfk8hoM0PUk7HTp0TQDc9VVpwsR9sVuY1q/0wHoJJg36DaZr74Jbi9pyCMUy
1qyAMmEoxnfxonsMd5MdP1UszoeKHbqzYXLTn7HcRlPQJCv2NXMH67FNl7dNYvCf
ynVztJ6uw9/jwpojBma0gc+4bXSASg0toyPxQpqNSsjkVTEeBC58NDeipBmX8jaH
kHfiC+PCVMRfedtz5YkoCZ748kQw4e6VpwfnvvR2zu0bdlZMcxKGmJ8iRgyI+AX2
pDzxnEO1O0ON0/toi+rVcdhVlj6w59tcpyaAHNP00yQkeqGcXAByDE4QBJbR4XOO
1VGKG3GstG/uD66XXYeEdLCWU4bwLLncML79jex+5XwB7dywj2Ulr2Lrj7v1L6NS
RF97nQQ7TtK4QEpwODf1Bpskr9ED+IUQJvbHq2VMbl3ndi8facVOA2B6R1HyHe+2
I/6lyXiafSVkR40+C6clN87KEw==
-----END CERTIFICATE-----
"""

[[servers]]
public_key = "x/s9bD+QPJzm31BM6KfmS+HhpUh8CgNH9iyYUk7K2Ac="

[[servers]]
public_key = "2AbJjs0NBoaw8Qzisgogt8EWciQ0aJjuHJAsWJMGlEE="

[[servers]]
public_key = "UcHB49e4MobUfbVDV3Q8VEa6ivxZy/k0iwzLYqRo5kg="
exception crandas.connection_file.ConnectionFileError

Bases: Exception

crandas.connection_file.read(fileobj, session, mode)

Read VDL connection file and store the configuration in a session object.

The user should specify a mode if and only if the connection file does not.

Parameters:
crandas.connection_file.write(fileobj, endpoint, authorized_mode, certificate, server_public_keys, *, keepalive=True, api_token=None)

Write connection configuration into a VDL connection file.

Note: this does not properly escape the variables if they contain quotes.

Parameters:

  • fileobj (file-like object)

  • endpoint (str) – The URL (usually HTTPS) that serves the VDL API

  • keepalive (bool, default: True) – Whether to use HTTP keepalive in the connection to the server

  • mode (bool or None) – Server mode to use: “design” (False), “authorized” (True), or unspecified

  • certificate (str) – PEM-encoded X.509 certificate for the endpoint TLS connection

  • server_public_keys (list of length at least 1 of 32-byte bytestrings) – The public key of the servers, used to encrypt PRSS keys for inputs.

  • api_token (Optional[str]) – API Token to use to authenticate against the API. For now, it is a base64-encoded string of the form Base64(x) where x == “<username>:<password>”, since we use HTTP(S) Basic authentication.