certs

package
v1.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 23, 2024 License: Apache-2.0 Imports: 12 Imported by: 0

README

Certs Service

Issues certificates for things. Certs service can create certificates to be used when Magistrala is deployed to support mTLS. Certificate service can create certificates using PKI mode - where certificates issued by PKI, when you deploy Vault as PKI certificate management cert service will proxy requests to Vault previously checking access rights and saving info on successfully created certificate.

PKI mode

When MG_CERTS_VAULT_HOST is set it is presumed that Vault is installed and certs service will issue certificates using Vault API. First you'll need to set up Vault. To setup Vault follow steps in Build Your Own Certificate Authority (CA).

For lab purposes you can use docker-compose and script for setting up PKI in https://github.com/andychao217/magistrala/blob/main/docker/addons/vault/README.md

MG_CERTS_VAULT_HOST=<https://vault-domain:8200>
MG_CERTS_VAULT_NAMESPACE=<vault_namespace> 
MG_CERTS_VAULT_APPROLE_ROLEID=<vault_approle_roleid> 
MG_CERTS_VAULT_APPROLE_SECRET=<vault_approle_sceret> 
MG_CERTS_VAULT_THINGS_CERTS_PKI_PATH=<vault_things_certs_pki_path> 
MG_CERTS_VAULT_THINGS_CERTS_PKI_ROLE_NAME=<vault_things_certs_issue_role_name> 

The certificates can also be revoked using certs service. To revoke a certificate you need to provide thing_id of the thing for which the certificate was issued.

curl -s -S -X DELETE http://localhost:9019/certs/revoke -H "Authorization: Bearer $TOK" -H 'Content-Type: application/json'   -d '{"thing_id":"c30b8842-507c-4bcd-973c-74008cef3be5"}'

Configuration

The service is configured using the environment variables presented in the following table. Note that any unset variables will be replaced with their default values.

Variable Description Default
MG_CERTS_LOG_LEVEL Log level for the Certs (debug, info, warn, error) info
MG_CERTS_HTTP_HOST Service Certs host ""
MG_CERTS_HTTP_PORT Service Certs port 9019
MG_CERTS_HTTP_SERVER_CERT Path to the PEM encoded server certificate file ""
MG_CERTS_HTTP_SERVER_KEY Path to the PEM encoded server key file ""
MG_AUTH_GRPC_URL Auth service gRPC URL localhost:8181
MG_AUTH_GRPC_TIMEOUT Auth service gRPC request timeout in seconds 1s
MG_AUTH_GRPC_CLIENT_CERT Path to the PEM encoded auth service gRPC client certificate file ""
MG_AUTH_GRPC_CLIENT_KEY Path to the PEM encoded auth service gRPC client key file ""
MG_AUTH_GRPC_SERVER_CERTS Path to the PEM encoded auth server gRPC server trusted CA certificate file ""
MG_CERTS_SIGN_CA_PATH Path to the PEM encoded CA certificate file ca.crt
MG_CERTS_SIGN_CA_KEY_PATH Path to the PEM encoded CA key file ca.key
MG_CERTS_VAULT_HOST Vault host http://vault:8200
MG_CERTS_VAULT_NAMESPACE Vault namespace in which pki is present magistrala
MG_CERTS_VAULT_APPROLE_ROLEID Vault AppRole auth RoleID magistrala
MG_CERTS_VAULT_APPROLE_SECRET Vault AppRole auth Secret magistrala
MG_CERTS_VAULT_THINGS_CERTS_PKI_PATH Vault PKI path for issuing Things Certificates pki_int
MG_CERTS_VAULT_THINGS_CERTS_PKI_ROLE_NAME Vault PKI Role Name for issuing Things Certificates magistrala_things_certs
MG_CERTS_DB_HOST Database host localhost
MG_CERTS_DB_PORT Database port 5432
MG_CERTS_DB_PASS Database password magistrala
MG_CERTS_DB_USER Database user magistrala
MG_CERTS_DB_NAME Database name certs
MG_CERTS_DB_SSL_MODE Database SSL mode disable
MG_CERTS_DB_SSL_CERT Database SSL certificate ""
MG_CERTS_DB_SSL_KEY Database SSL key ""
MG_CERTS_DB_SSL_ROOT_CERT Database SSL root certificate ""
MG_THINGS_URL Things service URL localhost:9000
MG_JAEGER_URL Jaeger server URL http://localhost:14268/api/traces
MG_JAEGER_TRACE_RATIO Jaeger sampling ratio 1.0
MG_SEND_TELEMETRY Send telemetry to magistrala call home server true
MG_CERTS_INSTANCE_ID Service instance ID ""

