mautrix-signal/pkg/signalmeow/protobuf/org/signal/chat/credentials.proto

/*
 * Copyright 2023 Signal Messenger, LLC
 * SPDX-License-Identifier: AGPL-3.0-only
 */

syntax = "proto3";

option java_multiple_files = true;

import "org/signal/chat/require.proto";

package org.signal.chat.credentials;

// Provides methods for obtaining and verifying credentials that allow an
// authenticated user to authenticate in another service or context without
// revealing their identity.
service Credentials {
  option (require.auth) = AUTH_ONLY_AUTHENTICATED;

  // Generates and returns an external service credentials for the caller.
  rpc GetExternalServiceCredentials(GetExternalServiceCredentialsRequest)
      returns (GetExternalServiceCredentialsResponse) {}

  // Generates a pair of delivery certificates that the holder can include to
  // identify themselves to a message recipient (but not the server) in a
  // sealed-sender message.
  rpc GetDeliveryCertificate(GetDeliveryCertificateRequest)
    returns (GetDeliveryCertificateResponse) {}

  // Generates a set of zero-knowledge credentials for various group-related
  // actions.
  rpc GetGroupCredentials(GetGroupCredentialsRequest)
    returns (GetGroupCredentialsResponse) {}

  // Generates zero-knowledge credentials for creating call links.
  rpc GetCreateCallLinkCredentials(GetCreateCallLinkCredentialsRequest)
    returns (GetCreateCallLinkCredentialsResponse) {}
}

// Provides methods for working with previously-generated credentials without
// revealing an association between the credentials and the caller's identity to
// the server.
service CredentialsAnonymous {
  option (require.auth) = AUTH_ONLY_ANONYMOUS;

  // Given a list of secure value recovery (SVR) service credentials and a phone
  // number, checks and returns which of the provided credentials were generated
  // by the user with the given phone number and have not yet expired.
  rpc CheckSvrCredentials(CheckSvrCredentialsRequest)
      returns (CheckSvrCredentialsResponse) {}
}

enum ExternalServiceType {
  EXTERNAL_SERVICE_TYPE_UNSPECIFIED = 0;
  EXTERNAL_SERVICE_TYPE_DIRECTORY = 1;
  EXTERNAL_SERVICE_TYPE_PAYMENTS = 2;
  EXTERNAL_SERVICE_TYPE_STORAGE = 3;
  EXTERNAL_SERVICE_TYPE_SVR = 4;
}

message GetExternalServiceCredentialsRequest {
  // A service to request credentials for.
  ExternalServiceType externalService = 1;
}

message GetExternalServiceCredentialsResponse {
  // A username that can be presented to authenticate with the external service.
  string username = 1;

  // A password that can be presented to authenticate with the external service.
  string password = 2;
}

enum AuthCheckResult {
  AUTH_CHECK_RESULT_UNSPECIFIED = 0;
  // The credentials could be used to make a call to SVR service by the user
  // associated with the `CheckSvrCredentialsRequest.number` phone number.
  AUTH_CHECK_RESULT_MATCH = 1;
  // The credentials were generated by a different user.
  AUTH_CHECK_RESULT_NO_MATCH = 2;
  // This status indicates that the corresponding credentials token should no longer be used.
  // This may be because it has expired or invalid, but it can also mean that there is a more
  // recent token in the request which should be used instead.
  AUTH_CHECK_RESULT_INVALID = 3;
}

message CheckSvrCredentialsRequest {
  // A phone number in the E164 format to check the passwords against.
  // Only passwords generated for the user associated with the given number will be marked as `AUTH_CHECK_RESULT_MATCH`.
  string number = 1;

  // A list of credentials from previously made calls to `ExternalServiceCredentials.GetExternalServiceCredentials()`
  // for `EXTERNAL_SERVICE_TYPE_SVR`. This list may contain credentials generated by different users. Up to 10 credentials
  // can be checked.
  repeated string passwords = 2 [(require.nonEmpty) = true, (require.size) = {max: 10}];
}

// For each of the credentials tokens in the `CheckSvrCredentialsRequest` contains the result of the check.
message CheckSvrCredentialsResponse {

  map<string, AuthCheckResult> matches = 1;
}

message GetDeliveryCertificateRequest {
}

// A pair of message delivery certificates. The response unconditionally
// includes certificates with and without the caller's phone number so the
// server never learns anything about the caller's intent to share their phone
// number with their contacts.
message GetDeliveryCertificateResponse {
  // A delivery receipt that includes the caller's phone number; may be empty if
  // the authenticated account does not have a phone number
  bytes certificate_with_e164 = 1;

  // A delivery receipt that does not include the caller's phone number
  bytes certificate_without_e164 = 2;
}

message GetGroupCredentialsRequest {
  // The earliest time for which to issue group credentials; must be aligned to
  // a UTC day boundary and may be no more than one day in the past at the time
  // of the call.
  uint64 redemption_start_seconds = 1;

  // The latest time for which to issue group credentials; must be aligned to a
  // UTC day boundary and no more than seven days in the future at the time of
  // the call.
  uint64 redemption_end_seconds = 2;
}

message GetGroupCredentialsResponse {
  // A zero-knowledge credential that may be redeemed at or up to one day after
  // the given redemption time
  message CredentialAndRedemptionTime {
    bytes credential = 1;
    uint64 redemption_time_seconds = 2;
  }

  // A collection of credentials allowing the holder to anonymously
  // authenticate themselves for group-related actions
  repeated CredentialAndRedemptionTime group_credentials = 1;

  // A collection of credentials allowing the holder to read, update, and delete
  // group call links
  repeated CredentialAndRedemptionTime call_link_auth_credentials = 2;

  // The phone number identifier for which the included credentials were
  // generated. Empty if the account does not have a phone number.
  bytes pni = 3;
}

message GetCreateCallLinkCredentialsRequest {
  // A zero-knowledge credential request
  bytes credential_request = 1;
}

message GetCreateCallLinkCredentialsResponse {
  // A zero-knowledge credential that may be redeemed at or up to one day after
  // the given redemption time
  bytes credential = 1;

  // The earliest time, in seconds since the epoch, at which the associated
  // credential may be redeemed
  uint64 redemption_time_seconds = 2;
}