trisads

README

TRISA Directory Service

Implements a simple gRPC directory service for TRISA.

This is a prototype implementation of a gRPC directory service that can act as a standalone server for VASP lookup queries. This is not intended to be used for production, but rather as a proof-of-concept (PoC) for directory service registration, lookups, and searches.

Generate Protocol Buffers

To regenerate the Go and Javascript code from the protocol buffers:

$ go generate ./...

The go generate directives are stored in pb/pb.go. The directives create grpc Go in the pb package as well as grpc-web in the web/src/pb directory.

Quick Start

The simplest way to get started is to use the docker-compose.yml file to get the following services running locally:

• trsisads: the TRISA directory service that implements the grpc protocol
• proxy: an envoy proxy that translates HTTP 1.1 requests into HTTP 2.0 requests
• dsui: UI that implements grpc-web to connect to the directory server via the proxy

Run the services as follows:

$ docker-compose up

Then connect to the UI on https://localhost:8000/

Development

For development purposes you'll want to run and reload the servers individually. To run the directory service:

$ go run ./cmd/trisads serve

Note that you'll likely want to have the following environment variables configured:

• $SECTIGO_USERNAME, $SECTIGO_PASSWORD: to access the Sectigo API
• $SENDGRID_API_KEY: sending verification emails and certificates

To run the development web UI server:

$ cd web
$ npx serve

Finally, to run the proxy, use the docker image, building if necessary:

$ docker run -n grpc-proxy trisacrypto/proxy:develop

Sectigo API

The directory service issues certificates using Sectigo, please refer to the API Documentation for more details on the endpoints and supported interactions. The sectigo package provides a simple client interface for interacting with the API; most of this code is handled by the server, but there is also a CLI interface that demonstrates usage.

To install the CLI server:

$ go install ./cmd/sectigo

This should add the sectigo command to your $PATH.

Authentication

The first step is authentication, you should set your username and password in the $SECTIGO_USERNAME and $SECTIGO_PASSWORD environment variables (alternatively you can pass them as parameters on the command line). To verify your authentication status you can use:

$ sectigo auth

The API authenticates by username and password then returns acess and refresh tokens which are stored in a local cache file. To see where your cache is stored:

$ sectigo auth --cache

If you'd like to check your credentials state, e.g. if the access tokens are valid, refreshable, or expired, use:

$ sectigo auth --debug

Authorities and Profiles

To begin to interact with certificates you need to list the authorities and profiles that your user account has access to.

$ sectigo authorities
[
  {
    "id": 1,
    "ecosystemId": 100,
    "signerCertificateId": 0,
    "ecosystemName": "TRISA",
    "balance": 10,
    "enabled": true,
    "profileId": 42,
    "profileName": "TRISA Profile"
  }
]

The authority displays the methods and profiles that certificates are created under. Here the profileId field is very important for use in subsequent calls. You can also view how many licenses have been ordered/issued across all authorities as follows:

$ sectigo licenses
{
  "ordered": 2,
  "issued": 2
}

To get detail information for a profile, use the profile ID with the following command:

$ sectigo profiles -i 42

This will return the raw profile configuration. Before creating certificates with the authority, you'll need to know the required profile parameters:

$ sectigo profile -i 42 --params

Creating Certificates

