21 KiB
backend
import "github.com/effective-security/trustyca/server/service/backend"
Package backend implements the backend service (privpb.Backend): the CA of the service identities and the signing plane (DESIGN.md section 2.1). It serves every method of pb.CA with the org of the request named explicitly (the privpb copies of the pb.CA requests), owns the issuer registry and the CRL publisher of internal/ca, and is served by the backend listener only, to service identities over mTLS.
The CA service of the tenants (server/service/ca) forwards every call here with the org of the caller's token and the caller's context: in process when both run in one process, else over gRPC, where the backend interceptor authorizes the forwarded caller again. The RA and the operator call it directly and name the org of every request; the AIA calls SignOCSP. A method runs as its caller and checks the tenant scope of the request and of the rows it reaches (tenantScope).
The service is built by its Factory from the app container; a test calls it directly:
svc := backend.New(caDb, orgsDb, authorizer, registry)
res, err := svc.SignCertificate(ctx, &privpb.SignCertificateRequest{
OrgID: orgID,
Profile: "server",
Request: csrPEM,
})
Index
- Constants
- func Factory(server gserver.GServer) any
- type Service
- func New(caDb db.CaDb, orgsDb db.OrgsDb, authorizer authctx.Authorizer, registry *core.Registry) *Service
- func (s *Service) ActivateIssuer(ctx context.Context, req *privpb.ActivateIssuerRequest) (*pb.Issuer, error)
- func (s *Service) Close()
- func (s *Service) DeleteProfile(ctx context.Context, req *privpb.DeleteProfileRequest) (*emptypb.Empty, error)
- func (s *Service) GetCRL(ctx context.Context, req *privpb.GetCrlRequest) (*pb.CrlResponse, error)
- func (s *Service) GetCertificate(ctx context.Context, req *privpb.GetCertificateRequest) (*pb.CertificateResponse, error)
- func (s *Service) GetIssuer(ctx context.Context, req *privpb.GetIssuerRequest) (*pb.Issuer, error)
- func (s *Service) GetProfile(ctx context.Context, req *privpb.GetProfileRequest) (*pb.CertProfile, error)
- func (s *Service) GetSummary(ctx context.Context, req *privpb.GetSummaryRequest) (*pb.SummaryResponse, error)
- func (s *Service) ImportIssuer(ctx context.Context, req *privpb.ImportIssuerRequest) (*pb.Issuer, error)
- func (s *Service) IsReady() bool
- func (s *Service) ListCertificates(ctx context.Context, req *privpb.ListCertificatesRequest) (*pb.CertificatesResponse, error)
- func (s *Service) ListIssuers(ctx context.Context, req *privpb.ListIssuersRequest) (*pb.IssuersResponse, error)
- func (s *Service) ListProfiles(ctx context.Context, req *privpb.ListProfilesRequest) (*pb.ProfilesResponse, error)
- func (s *Service) ListRevokedCertificates(ctx context.Context, req *privpb.ListRevokedCertificatesRequest) (*pb.RevokedCertificatesResponse, error)
- func (s *Service) ListRoots(ctx context.Context, req *privpb.ListRootsRequest) (*pb.RootsResponse, error)
- func (s *Service) Name() string
- func (s *Service) PublishCrls(ctx context.Context, req *privpb.PublishCrlsRequest) (*pb.CrlsResponse, error)
- func (s *Service) RegisterGRPC(r *grpc.Server)
- func (s *Service) RegisterIssuer(ctx context.Context, req *privpb.RegisterIssuerRequest) (*pb.Issuer, error)
- func (s *Service) RegisterProfile(ctx context.Context, req *privpb.RegisterProfileRequest) (*pb.CertProfile, error)
- func (s *Service) RegisterRoot(ctx context.Context, req *privpb.RegisterRootRequest) (*pb.RootCertificate, error)
- func (s *Service) RevokeCertificate(ctx context.Context, req *privpb.RevokeCertificateRequest) (*pb.RevokedCertificateResponse, error)
- func (s *Service) SignCertificate(ctx context.Context, req *privpb.SignCertificateRequest) (*pb.CertificateResponse, error)
- func (s *Service) SignOCSP(ctx context.Context, req *pb.OCSPRequest) (*pb.OCSPResponse, error)
- func (s *Service) UpdateCertificateLabel(ctx context.Context, req *privpb.UpdateCertificateLabelRequest) (*pb.CertificateResponse, error)
- func (s *Service) UpdateIssuer(ctx context.Context, req *privpb.UpdateIssuerRequest) (*pb.Issuer, error)
Constants
EventSource is the source of the audit events the CA records
const EventSource = "ca"
ServiceName provides the Service Name for this package
const ServiceName = "backend"
func Factory
func Factory(server gserver.GServer) any
Factory returns a factory of the service
type Service
Service defines the backend service (privpb.Backend), the CA of the service identities and the signing plane (DESIGN.md section 2.1): every method of pb.CA with the org of the request named explicitly. Issuers and profiles are resolved from the DB through the issuer registry of internal/ca, which caches the built issuers per row, and CRLs are signed by its publisher, which the crl_renewal task shares. A method runs as its caller: the CA service of the same process passes its caller's context, the backend listener builds the context of a caller the WFE forwards (authctx.NewAuthUnaryBackendInterceptor), and a service identity (the RA, the operator, the AIA) acts as itself.
type Service struct {
// contains filtered or unexported fields
}
func New
func New(caDb db.CaDb, orgsDb db.OrgsDb, authorizer authctx.Authorizer, registry *core.Registry) *Service
New returns the backend service over the issuer registry; without a registry every method fails with Unavailable
func (*Service) ActivateIssuer
func (s *Service) ActivateIssuer(ctx context.Context, req *privpb.ActivateIssuerRequest) (*pb.Issuer, error)
ActivateIssuer sets the externally signed certificate of a Pending issuer of the org and activates it; the certificate must be for the key of the issuer and its chain must verify. A request that names a project activates an issuer of that project only.
func (*Service) Close
func (s *Service) Close()
Close the subservices and its resources
func (*Service) DeleteProfile
func (s *Service) DeleteProfile(ctx context.Context, req *privpb.DeleteProfileRequest) (*emptypb.Empty, error)
DeleteProfile deletes a profile of the org; a request that names a project deletes a profile of that project only
func (*Service) GetCRL
func (s *Service) GetCRL(ctx context.Context, req *privpb.GetCrlRequest) (*pb.CrlResponse, error)
GetCRL returns the current CRL of the issuer with the key identifier. A tenant reads the CRLs of its org: the CRL of another org, of the platform or of a project the caller cannot read is not found. A trusted service caller that names no org (CIS) reads the CRL of any issuer, since CRLs are public.
func (*Service) GetCertificate
func (s *Service) GetCertificate(ctx context.Context, req *privpb.GetCertificateRequest) (*pb.CertificateResponse, error)
GetCertificate returns a certificate of the org by its ID, its Subject Key Identifier (the newest one of the key), its SHA-256 thumbprint, or the key identifier of its issuer and its serial number. A certificate of another org, or of a project the caller cannot read, is not found.
func (*Service) GetIssuer
func (s *Service) GetIssuer(ctx context.Context, req *privpb.GetIssuerRequest) (*pb.Issuer, error)
GetIssuer returns an issuer of the org by ID, by label resolved in the project then in the org, or by IKID. An issuer found by ID or IKID must be of a project the caller can read, or org-wide (tenantScope.RowAccess).
func (*Service) GetProfile
func (s *Service) GetProfile(ctx context.Context, req *privpb.GetProfileRequest) (*pb.CertProfile, error)
GetProfile returns a profile of the org by ID, or by label resolved in the project then in the org
func (*Service) GetSummary
func (s *Service) GetSummary(ctx context.Context, req *privpb.GetSummaryRequest) (*pb.SummaryResponse, error)
GetSummary returns the counts of the tenant's dashboard: the issuers by status, the certificates by status and the Active ones that expire within 7, 30 and 90 days, and the issuers that publish CRLs by the state of their CRL. The scope is the org, the project the request names (or the project of a restricted API key) or, for a member with project grants only, the org-wide rows and those of its projects, as the lists cover them. The counts are read at one snapshot (db.GetSummaryCounts) and from the tables only, so a backend without an issuer registry serves them.
func (*Service) ImportIssuer
func (s *Service) ImportIssuer(ctx context.Context, req *privpb.ImportIssuerRequest) (*pb.Issuer, error)
ImportIssuer registers an issuer from an existing certificate and key: a key in a crypto provider by its URI, or a PEM key that is stored wrapped. The chain must verify to the given or the self-signed root.
func (*Service) IsReady
func (s *Service) IsReady() bool
IsReady indicates that the service is ready to serve its end-points
func (*Service) ListCertificates
func (s *Service) ListCertificates(ctx context.Context, req *privpb.ListCertificatesRequest) (*pb.CertificatesResponse, error)
ListCertificates returns the certificates of the org, newest first: of the project of the request, or of the org-wide scope and every project the caller may read (DESIGN.md section 3.3)
func (*Service) ListIssuers
func (s *Service) ListIssuers(ctx context.Context, req *privpb.ListIssuersRequest) (*pb.IssuersResponse, error)
ListIssuers returns the issuers of the org, newest first; a project limits the result to its own issuers. Without a project, a member with project grants only lists the org-wide issuers and those of its projects. IDs and IKIDs (the key identifiers the certificates carry) narrow the list to the issuers of a page of certificates, at most maxListKeys each; an issuer outside the scope is not returned.
func (*Service) ListProfiles
func (s *Service) ListProfiles(ctx context.Context, req *privpb.ListProfilesRequest) (*pb.ProfilesResponse, error)
ListProfiles returns the profiles of the org, newest first; a project limits the result to its own profiles. Without a project, a member with project grants only lists the org-wide profiles and those of its projects. IDs and Labels narrow the list to the profiles of a page of certificates, at most maxListKeys each; a profile outside the scope is not returned.
func (*Service) ListRevokedCertificates
func (s *Service) ListRevokedCertificates(ctx context.Context, req *privpb.ListRevokedCertificatesRequest) (*pb.RevokedCertificatesResponse, error)
ListRevokedCertificates returns the revoked certificates of the org with their revocation, newest revocation first, in the scope of the request as ListCertificates does
func (*Service) ListRoots
func (s *Service) ListRoots(ctx context.Context, req *privpb.ListRootsRequest) (*pb.RootsResponse, error)
ListRoots returns the trust anchors of the org, newest first; a trusted service caller that names no org lists the platform anchors
func (*Service) Name
func (s *Service) Name() string
Name returns the service name
func (*Service) PublishCrls
func (s *Service) PublishCrls(ctx context.Context, req *privpb.PublishCrlsRequest) (*pb.CrlsResponse, error)
PublishCrls publishes the CRLs that are due, or every CRL in scope when forced, and returns the CRLs it published. A tenant publishes for the issuers of its org: the one of the IKID, which must belong to the project when the request names one; the Active and Archived issuers of the project the request names, or of a restricted API key; or else the org-wide issuers and those of the projects the caller may read. A trusted service caller that names no org publishes for every org and the platform, as the crl_renewal task does in-process. An issuer that does not publish CRLs (Pending, Destroyed, expired) is refused with a precondition failure when named by its IKID; in a scope it is skipped, and an issuer whose CRL fails is logged and counted, so the request fails after the others are published. Every published CRL records a CrlPublished event before the request fails, since a retry finds those CRLs fresh.
func (*Service) RegisterGRPC
func (s *Service) RegisterGRPC(r *grpc.Server)
RegisterGRPC registers gRPC handler
func (*Service) RegisterIssuer
func (s *Service) RegisterIssuer(ctx context.Context, req *privpb.RegisterIssuerRequest) (*pb.Issuer, error)
RegisterIssuer creates an issuer of the org (DESIGN.md section 5.2): a self-signed root when the type is Root, an issuer signed by the parent when ParentID is set, otherwise a Pending issuer with its CSR. The key is generated in the crypto provider and never leaves it; a software key is stored wrapped.
func (*Service) RegisterProfile
func (s *Service) RegisterProfile(ctx context.Context, req *privpb.RegisterProfileRequest) (*pb.CertProfile, error)
RegisterProfile creates a profile of the org or of the project, or replaces the one with the same label in the same scope. The profile is validated as the authority will sign with it; its issuer label binds it to an issuer of the org, or to any issuer that allows it.
func (*Service) RegisterRoot
func (s *Service) RegisterRoot(ctx context.Context, req *privpb.RegisterRootRequest) (*pb.RootCertificate, error)
RegisterRoot registers a self-signed CA certificate as a trust anchor of the org; registering it again updates its trust
func (*Service) RevokeCertificate
func (s *Service) RevokeCertificate(ctx context.Context, req *privpb.RevokeCertificateRequest) (*pb.RevokedCertificateResponse, error)
RevokeCertificate revokes a certificate of the org, named by its ID, its Subject Key Identifier or its issuer and serial number: the revocation and the status of the certificate are written in one transaction (db.RevokeCertificate), then the CertificateRevoked event is recorded. A revoked certificate is refused with a precondition failure, and the reason RemoveFromCRL, which releases a certificate from hold (RFC 5280 section 5.3.1), is refused since hold removal is not implemented. The request names the project of the certificate when the caller's role is granted there only; a certificate of another project is then not found.
func (*Service) SignCertificate
func (s *Service) SignCertificate(ctx context.Context, req *privpb.SignCertificateRequest) (*pb.CertificateResponse, error)
SignCertificate signs a certificate request with the issuer of the profile, resolved in the scope of the request (DESIGN.md section 6), and records the certificate with its issue event in one transaction.
func (*Service) SignOCSP
func (s *Service) SignOCSP(ctx context.Context, req *pb.OCSPRequest) (*pb.OCSPResponse, error)
SignOCSP signs an OCSP response for the certificate of the request: good for a registered certificate, revoked with the reason and time of its revocation, and unknown for a serial the issuer never registered.
func (*Service) UpdateCertificateLabel
func (s *Service) UpdateCertificateLabel(ctx context.Context, req *privpb.UpdateCertificateLabelRequest) (*pb.CertificateResponse, error)
UpdateCertificateLabel replaces the label a client gave a certificate, and its client metadata when the request carries any. The request names the project of the certificate when the caller's role is granted there only (the interceptor authorizes that scope); a certificate of another project is then not found. There is no event type for the change: it is logged, not recorded in the audit trail.
func (*Service) UpdateIssuer
func (s *Service) UpdateIssuer(ctx context.Context, req *privpb.UpdateIssuerRequest) (*pb.Issuer, error)
UpdateIssuer replaces the runtime settings of an issuer of the org, or moves it along its lifecycle: Active to Archived, Archived to Destroyed. Destroying an issuer removes its key from the crypto provider when the provider manages keys, and clears a wrapped software key. A request that names a project changes an issuer of that project only.
Generated by gomarkdoc