Package: cryptol
Cryptol Python ClientIn-development Python client for Cryptol. Currently tested on Linux and MacOS --
at present there may be some minor issues running the Python Client in a Windows
environment that need to be addressed (e.g., some Python process management methods
are not cross-OS-compatible).This Cryptol client depends on thecryptol-remote-apiserver.TL;DR Steps to running Cryptol Python scriptsClone the repogit clone https://github.com/GaloisInc/cryptol.gitEnter the repocd cryptolInitialize git submodulesgit submodule update --initNavigate to the python clientcd cryptol-remote-api/pythonInstall and setup some version of thecryptol-remote-apiserver and update any
relevant environment variables as needed (seecryptol.connect()documentation
for the various ways a server can be connected to).
E.g., here is how the docker image of the server might be used:$ docker run --name=cryptol-remote-api -d \
  -v $PWD/tests/cryptol/test-files:/home/cryptol/tests/cryptol/test-files \
  -p 8080:8080 \
  ghcr.io/galoisinc/cryptol-remote-api:nightly-portable
$ export CRYPTOL_SERVER_URL="http://localhost:8080/"Install the Python client (requires Python v3.7 or newer -- we recommend usingpoetryto install the package):$ poetry installRun tests or individual scripts:$ poetry run python -m unittest discover tests/cryptol
$ poetry run python tests/cryptol/test_salsa20.pyPython Client Installation (via Poetry)First, clone the repository and submodules.$ git clone https://github.com/GaloisInc/cryptol.git
$ cd cryptol
$ git submodule update --initThen, usepoetryto install
the python client from thecryptol-remote-api/pythondirectory:$ cd cryptol-remote-api/python
$ poetry installCryptol serverTo run the verification scripts acryptol-remote-apiserver must be available,
either as a local executable or running in docker image listening on a port.Connecting with a server in a scriptConnecting to a server in a Python script is accomplished via thecryptol.connectmethod. Its accompanying Python doc strings describe the various ways it can be
used. Below is a brief summary:cryptol.connect(), when provided no arguments, will attempt the following in order:If the environment variableCRYPTOL_SERVERis set and refers to an
executable, it is assumed to be acryptol-remote-apiexecutable and will be
used for the duration of the script.If the environment variableCRYPTOL_SERVER_URLis set, it is assumed to be
the URL for a running Cryptol server inhttpmode and will be connected to.
(N.B., this can be a local server or a server running in a docker image.)If an executablecryptol-remote-apiis available on thePATHit is
assumed to be a Cryptol server and will be used for the duration of the script.Additional arguments and options are documented with the function.Notably, thereset_serverkeyword can be used to connect to a running server
and reset it, ensuring states from previous scripts have been cleared. E.g.,cryptol.connect(reset_server=True).Acquiring a Cryptol ServerThere are several ways a server executable can be obtained.Server executablesAn executable of the server is now included in each release of Cryptol.Nightly server builds can be found asArtifactsof theNightly
Buildsgithub action. I.e., go to theNightly BuildsGithub Action, click on a
successful build, scroll to the bottom and underArtifactsa Linux, Windows,
and MacOS tarball will be listed.Nightly Docker images of the server can be found under thePackagessection
of the Cryptol github repository.Server docker imagesRelease docker images for the Cryptol server are distributed with Cryptol
releases; nightly Cryptol servers are available under thePackagessection of the Cryptol repository.These images are set up to run as HTTPcryptol-remote-apiservers, e.g.:docker run --name=cryptol-remote-api -d \
  -p 8080:8080 \
  ghcr.io/galoisinc/cryptol-remote-api:nightly-portableThe-voption todocker runcan be used to load files into the docker
server's working directory so they can be loaded into the server at the request
of python scripts. E.g.,-v PATH_TO_FILES:/home/cryptol/files/will upload the
contents of the host machine's directoryPATH_TO_FILESto the/home/cryptol/files/directory in the docker container, which corresponds to the
relative pathfiles/for the Cryptol server. (If desired, it can be useful to
place files in a location in the Docker container such that the same relative
paths in scripts refer to the same files in the host machine and docker
container.)Building from SourceIf this repository is checked out and the build directions are successfully run,cabal v2-exec which cryptol-remote-apishould indicate where the server executable has
been stored bycabal.Alternativelycabal v2-install cryptol-remote-apishould install the server
executable into the user's~/.cabal/bindirectory (or similar), which (if
configured properly) should then appear ascryptol-remote-apiin a user'sPATH.Running Python Cryptol scriptsOnce the server is setup and any path variables are setup as desired, the
Python (>= v3.7) client can be installed usingpoetryas follows:$ cd cryptol-remote-api/python
$ poetry installThen the tests or individual scripts can be run as follows:$ poetry run python -m unittest discover tests/cryptol
$ poetry run python tests/cryptol/test_cryptol_api.pyIf leveraging environment variables is undesirable, the scripts themselves can
specify a command to launch the server, e.g.:cryptol.connect(COMMAND)whereCOMMANDis a command to launch a new Cryptol server in socket mode.Or a server URL can be specified directly in the script, e.g.:cryptol.connect(url=URL)There is a step-by-step examplehere.Running Cryptol Scripts from a clean server stateTo ensure any previous server state is cleared when running a Cryptol Python script
against a persistent server (e.g., one running in HTTP mode in a different process),
thereset_serverkeyword can be passed tocryptol.connect(). E.g.,cryptol.connect(url="http://localhost:8080/", reset_server=True)will connect to a Cryptol server running athttp://localhost:8080/and will
guarantee any previous state on the server is cleared.