You can request a certificate to be created with the commonName and pkcs12Password params as follows (note for profiles that require other params, you'll have to use the code base directly and implement your own method):

$ sectigo create -a 42 -d example.com -p secrtpasswrd -b "example.com certs"
{
  "batchId": 24,
  "orderNumber": 1024,
  "creationDate": "2020-12-10T16:35:32.805+0000",
  "profile": "TRISA Profile",
  "size": 1,
  "status": "CREATED",
  "active": false,
  "batchName": "example.com certs",
  "rejectReason": "",
  "generatorParametersValues": null,
  "userId": 10,
  "downloadable": true,
  "rejectable": true
}

The -a flag specifies the authority, but should be a profile id. The domain must be a valid domain. If you don't specify a password, one is generated for you and printed on the CLI before exit. The -b flag gives a human readable name for the batch creation. The return data shows detail about the batch certificate job that was created; you can fetch the data to keep checking on the status as follows:

$ sectigo batches -i 24

You can also get processing information for the batch:

$ sectigo batches -i 24 --status

Once the batch is created, it's time to download the certificates in a ZIP file:

$ sectigo download -i 24 -o certs/

This will download the batch file (usually batchId.zip, 24.zip in this case) to the certs/ directory. Unzip the certs then decrypt the .pem file as follows:

$ unzip certs/24.zip
$ openssl pkcs12 -in certs/example.com.p12 -out certs/example.com.pem -nodes

For more on working with the PKCS12 file, see Export Certificates and Private Key from a PKCS#12 File with OpenSSL.

Managing Certificates

You can search for a certificate by name or serial number, but mostly commonly you search by the domain or common name to get the serial number:

$ sectigo find -n example.com

Once you've obtained the serial number you can revoke the certificate as follows:

$ sectigo revoke -p 42 -r "cessation of operation" -s 12345

This command expects the profile id that issued the certificate with the -p flag, an RFC 5280 reason code passed via the -r flag (unspecified by default), and the serial number of the certificate using the -s flag. If this command doesn't error, then the certificate has been successfully revoked.

The RFC 5280 reasons are:

• "unspecified"
• "keycompromise"
• "ca compromise"
• "affiliation changed"
• "superseded"
• "cessation of operation"
• "certificate hold"
• "remove from crl"
• "privilege withdrawn"
• "aa compromise"

Note that the reason is whitespace and case insensitive.

Documentation

Index

• Constants
• func Version() string
• type LogLevelDecoder
  • func (ll *LogLevelDecoder) Decode(value string) error
• type Server
  • func New(conf *Settings) (s *Server, err error)
  • func (s *Server) Lookup(ctx context.Context, in *pb.LookupRequest) (out *pb.LookupReply, err error)
  • func (s *Server) Register(ctx context.Context, in *pb.RegisterRequest) (out *pb.RegisterReply, err error)
  • func (s *Server) Search(ctx context.Context, in *pb.SearchRequest) (out *pb.SearchReply, err error)
  • func (s *Server) SendVerificationEmail(vasp pb.VASP) (err error)
  • func (s *Server) Serve() (err error)
  • func (s *Server) Shutdown() (err error)
• type Settings
  • func Config() (_ *Settings, err error)

Constants

const (
	VersionMajor = 1
	VersionMinor = 0
	VersionPatch = 0
)

Version component constants for the current build.

Functions

func Version

func Version() string

Version returns the semantic version for the current build.

Types

type LogLevelDecoder

type LogLevelDecoder zerolog.Level

LogLevelDecoder deserializes the log level from a config string.

func (*LogLevelDecoder) Decode

func (ll *LogLevelDecoder) Decode(value string) error

Decode implements envconfig.Decoder

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server implements the GRPC TRISADirectoryService.

func New

func New(conf *Settings) (s *Server, err error)

New creates a TRISA Directory Service with the specified configuration and prepares it to listen for and serve GRPC requests.

func (*Server) Lookup

func (s *Server) Lookup(ctx context.Context, in *pb.LookupRequest) (out *pb.LookupReply, err error)

Lookup a VASP entity by name or ID to get full details including the TRISA certification if it exists and the entity has been verified.

func (*Server) Register

func (s *Server) Register(ctx context.Context, in *pb.RegisterRequest) (out *pb.RegisterReply, err error)

Register a new VASP entity with the directory service. After registration, the new entity must go through the verification process to get issued a certificate. The status of verification can be obtained by using the lookup RPC call.

func (*Server) Search

func (s *Server) Search(ctx context.Context, in *pb.SearchRequest) (out *pb.SearchReply, err error)

Search for VASP entity records by name or by country in order to perform more detailed Lookup requests. The search process is purposefully simplistic at the moment.

func (*Server) SendVerificationEmail

func (s *Server) SendVerificationEmail(vasp pb.VASP) (err error)

SendVerificationEmail is a shortcut for iComply verification in which we simply send an email to the TRISA admins and have them manually verify registrations.

func (*Server) Serve

func (s *Server) Serve() (err error)

Serve GRPC requests on the specified address.

func (*Server) Shutdown

func (s *Server) Shutdown() (err error)

Shutdown the TRISA Directory Service gracefully

type Settings

type Settings struct {
	BindAddr        string          `envconfig:"TRISADS_BIND_ADDR" default:":4433"`
	DatabaseDSN     string          `envconfig:"TRISADS_DATABASE" required:"true"`
	SectigoUsername string          `envconfig:"SECTIGO_USERNAME" required:"false"`
	SectigoPassword string          `envconfig:"SECTIGO_PASSWORD" required:"false"`
	SendGridAPIKey  string          `envconfig:"SENDGRID_API_KEY" required:"false"`
	ServiceEmail    string          `envconfig:"TRISADS_SERVICE_EMAIL" default:"admin@vaspdirectory.net"`
	AdminEmail      string          `envconfig:"TRISADS_ADMIN_EMAIL" default:"admin@trisa.io"`
	LogLevel        LogLevelDecoder `envconfig:"TRISADS_LOG_LEVEL" default:"info"`
}

Settings uses envconfig to load required settings from the environment and validate them in preparation for running the TRISA Directory Service.

func Config

func Config() (_ *Settings, err error)

Config creates a new settings object, loading environment variables and defaults.