sa.proto

syntax = "proto3";

package sa;
option go_package = "github.com/letsencrypt/boulder/sa/proto";

import "core/proto/core.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/timestamp.proto";

// StorageAuthorityReadOnly exposes only those SA methods which are read-only.
service StorageAuthorityReadOnly {
  rpc CountCertificatesByNames(CountCertificatesByNamesRequest) returns (CountByNames) {}
  rpc CountFQDNSets(CountFQDNSetsRequest) returns (Count) {}
  rpc CountInvalidAuthorizations2(CountInvalidAuthorizationsRequest) returns (Count) {}
  rpc CountOrders(CountOrdersRequest) returns (Count) {}
  rpc CountPendingAuthorizations2(RegistrationID) returns (Count) {}
  rpc CountRegistrationsByIP(CountRegistrationsByIPRequest) returns (Count) {}
  rpc CountRegistrationsByIPRange(CountRegistrationsByIPRequest) returns (Count) {}
  rpc FQDNSetExists(FQDNSetExistsRequest) returns (Exists) {}
  rpc FQDNSetTimestampsForWindow(CountFQDNSetsRequest) returns (Timestamps) {}
  rpc GetAuthorization2(AuthorizationID2) returns (core.Authorization) {}
  rpc GetAuthorizations2(GetAuthorizationsRequest) returns (Authorizations) {}
  rpc GetCertificate(Serial) returns (core.Certificate) {}
  rpc GetCertificateStatus(Serial) returns (core.CertificateStatus) {}
  rpc GetMaxExpiration(google.protobuf.Empty) returns (google.protobuf.Timestamp) {}
  rpc GetOrder(OrderRequest) returns (core.Order) {}
  rpc GetOrderForNames(GetOrderForNamesRequest) returns (core.Order) {}
  rpc GetPendingAuthorization2(GetPendingAuthorizationRequest) returns (core.Authorization) {}
  rpc GetRegistration(RegistrationID) returns (core.Registration) {}
  rpc GetRegistrationByKey(JSONWebKey) returns (core.Registration) {}
  rpc GetRevocationStatus(Serial) returns (RevocationStatus) {}
  rpc GetRevokedCerts(GetRevokedCertsRequest) returns (stream core.CRLEntry) {}
  rpc GetSerialMetadata(Serial) returns (SerialMetadata) {}
  rpc GetValidAuthorizations2(GetValidAuthorizationsRequest) returns (Authorizations) {}
  rpc GetValidOrderAuthorizations2(GetValidOrderAuthorizationsRequest) returns (Authorizations) {}
  rpc IncidentsForSerial(Serial) returns (Incidents) {}
  rpc KeyBlocked(KeyBlockedRequest) returns (Exists) {}
  rpc PreviousCertificateExists(PreviousCertificateExistsRequest) returns (Exists) {}
  rpc SerialsForIncident (SerialsForIncidentRequest) returns (stream IncidentSerial) {}
}

