Package: pht-train-container-library
🚆 Train Container LibraryPython library for validating and interacting with pht-train images/containers.Installationpipinstallpht-train-container-librarySetup development environmentMake sure you havepoetryandpre-commitinstalled.Install the dependencies and pre-commit hooks:poetryinstall--withdevpoetryrunpre-commitinstallRun testspoetryrunpytestLinting and formattingThese commands are also run as pre-commit hooks.Linting with ruff:poetryrunruff.--fixFormatting with black:poetryrunblack.Security ProtocolThe pht security protocol adapted fromdocs/Secure_PHT_latest__official.pdfperforms two main tasks:Before executing a train-image on the local machine, unless the station is the first station on the route, the
previous results need to be decrypted and the content of the image needs to be validated based on the configuration
of the individual train ->pre-run.After executing the train the updated results need to be encrypted and the train configuration needs to be updated to
reflect the current state ->post-run.Train image structureTo ensure the protocol is working correctly train docker images are required to keep the following structure:/opt/train_config.json: Stores the configuration file of the train./opt/pht_train/: Stores all the files containing code or other things required for the train algorithm to run. The
contents of this directory can never change and is validated by thepre-runstep./opt/pht_results/: Stores the results of the train. Which will be decrypted in thepre-runstep and encrypted in
thepost-runstep.No files in the image outside the/opt/pht_results/directory should change during the execution of the algorithm.Usage - Python ScriptTo use the protocol in your own python application, after installing the library
withpip install pht-train-container-libraryan instance of the protocol can be to validate docker images as follows:fromtrain_lib.security.protocolimportSecurityProtocolfromtrain_lib.docker_util.docker_opsimportextract_train_configimage_name='<image-repo>:<image-tag>'station_id='<station-id>'# Get the train configuration from the imageconfig=extract_train_config(image_name)# Initialize the protocol with the extracted config and station_idprotocol=SecurityProtocol(station_id=station_id,config=config)# execute one of the protocol stepsprotocol.pre_run_protocol(image_name,private_key_path='<path-to-private-key>')# protocol.post_run_protocol(image_name, private_key_path='<path-to-private-key>')Usage - ContainerA containerized version of the protocol is also available it can be used with the following command:dockerrun-eSTATION_ID=<station_id>-ePRIVATE_KEY_PATH=/opt/private_key.pem-v/var/run/docker.sock:/var/run/docker.sock-v<path_to_your_key>:/opt/private_key.pemghcr.io/pht-medic/protocol<pre-run/post-run><image-repo>:<image-tag>STATION_IDandPRIVATE_KEY_PATHare required to be set in the environment variables. As well as passing the docker
socket/var/run/docker.sockto the container as a volume to enable docker-in-docker functionality.Pre-run protocolThe pre-run protocol consists of the following stepsThe hash of the immutable files (train definition) is verified making sure that the executable files did not change
during the the train definition.The digital signature is verified ensuring the correctness of the results at each stop of the train.The symmetric key is decrypted using the provided station private keyThe mutable files in/opt/pht_resultsare decrypted using the symmetric key obtained in the previous stepThe decrypted files are hashed and the hash is compared to the one stored in the train configuration file.Once these steps have been completed the image is ready to be executed.Post-run protocolCalculate the hash of the newly generated resultsSign the hash of the results using the providedPRIVATE_KEY_PATHUpdate the the train signature using the session id that is randomly generated at each execution stepEncrypt the resulting files using a newly generated symmetric keyEncrypt the generated symmetric key with the public keys of the train participantsUpdate the train configuration fileWith the completion of these steps the train is ready to be pushed into the registry for further processingTestsRun the tests to validate the security protocol is working as intended. From this projects root directory runpytest train_lib