samply/beam-enroll repository overview

The tool in this repository is a helper tool for enrolling new endpoints in a Samply.Beam⁠ network.

Samply.Beam⁠ is a distributed task broker designed for efficient communication across strict network environments. It provides most commonly used communication patterns across strict network boundaries, end-to-end encryption and signatures, as well as certificate management and validation on top of an easy to use REST API. To provide authentication, end-to-end encryption, and ensure data integrity, Samply.Beam requires so called "public key cryptography". As it is implemented in Samply.Beam, this requires each site to have a secret "private key" and a publicly known "public certificate". This companion tool generates the private key and generates a "Certificate Sign Request" (CSR), a predecessor to the public certificate. This CSR can be used by the central CA operator to generate and sign the certificate.

⁠Usage

There are two ways to run the companion tool: First using Docker or second compiling and running it locally. In both cases you need to provide the intended ProxyID (see Beam Documentation⁠ for details). Therefore, the following commands expect the ProxyId in the environment varable $PROXY_ID and an output keyfile name in $PRIVATEKEXFILENAME. Per default, the beam proxy expects $PROXY_ID_SHOR.priv.pem.

⁠Docker

You can use the pre-compiled docker images in the Docker registry⁠:

docker run --rm -ti -v <path to beam proxy>/pki:/etc/bridgehead/pki samply/beam-enroll:latest --output-file $PRIVATEKEYFILENAME --proxy-id $PROXY_ID
chmod 600 $PRIVATEKEYFILENAME

⁠Manual

With an installed rust toolchain (at least Rust 1.65), first, clone the repository:

git clone https://github.com/samply/beam-enroll.git

Compile the application using cargo:

cd beam-enroll && cargo build --release

Last, execute the application:

./target/release/beam_enroll --proxy-id=$PROXY_ID

⁠Command Line Options

The Beam Certificate Enrollment Companion app supports the following command line parameters:

• proxy-id: The fully qualified proxy id, i.e. proxy1.broker.example.org
• output-file: Optional: Filename of the generated private key file. Defaults to ./pki/myprivatekey.pem
• admin-email: Optional: Provide your central Beam admin's email address for better on screen directions
• overwrite: Optional: Allow the companion tool to overwrite an existing private key file. Defaults to false

⁠Cryptography Notice

This distribution includes cryptographic software. The country in which you currently reside may have restrictions on the import, possession, use, and/or re-export to another country, of encryption software. BEFORE using any encryption software, please check your country's laws, regulations and policies concerning the import, possession, or use, and re-export of encryption software, to see if this is permitted. See http://www.wassenaar.org/⁠ for more information.