// StorageAuthority provides full read/write access to the database.
service StorageAuthority {
  // Getters: this list must be identical to the StorageAuthorityReadOnly rpcs.
  rpc CountCertificatesByNames(CountCertificatesByNamesRequest) returns (CountByNames) {}
  rpc CountFQDNSets(CountFQDNSetsRequest) returns (Count) {}
  rpc CountInvalidAuthorizations2(CountInvalidAuthorizationsRequest) returns (Count) {}
  rpc CountOrders(CountOrdersRequest) returns (Count) {}
  rpc CountPendingAuthorizations2(RegistrationID) returns (Count) {}
  rpc CountRegistrationsByIP(CountRegistrationsByIPRequest) returns (Count) {}
  rpc CountRegistrationsByIPRange(CountRegistrationsByIPRequest) returns (Count) {}
  rpc FQDNSetExists(FQDNSetExistsRequest) returns (Exists) {}
  rpc FQDNSetTimestampsForWindow(CountFQDNSetsRequest) returns (Timestamps) {}
  rpc GetAuthorization2(AuthorizationID2) returns (core.Authorization) {}
  rpc GetAuthorizations2(GetAuthorizationsRequest) returns (Authorizations) {}
  rpc GetCertificate(Serial) returns (core.Certificate) {}
  rpc GetCertificateStatus(Serial) returns (core.CertificateStatus) {}
  rpc GetMaxExpiration(google.protobuf.Empty) returns (google.protobuf.Timestamp) {}
  rpc GetOrder(OrderRequest) returns (core.Order) {}
  rpc GetOrderForNames(GetOrderForNamesRequest) returns (core.Order) {}
  rpc GetPendingAuthorization2(GetPendingAuthorizationRequest) returns (core.Authorization) {}
  rpc GetRegistration(RegistrationID) returns (core.Registration) {}
  rpc GetRegistrationByKey(JSONWebKey) returns (core.Registration) {}
  rpc GetRevocationStatus(Serial) returns (RevocationStatus) {}
  rpc GetRevokedCerts(GetRevokedCertsRequest) returns (stream core.CRLEntry) {}
  rpc GetSerialMetadata(Serial) returns (SerialMetadata) {}
  rpc GetValidAuthorizations2(GetValidAuthorizationsRequest) returns (Authorizations) {}
  rpc GetValidOrderAuthorizations2(GetValidOrderAuthorizationsRequest) returns (Authorizations) {}
  rpc IncidentsForSerial(Serial) returns (Incidents) {}
  rpc KeyBlocked(KeyBlockedRequest) returns (Exists) {}
  rpc PreviousCertificateExists(PreviousCertificateExistsRequest) returns (Exists) {}
  rpc SerialsForIncident (SerialsForIncidentRequest) returns (stream IncidentSerial) {}
  // Adders
  rpc AddBlockedKey(AddBlockedKeyRequest) returns (google.protobuf.Empty) {}
  rpc AddCertificate(AddCertificateRequest) returns (google.protobuf.Empty) {}
  rpc AddPrecertificate(AddCertificateRequest) returns (google.protobuf.Empty) {}
  rpc SetCertificateStatusReady(Serial) returns (google.protobuf.Empty) {}
  rpc AddSerial(AddSerialRequest) returns (google.protobuf.Empty) {}
  rpc DeactivateAuthorization2(AuthorizationID2) returns (google.protobuf.Empty) {}
  rpc DeactivateRegistration(RegistrationID) returns (google.protobuf.Empty) {}
  rpc FinalizeAuthorization2(FinalizeAuthorizationRequest) returns (google.protobuf.Empty) {}
  rpc FinalizeOrder(FinalizeOrderRequest) returns (google.protobuf.Empty) {}
  rpc NewOrderAndAuthzs(NewOrderAndAuthzsRequest) returns (core.Order) {}
  rpc NewRegistration(core.Registration) returns (core.Registration) {}
  rpc RevokeCertificate(RevokeCertificateRequest) returns (google.protobuf.Empty) {}
  rpc SetOrderError(SetOrderErrorRequest) returns (google.protobuf.Empty) {}
  rpc SetOrderProcessing(OrderRequest) returns (google.protobuf.Empty) {}
  rpc UpdateRegistration(core.Registration) returns (google.protobuf.Empty) {}
  rpc UpdateRevokedCertificate(RevokeCertificateRequest) returns (google.protobuf.Empty) {}
  rpc LeaseCRLShard(LeaseCRLShardRequest) returns (LeaseCRLShardResponse) {}
  rpc UpdateCRLShard(UpdateCRLShardRequest) returns (google.protobuf.Empty) {}
}

message RegistrationID {
  int64 id = 1;
}

message JSONWebKey {
  bytes jwk = 1; 
}

message AuthorizationID {
  string id = 1;
}

message GetPendingAuthorizationRequest {
  int64 registrationID = 1;
  string identifierType = 2;
  string identifierValue = 3;
  // Result must be valid until at least this Unix timestamp (nanos)
  int64 validUntil = 4;
}

message GetValidAuthorizationsRequest {
  int64 registrationID = 1;
  repeated string domains = 2;
  int64 now = 3; // Unix timestamp (nanoseconds)
}

message ValidAuthorizations {
  message MapElement {
          string domain = 1;
          core.Authorization authz = 2;
  }
  repeated MapElement valid = 1;
}

message Serial {
  string serial = 1;
}

message SerialMetadata {
  string serial = 1;
  int64 registrationID = 2;
  int64 created = 3; // Unix timestamp (nanoseconds)
  int64 expires = 4; // Unix timestamp (nanoseconds)
}

message Range {
  int64 earliest = 1; // Unix timestamp (nanoseconds)
  int64 latest = 2;   // Unix timestamp (nanoseconds)
}

message Count {
  int64 count = 1;
}

message Timestamps {
	repeated int64 timestamps = 1; // Unix timestamp (nanoseconds)
}

message CountCertificatesByNamesRequest {
  Range range = 1;
  repeated string names = 2;
}

message CountByNames {
  map<string, int64> counts = 1;
  google.protobuf.Timestamp earliest = 2; // Unix timestamp (nanoseconds)
}

message CountRegistrationsByIPRequest {
  bytes ip = 1;
  Range range = 2;
}

message CountInvalidAuthorizationsRequest {
  int64 registrationID = 1;
  string hostname = 2;
  // Count authorizations that expire in this range.
  Range range = 3;
}

message CountOrdersRequest {
  int64 accountID = 1;
  Range range = 2;
}

message CountFQDNSetsRequest {
  int64 window = 1;
  repeated string domains = 2;
}

message FQDNSetExistsRequest {
  repeated string domains = 1;
}

message PreviousCertificateExistsRequest {
  string domain = 1;
  int64 regID = 2;
}

message Exists {
  bool exists = 1;
}

message AddSerialRequest {
  int64 regID = 1;
  string serial = 2;
  int64 created = 3; // Unix timestamp (nanoseconds)
  int64 expires = 4; // Unix timestamp (nanoseconds)
}

