Skip to content

Latest commit

 

History

History
141 lines (95 loc) · 5.78 KB

04-GeneratingCertificates.md

File metadata and controls

141 lines (95 loc) · 5.78 KB
Raw

Generating Certificates

This document will walk you through one way to generate a CA and self-signed certificate for use with Steward.

Two-way trust must be established between Steward and the Strategy Provider client for each request. To accomplish this, both the Server and Client will need TLS certificates and the CA certificate of the other party (Steward needs the client's CA, and the client needs Steward's CA). To make generating Steward's certificates easier, we've provided a convenience script called gen-certs.sh which can be found here. The script takes one optional flag for the output location of the certificates and their signing keys. The client CA will be set by default to Seven Seas' CA for now.

Steps

  1. Ensure you have OpenSSL installed.

This script requires OpenSSL to be installed; it will not work with LibreSSL.

Note that LibreSSL still uses the binary name openssl. You'll know if you have the wrong binary if openssl version says "LibreSSL". This script was tested against version OpenSSL 1.1.1n.

  1. Run the following command from the root of this repository
./gen-certs.sh -o some/output/location/

If you don't set the output path flag, certificates and keys will be created in the current working directory.

  1. Fill out the Server CA information

After running this command you run through a series of prompts. The first will be for information pertaining to the certificate authority like geographical location, email, etc. Set your CN to your domain name, and optionally set the OU for identification purposes. The rest of the fields can be safely left blank.

  1. Fill out the Server Certificate information

A similar set of prompts will ask for the same information for the Server (Steward) certificate which will be signed by the CA. As before, set your CN to your domain name, and optionally set the OU for identification purposes. Please leave the password blank. The rest of the fields can also be safely left blank.

  1. Provide your domain name

The final two prompts will ask for the domain name where Steward will be publically hosted. At least one of these MUST be set for Steward to start up with the certificate. Please do not use an IP address.

  1. (Optional) View your signed certificate

You can view your certificate plaintext with the following command:

openssl x509 -text -in <output_path>/server.crt

Valid TLS certificates will have "Version 3" near the top of the certificate plaintext. You should also see your domain name as a Subject Alternative Name.

  1. Test Steward with your certificate

A temporary test client CA can be used to verify your steward process is connectable from the network. The test client CA MUST BE REMOVED prior to running in production.

The test client CA is included in this repo at:

integration_tests/tls/client/test_client_ca.crt

Create a TOML config file with the [server] section containing the paths to your generated artifacts. See the configuration reference for more info. Your file will need to look something like this:

[server]
client_ca_cert_path = "integration_tests/tls/client/test_client_ca.crt" # this path is relative to the steward repository root
server_cert_path = "<output_path>/server.crt"
server_key_path = "<output_path>/server_key_pkcs8.pem"

You'll then need to start Steward and then send a gRPC request to it.

To start steward run

steward -c <config_toml_path> start

If you see something like the following log messages, so far so good:

INFO steward::commands::cosmos_mode: Starting application
INFO steward::commands::cosmos_mode: listening on 0.0.0.0:5734

Then you'll need to send a gRPC request to the endpoint (in the case above, 0.0.0.0:5734).

You can use your client of preference. Here is an example using grpcurl with the test client certs from this repo:

# execute with the steward repo root as your current working directory for the
# test cert relative paths to work
grpcurl -cert integration_tests/tls/client/test_client.crt \
	-key integration_tests/tls/client/test_client_key_pkcs8.pem \
	-cacert <output_path>/server_ca.crt \
	-d '' \
	<fqdn_of_server>:5734 \
	steward.v2.ContractCall/Submit

If you see a response like the following, then your process is accepting connections properly.

Resolved method descriptor:
// Handles simple contract call submission
rpc Submit ( .steward.v2.SubmitRequest ) returns ( .steward.v2.SubmitResponse );

Request metadata to send:
(empty)

Response headers received:
(empty)

Response trailers received:
content-type: application/grpc
date: Mon, 03 Oct 2022 19:00:02 GMT
Sent 0 requests and received 0 responses
ERROR:
  Code: PermissionDenied
  Message: cellar ID  not approved by governance

When you send this request, if you get an error to establishing a connection, there is probably something wrong with your configuration or your certificates.

An error like this one means the connection was established successfully:

# steward log
ERROR steward::cork: cork query client connection failed: transport error: error trying to connect: tcp connect error: Connection refused (os error 61)
# this is steward failing to connect to the Sommelier chain, which it would not be attempting
# if your client connection wasn't working.

# client log
ERROR:
  Code: Internal
  Message: failed to query chain to validate cellar id
  1. Remove testing configuration

In Production, steward must run without the client_ca_cert_path set. If you edited your production TOML file for testing, remove the client_ca_cert_path value from the [server] section.

client_ca_cert_path = "..." # remove this temporary line
  1. Provide your CA to the Strategy Provider

Add your information to the Steward Registry by following the steps outlined in the README there.