Deployment

The service is distributed as Docker container. Check the certs service section in docker-compose file to see how the service is deployed.

Running this service outside of container requires working instance of the auth service, things service, postgres database, vault and Jaeger server. To start the service outside of the container, execute the following shell script:

# download the latest version of the service
git clone https://github.com/andychao217/magistrala

cd magistrala

# compile the certs
make certs

# copy binary to bin
make install

# set the environment variables and run the service
MG_CERTS_LOG_LEVEL=info \
MG_CERTS_HTTP_HOST=localhost \
MG_CERTS_HTTP_PORT=9019 \
MG_CERTS_HTTP_SERVER_CERT="" \
MG_CERTS_HTTP_SERVER_KEY="" \
MG_AUTH_GRPC_URL=localhost:8181 \
MG_AUTH_GRPC_TIMEOUT=1s \
MG_AUTH_GRPC_CLIENT_CERT="" \
MG_AUTH_GRPC_CLIENT_KEY="" \
MG_AUTH_GRPC_SERVER_CERTS="" \
MG_CERTS_SIGN_CA_PATH=ca.crt \
MG_CERTS_SIGN_CA_KEY_PATH=ca.key \
MG_CERTS_VAULT_HOST=http://vault:8200 \
MG_CERTS_VAULT_NAMESPACE=magistrala \
MG_CERTS_VAULT_APPROLE_ROLEID=magistrala \
MG_CERTS_VAULT_APPROLE_SECRET=magistrala \
MG_CERTS_VAULT_THINGS_CERTS_PKI_PATH=pki_int \
MG_CERTS_VAULT_THINGS_CERTS_PKI_ROLE_NAME=magistrala_things_certs \
MG_CERTS_DB_HOST=localhost \
MG_CERTS_DB_PORT=5432 \
MG_CERTS_DB_PASS=magistrala \
MG_CERTS_DB_USER=magistrala \
MG_CERTS_DB_NAME=certs \
MG_CERTS_DB_SSL_MODE=disable \
MG_CERTS_DB_SSL_CERT="" \
MG_CERTS_DB_SSL_KEY="" \
MG_CERTS_DB_SSL_ROOT_CERT="" \
MG_THINGS_URL=localhost:9000 \
MG_JAEGER_URL=http://localhost:14268/api/traces \
MG_JAEGER_TRACE_RATIO=1.0 \
MG_SEND_TELEMETRY=true \
MG_CERTS_INSTANCE_ID="" \
$GOBIN/magistrala-certs

Setting MG_CERTS_HTTP_SERVER_CERT and MG_CERTS_HTTP_SERVER_KEY will enable TLS against the service. The service expects a file in PEM format for both the certificate and the key.

Setting MG_AUTH_GRPC_CLIENT_CERT and MG_AUTH_GRPC_CLIENT_KEY will enable TLS against the auth service. The service expects a file in PEM format for both the certificate and the key. Setting MG_AUTH_GRPC_SERVER_CERTS will enable TLS against the auth service trusting only those CAs that are provided. The service expects a file in PEM format of trusted CAs.

Usage

For more information about service capabilities and its usage, please check out the Certs section.

Documentation

Overview

Package certs contains the domain concept definitions needed to support Magistrala certs service functionality.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrFailedCertCreation failed to create certificate.
	ErrFailedCertCreation = errors.New("failed to create client certificate")

	// ErrFailedCertRevocation failed to revoke certificate.
	ErrFailedCertRevocation = errors.New("failed to revoke certificate")

	ErrFailedToRemoveCertFromDB = errors.New("failed to remove cert serial from db")

	ErrFailedReadFromPKI = errors.New("failed to read certificate from PKI")
)
View Source
var ErrMissingCerts = errors.New("CA path or CA key path not set")