message AddCertificateRequest {
  bytes der = 1;
  int64 regID = 2;
  reserved 3; // previously ocsp
  // An issued time. When not present the SA defaults to using
  // the current time.
  int64 issued = 4;
  int64 issuerNameID = 5; // https://pkg.go.dev/github.com/letsencrypt/boulder/issuance#IssuerNameID

  // If this is set to true, the certificateStatus.status column will be set to
  // "wait", which will cause us to serve internalError responses with OCSP is
  // queried. This allows us to meet the BRs requirement:
  //
  // If the OCSP responder receives a request for the status of a certificate
  // serial number that is “unused”, then ...
  // the responder MUST NOT respond with a “good” status for such requests.
  // 
  // Paraphrasing, a certificate serial number is unused if neither a
  // Certificate nor a Precertificate has been issued with it. So when we write
  // a linting certificate to the precertificates table, we want to make sure
  // we never give a "good" response for that serial until the precertificate
  // is actually issued.
  bool ocspNotReady = 6;
}

message OrderRequest {
  int64 id = 1;
}

message NewOrderRequest {
  int64 registrationID = 1;
  int64 expires = 2;
  repeated string names = 3;
  repeated int64 v2Authorizations = 4;
}

message NewOrderAndAuthzsRequest {
  NewOrderRequest newOrder = 1;
  repeated core.Authorization newAuthzs = 2;
}

message SetOrderErrorRequest {
  int64 id = 1;
  core.ProblemDetails error = 2;
}

message GetValidOrderAuthorizationsRequest {
  int64 id = 1;
  int64 acctID = 2;
}

message GetOrderForNamesRequest {
  int64 acctID = 1;
  repeated string names = 2;
}

message FinalizeOrderRequest {
  int64 id = 1;
  string certificateSerial = 2;
}

message GetAuthorizationsRequest {
  int64 registrationID = 1;
  repeated string domains = 2;
  int64 now = 3; // Unix timestamp (nanoseconds)
}

message Authorizations {
  message MapElement {
          string domain = 1;
          core.Authorization authz = 2;
  }
  repeated MapElement authz = 1;
}

message AuthorizationIDs {
  repeated string ids = 1;
}

message AuthorizationID2 {
  int64 id = 1;
}

message RevokeCertificateRequest {
  string serial = 1;
  int64 reason = 2;
  int64 date = 3; // Unix timestamp (nanoseconds)
  int64 backdate = 5; // Unix timestamp (nanoseconds)
  bytes response = 4;
  int64 issuerID = 6;
}

message FinalizeAuthorizationRequest {
  int64 id = 1;
  string status = 2;
  int64 expires = 3; // Unix timestamp (nanoseconds)
  string attempted = 4;
  repeated core.ValidationRecord validationRecords = 5;
  core.ProblemDetails validationError = 6;
  int64 attemptedAt = 7; // Unix timestamp (nanoseconds)
}

message AddBlockedKeyRequest {
  bytes keyHash = 1;
  int64 added = 2; // Unix timestamp (nanoseconds)
  string source = 3;
  string comment = 4;
  int64 revokedBy = 5;
}

message KeyBlockedRequest {
  bytes keyHash = 1;
}

message Incident {
  int64 id = 1;
  string serialTable = 2;
  string url = 3;
  int64 renewBy = 4; // Unix timestamp (nanoseconds)
  bool enabled = 5;
}

message Incidents {
  repeated Incident incidents = 1;
}

message SerialsForIncidentRequest {
  string incidentTable = 1;
}

message IncidentSerial {
  string serial = 1;
  int64 registrationID = 2; // May be 0 (NULL)
  int64 orderID = 3; // May be 0 (NULL)
  int64 lastNoticeSent = 4; // Unix timestamp (nanoseconds), may be 0 (NULL)
}

message GetRevokedCertsRequest {
  int64 issuerNameID = 1;
  int64 expiresAfter = 2; // Unix timestamp (nanoseconds), inclusive
  int64 expiresBefore = 3; // Unix timestamp (nanoseconds), exclusive
  int64 revokedBefore = 4; // Unix timestamp (nanoseconds)
}

message RevocationStatus {
  int64 status = 1;
  int64 revokedReason = 2;
  google.protobuf.Timestamp revokedDate = 3; // Unix timestamp (nanoseconds)
}

message LeaseCRLShardRequest {
  int64 issuerNameID = 1;
  int64 minShardIdx = 2;
  int64 maxShardIdx = 3;
  google.protobuf.Timestamp until = 4;
}

message LeaseCRLShardResponse {
  int64 issuerNameID = 1;
  int64 shardIdx = 2;
}

message UpdateCRLShardRequest {
  int64 issuerNameID = 1;
  int64 shardIdx = 2;
  google.protobuf.Timestamp thisUpdate = 3;
  google.protobuf.Timestamp nextUpdate = 4;
}