| Name | cryptol JSON |
| Version |
3.1.0
JSON |
| download |
| home_page | |
| Summary | Cryptol client for the Cryptol RPC server |
| upload_time | 2024-02-05 20:52:50 |
| maintainer | |
| docs_url | None |
| author | Galois, Inc. |
| requires_python | >=3.8.0,<4 |
| license | BSD License |
| keywords |
cryptography
verification
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Cryptol Python Client
In-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 the
[cryptol-remote-api](https://github.com/GaloisInc/cryptol/tree/master/cryptol-remote-api)
server.
# TL;DR Steps to running Cryptol Python scripts
1. Clone the repo
```
git clone https://github.com/GaloisInc/cryptol.git
```
2. Enter the repo
```
cd cryptol
```
3. Initialize git submodules
```
git submodule update --init
```
4. Navigate to the python client
```
cd cryptol-remote-api/python
```
5. Install and setup some version of the `cryptol-remote-api` server and update any
relevant environment variables as needed (see `cryptol.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/"
```
6. Install the Python client (requires Python v3.7 or newer -- we recommend using [`poetry`](https://python-poetry.org/docs/#installation) to install the package):
```
$ poetry install
```
7. Run tests or individual scripts:
```
$ poetry run python -m unittest discover tests/cryptol
$ poetry run python tests/cryptol/test_salsa20.py
```
# Python Client Installation (via Poetry)
First, clone the repository and submodules.
```
$ git clone https://github.com/GaloisInc/cryptol.git
$ cd cryptol
$ git submodule update --init
```
Then, use [`poetry`](https://python-poetry.org/docs/#installation) to install
the python client from the `cryptol-remote-api/python` directory:
```
$ cd cryptol-remote-api/python
$ poetry install
```
# Cryptol server
To run the verification scripts a `cryptol-remote-api` server must be available,
either as a local executable or running in docker image listening on a port.
## Connecting with a server in a script
Connecting to a server in a Python script is accomplished via the `cryptol.connect`
method. 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:
1. If the environment variable ``CRYPTOL_SERVER`` is set and refers to an
executable, it is assumed to be a `cryptol-remote-api` executable and will be
used for the duration of the script.
2. If the environment variable ``CRYPTOL_SERVER_URL`` is set, it is assumed to be
the URL for a running Cryptol server in ``http`` mode and will be connected to.
(N.B., this can be a local server or a server running in a docker image.)
3. If an executable ``cryptol-remote-api`` is available on the ``PATH`` it 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, the `reset_server` keyword 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 Server
There are several ways a server executable can be obtained.
### Server executables
An executable of the server is now included in each release of Cryptol.
Nightly server builds can be found as `Artifacts` of the [Nightly
Builds](https://github.com/GaloisInc/saw-script/actions/workflows/nightly.yml)
github action. I.e., go to the `Nightly Builds` Github Action, click on a
successful build, scroll to the bottom and under `Artifacts` a Linux, Windows,
and MacOS tarball will be listed.
Nightly Docker images of the server can be found under the
[Packages](https://github.com/orgs/GaloisInc/packages?repo_name=cryptol) section
of the Cryptol github repository.
### Server docker images
Release docker images for the Cryptol server are distributed with Cryptol
releases; nightly Cryptol servers are available under the
[Packages](https://github.com/orgs/GaloisInc/packages) section of the Cryptol repository.
These images are set up to run as HTTP `cryptol-remote-api` servers, e.g.:
```
docker run --name=cryptol-remote-api -d \
-p 8080:8080 \
ghcr.io/galoisinc/cryptol-remote-api:nightly-portable
```
The `-v` option to `docker run` can 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 directory `PATH_TO_FILES` to the
`/home/cryptol/files/` directory in the docker container, which corresponds to the
relative path `files/` 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 Source
If this repository is checked out and the build directions are successfully run,
`cabal v2-exec which cryptol-remote-api` should indicate where the server executable has
been stored by `cabal`.
Alternatively `cabal v2-install cryptol-remote-api` should install the server
executable into the user's `~/.cabal/bin` directory (or similar), which (if
configured properly) should then appear as `cryptol-remote-api` in a user's `PATH`.
# Running Python Cryptol scripts
Once the server is setup and any path variables are setup as desired, the
Python (>= v3.7) client can be installed using
[`poetry`](https://python-poetry.org/docs/#installation) as follows:
```
$ cd cryptol-remote-api/python
$ poetry install
```
Then 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.py
```
If leveraging environment variables is undesirable, the scripts themselves can
specify a command to launch the server, e.g.:
```
cryptol.connect(COMMAND)
```
where `COMMAND` is 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 example [here](GettingStarted.md).
## Running Cryptol Scripts from a clean server state
To 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),
the `reset_server` keyword can be passed to `cryptol.connect()`. E.g.,
```
cryptol.connect(url="http://localhost:8080/", reset_server=True)
```
will connect to a Cryptol server running at `http://localhost:8080/` and will
guarantee any previous state on the server is cleared.
Raw data
{
"_id": null,
"home_page": "",
"name": "cryptol",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8.0,<4",
"maintainer_email": "",
"keywords": "cryptography,verification",
"author": "Galois, Inc.",
"author_email": "cryptol-team@galois.com",
"download_url": "https://files.pythonhosted.org/packages/3b/e6/979eb543ccac9d8d1760a2d908d62b2560ce052b6747303fe2948f036c43/cryptol-3.1.0.tar.gz",
"platform": null,
"description": "# Cryptol Python Client\n\nIn-development Python client for Cryptol. Currently tested on Linux and MacOS --\nat present there may be some minor issues running the Python Client in a Windows\nenvironment that need to be addressed (e.g., some Python process management methods\nare not cross-OS-compatible).\n\nThis Cryptol client depends on the\n[cryptol-remote-api](https://github.com/GaloisInc/cryptol/tree/master/cryptol-remote-api)\nserver.\n\n# TL;DR Steps to running Cryptol Python scripts\n\n1. Clone the repo \n```\ngit clone https://github.com/GaloisInc/cryptol.git\n```\n2. Enter the repo\n```\ncd cryptol\n```\n3. Initialize git submodules \n```\ngit submodule update --init\n```\n4. Navigate to the python client\n```\ncd cryptol-remote-api/python\n```\n5. Install and setup some version of the `cryptol-remote-api` server and update any\n relevant environment variables as needed (see `cryptol.connect()` documentation\n for the various ways a server can be connected to).\n E.g., here is how the docker image of the server might be used:\n```\n$ docker run --name=cryptol-remote-api -d \\\n -v $PWD/tests/cryptol/test-files:/home/cryptol/tests/cryptol/test-files \\\n -p 8080:8080 \\\n ghcr.io/galoisinc/cryptol-remote-api:nightly-portable\n$ export CRYPTOL_SERVER_URL=\"http://localhost:8080/\"\n```\n6. Install the Python client (requires Python v3.7 or newer -- we recommend using [`poetry`](https://python-poetry.org/docs/#installation) to install the package):\n```\n$ poetry install \n```\n7. Run tests or individual scripts:\n```\n$ poetry run python -m unittest discover tests/cryptol\n$ poetry run python tests/cryptol/test_salsa20.py\n```\n\n# Python Client Installation (via Poetry)\n\nFirst, clone the repository and submodules.\n\n```\n$ git clone https://github.com/GaloisInc/cryptol.git\n$ cd cryptol\n$ git submodule update --init\n```\n\nThen, use [`poetry`](https://python-poetry.org/docs/#installation) to install\nthe python client from the `cryptol-remote-api/python` directory:\n\n```\n$ cd cryptol-remote-api/python\n$ poetry install\n```\n\n# Cryptol server\n\nTo run the verification scripts a `cryptol-remote-api` server must be available,\neither as a local executable or running in docker image listening on a port.\n\n## Connecting with a server in a script\n\nConnecting to a server in a Python script is accomplished via the `cryptol.connect`\nmethod. Its accompanying Python doc strings describe the various ways it can be\nused. Below is a brief summary:\n\n`cryptol.connect()`, when provided no arguments, will attempt the following in order:\n\n1. If the environment variable ``CRYPTOL_SERVER`` is set and refers to an\n executable, it is assumed to be a `cryptol-remote-api` executable and will be\n used for the duration of the script.\n2. If the environment variable ``CRYPTOL_SERVER_URL`` is set, it is assumed to be\n the URL for a running Cryptol server in ``http`` mode and will be connected to.\n (N.B., this can be a local server or a server running in a docker image.)\n3. If an executable ``cryptol-remote-api`` is available on the ``PATH`` it is\n assumed to be a Cryptol server and will be used for the duration of the script.\n\nAdditional arguments and options are documented with the function.\n\nNotably, the `reset_server` keyword can be used to connect to a running server\nand reset it, ensuring states from previous scripts have been cleared. E.g.,\n`cryptol.connect(reset_server=True)`.\n\n\n## Acquiring a Cryptol Server\n\nThere are several ways a server executable can be obtained.\n\n### Server executables\n\nAn executable of the server is now included in each release of Cryptol.\n\nNightly server builds can be found as `Artifacts` of the [Nightly\nBuilds](https://github.com/GaloisInc/saw-script/actions/workflows/nightly.yml)\ngithub action. I.e., go to the `Nightly Builds` Github Action, click on a\nsuccessful build, scroll to the bottom and under `Artifacts` a Linux, Windows,\nand MacOS tarball will be listed.\n\nNightly Docker images of the server can be found under the\n[Packages](https://github.com/orgs/GaloisInc/packages?repo_name=cryptol) section\nof the Cryptol github repository.\n\n### Server docker images\n\nRelease docker images for the Cryptol server are distributed with Cryptol\nreleases; nightly Cryptol servers are available under the\n[Packages](https://github.com/orgs/GaloisInc/packages) section of the Cryptol repository.\n\nThese images are set up to run as HTTP `cryptol-remote-api` servers, e.g.:\n\n```\ndocker run --name=cryptol-remote-api -d \\\n -p 8080:8080 \\\n ghcr.io/galoisinc/cryptol-remote-api:nightly-portable\n```\n\nThe `-v` option to `docker run` can be used to load files into the docker\nserver's working directory so they can be loaded into the server at the request\nof python scripts. E.g., `-v PATH_TO_FILES:/home/cryptol/files/` will upload the\ncontents of the host machine's directory `PATH_TO_FILES` to the\n`/home/cryptol/files/` directory in the docker container, which corresponds to the\nrelative path `files/` for the Cryptol server. (If desired, it can be useful to\nplace files in a location in the Docker container such that the same relative\npaths in scripts refer to the same files in the host machine and docker\ncontainer.)\n\n### Building from Source\n\nIf this repository is checked out and the build directions are successfully run,\n`cabal v2-exec which cryptol-remote-api` should indicate where the server executable has\nbeen stored by `cabal`.\n\nAlternatively `cabal v2-install cryptol-remote-api` should install the server\nexecutable into the user's `~/.cabal/bin` directory (or similar), which (if\nconfigured properly) should then appear as `cryptol-remote-api` in a user's `PATH`.\n\n\n# Running Python Cryptol scripts\n\nOnce the server is setup and any path variables are setup as desired, the\nPython (>= v3.7) client can be installed using\n[`poetry`](https://python-poetry.org/docs/#installation) as follows:\n\n```\n$ cd cryptol-remote-api/python\n$ poetry install\n```\n\nThen the tests or individual scripts can be run as follows:\n```\n$ poetry run python -m unittest discover tests/cryptol\n$ poetry run python tests/cryptol/test_cryptol_api.py\n```\n\nIf leveraging environment variables is undesirable, the scripts themselves can\nspecify a command to launch the server, e.g.:\n\n```\ncryptol.connect(COMMAND)\n```\n\nwhere `COMMAND` is a command to launch a new Cryptol server in socket mode.\n\nOr a server URL can be specified directly in the script, e.g.:\n\n```\ncryptol.connect(url=URL)\n```\n\nThere is a step-by-step example [here](GettingStarted.md).\n\n## Running Cryptol Scripts from a clean server state\n\nTo ensure any previous server state is cleared when running a Cryptol Python script\nagainst a persistent server (e.g., one running in HTTP mode in a different process),\nthe `reset_server` keyword can be passed to `cryptol.connect()`. E.g.,\n\n```\ncryptol.connect(url=\"http://localhost:8080/\", reset_server=True)\n```\n\nwill connect to a Cryptol server running at `http://localhost:8080/` and will\nguarantee any previous state on the server is cleared.\n",
"bugtrack_url": null,
"license": "BSD License",
"summary": "Cryptol client for the Cryptol RPC server",
"version": "3.1.0",
"project_urls": null,
"split_keywords": [
"cryptography",
"verification"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3ea59d9fbb506954eeb7ee9bb1f5b3bf52aea4f426b1557b59f1447d512f985f",
"md5": "77b5d9aecdf0f2860482f18c8f95cf88",
"sha256": "05ad03b80357c7589c925a5b09e8a9a3f11f6d471d726a1c1488d5742b0a2dba"
},
"downloads": -1,
"filename": "cryptol-3.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "77b5d9aecdf0f2860482f18c8f95cf88",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.0,<4",
"size": 37040,
"upload_time": "2024-02-05T20:52:48",
"upload_time_iso_8601": "2024-02-05T20:52:48.957168Z",
"url": "https://files.pythonhosted.org/packages/3e/a5/9d9fbb506954eeb7ee9bb1f5b3bf52aea4f426b1557b59f1447d512f985f/cryptol-3.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3be6979eb543ccac9d8d1760a2d908d62b2560ce052b6747303fe2948f036c43",
"md5": "35003876bd56b87ab84560ad0aa1d352",
"sha256": "101a74b381d65d2529b8b31b450f7c585cdb9f3a67a0a3a909ee46414cf23167"
},
"downloads": -1,
"filename": "cryptol-3.1.0.tar.gz",
"has_sig": false,
"md5_digest": "35003876bd56b87ab84560ad0aa1d352",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.0,<4",
"size": 31731,
"upload_time": "2024-02-05T20:52:50",
"upload_time_iso_8601": "2024-02-05T20:52:50.658861Z",
"url": "https://files.pythonhosted.org/packages/3b/e6/979eb543ccac9d8d1760a2d908d62b2560ce052b6747303fe2948f036c43/cryptol-3.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-05 20:52:50",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "cryptol"
}