Functions

func LoadCertificates

func LoadCertificates(caPath, caKeyPath string) (tls.Certificate, *x509.Certificate, error)

func ReadCert

func ReadCert(b []byte) (*x509.Certificate, error)

Types

type Cert

type Cert struct {
	OwnerID        string    `json:"owner_id" mapstructure:"owner_id"`
	ThingID        string    `json:"thing_id" mapstructure:"thing_id"`
	ClientCert     string    `json:"client_cert" mapstructure:"certificate"`
	IssuingCA      string    `json:"issuing_ca" mapstructure:"issuing_ca"`
	CAChain        []string  `json:"ca_chain" mapstructure:"ca_chain"`
	ClientKey      string    `json:"client_key" mapstructure:"private_key"`
	PrivateKeyType string    `json:"private_key_type" mapstructure:"private_key_type"`
	Serial         string    `json:"serial" mapstructure:"serial_number"`
	Expire         time.Time `json:"expire" mapstructure:"-"`
}

Cert defines the certificate paremeters.

type Page

type Page struct {
	Total  uint64
	Offset uint64
	Limit  uint64
	Certs  []Cert
}

ConfigsPage contains page related metadata as well as list.

type Repository

type Repository interface {
	// Save  saves cert for thing into database
	Save(ctx context.Context, cert Cert) (string, error)

	// RetrieveAll retrieve issued certificates for given owner ID
	RetrieveAll(ctx context.Context, ownerID string, offset, limit uint64) (Page, error)

	// Remove removes certificate from DB for a given thing ID
	Remove(ctx context.Context, ownerID, thingID string) error

	// RetrieveByThing retrieves issued certificates for a given thing ID
	RetrieveByThing(ctx context.Context, ownerID, thingID string, offset, limit uint64) (Page, error)

	// RetrieveBySerial retrieves a certificate for a given serial ID
	RetrieveBySerial(ctx context.Context, ownerID, serialID string) (Cert, error)
}

Repository specifies a Config persistence API.

type Revoke

type Revoke struct {
	RevocationTime time.Time `mapstructure:"revocation_time"`
}

Revoke defines the conditions to revoke a certificate.

type Service

type Service interface {
	// IssueCert issues certificate for given thing id if access is granted with token
	IssueCert(ctx context.Context, token, thingID, ttl string) (Cert, error)

	// ListCerts lists certificates issued for a given thing ID
	ListCerts(ctx context.Context, token, thingID string, offset, limit uint64) (Page, error)

	// ListSerials lists certificate serial IDs issued for a given thing ID
	ListSerials(ctx context.Context, token, thingID string, offset, limit uint64) (Page, error)

	// ViewCert retrieves the certificate issued for a given serial ID
	ViewCert(ctx context.Context, token, serialID string) (Cert, error)

	// RevokeCert revokes a certificate for a given serial ID
	RevokeCert(ctx context.Context, token, serialID string) (Revoke, error)
}

Service specifies an API that must be fulfilled by the domain service implementation, and all of its decorators (e.g. logging & metrics).

func New

func New(auth magistrala.AuthServiceClient, certs Repository, sdk mgsdk.SDK, pkiAgent pki.Agent) Service

New returns new Certs service.

Directories

Path Synopsis
Package api contains implementation of certs service HTTP API.
Package api contains implementation of certs service HTTP API.
Package mocks contains mocks for testing purposes.
Package mocks contains mocks for testing purposes.
Package pki contains the domain concept definitions needed to support Magistrala Certs service functionality.
Package pki contains the domain concept definitions needed to support Magistrala Certs service functionality.
Package postgres contains repository implementations using PostgreSQL as the underlying database.
Package postgres contains repository implementations using PostgreSQL as the underlying database.
Package tracing provides tracing instrumentation for Magistrala Users Groups service.
Package tracing provides tracing instrumentation for Magistrala Users Groups service.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL