certs

package
v0.36.1 Latest Latest
Warning

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

 Go to latest Published: Feb 21, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

README

Certs Service

Issues X.509 certificates for things, enabling mTLS authentication.

Features

  • Issue certificates for things (RSA or ECDSA)
  • List certificates by thing ID
  • View certificate details by serial number
  • Renew certificates approaching expiration
  • Revoke certificates by serial number

Usage

First, obtain an authentication token:

TOK=$(curl -s -X POST http://localhost/tokens \
  -H 'Content-Type: application/json' \
  -d '{"email":"user@example.com","password":"12345678"}' | jq -r '.token')
Issue a certificate
curl -s -X POST http://localhost:8204/certs \
  -H "Authorization: Bearer $TOK" \
  -H 'Content-Type: application/json' \
  -d '{"thing_id":"<thing_id>", "key_bits":2048, "key_type":"rsa"}'

Supported key types: rsa (default), ec/ecdsa

List certificates for a thing
curl -s http://localhost:8204/certs?thing_id=<thing_id> \
  -H "Authorization: Bearer $TOK"
View a certificate
curl -s http://localhost:8204/certs/<serial> \
  -H "Authorization: Bearer $TOK"
Renew a certificate

Certificates can be renewed when they are within 30 days of expiration.

curl -s -X PUT http://localhost:8204/certs/<serial>/renew \
  -H "Authorization: Bearer $TOK"
Revoke a certificate
curl -s -X DELETE http://localhost:8204/certs/<serial> \
  -H "Authorization: Bearer $TOK"

Configuration

Environment Variable Description Default
MF_CERTS_SIGN_CA_PATH Path to CA certificate. ca.crt
MF_CERTS_SIGN_CA_KEY_PATH Path to CA private key ca.key
MF_CERTS_SIGN_HOURS_VALID Certificate validity period 2048h
MF_CERTS_SIGN_RSA_BITS RSA key size (if not specified in request) 2048

Documentation

Overview

Package certs contains the domain concept definitions needed to support Mainflux 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")
)

Functions

This section is empty.

Types

type Cert 

type Cert struct {
	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"`
	ExpiresAt      time.Time `json:"expires_at" mapstructure:"-"`
}

Cert defines the certificate parameters

type Config 

type Config struct {
	LogLevel       string
	ClientTLS      bool
	CaCerts        string
	HTTPPort       string
	ServerCert     string
	ServerKey      string
	CertsURL       string
	JaegerURL      string
	AuthURL        string
	AuthTimeout    time.Duration
	SignTLSCert    tls.Certificate
	SignX509Cert   *x509.Certificate
	SignRSABits    int
	SignHoursValid string
}

Config defines the service parameters

type Page 

type Page struct {
	Total 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
	RetrieveAll(ctx context.Context, offset, limit uint64) (Page, error)

	// Remove removes certificate from DB for a given serial
	Remove(ctx context.Context, serial string) error

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

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

	// RetrieveRevokedCerts retrieves all revoked certificates
	RetrieveRevokedCerts(ctx context.Context) ([]RevokedCert, 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 RevokedCert added in v0.32.1 

type RevokedCert struct {
	Serial    string    `db:"serial"`
	ThingID   string    `db:"thing_id"`
	RevokedAt time.Time `db:"revoked_at"`
}

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, keyBits int, keyType 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 numbers 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, serial string) (Cert, error)

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

	// RenewCert extends the expiration date of a certificate.
	RenewCert(ctx context.Context, token, serial string) (Cert, 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 protomfx.AuthServiceClient, things protomfx.ThingsServiceClient, certs Repository, config Config, pkiAgent pki.Agent) Service

New returns new Certs service.

Source Files

View all Source files

Directories

Path Synopsis
Package api contains implementation of certs service HTTP API.
 Package api contains implementation of certs service HTTP API.
Package postgres contains repository implementations using PostgreSQL as the underlying database.
 Package postgres contains repository implementations using PostgreSQL as the underlying database.
Package tracing contains middlewares that will add spans to existing traces.
 Package tracing contains middlewares that will add spans to existing traces.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.