"Fossies" - the Fresh Open Source Software Archive

Member "Signal-Server-11.97.0/service/src/main/proto/RegistrationService.proto" (21 Feb 2024, 12859 Bytes) of package /linux/www/Signal-Server-11.97.0.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 syntax = "proto3";
    2 
    3 option java_multiple_files = true;
    4 
    5 package org.signal.registration.rpc;
    6 
    7 service RegistrationService {
    8   /**
    9    * Create a new registration session for a given destination phone number.
   10    */
   11   rpc CreateSession (CreateRegistrationSessionRequest) returns (CreateRegistrationSessionResponse) {}
   12 
   13   /**
   14    * Retrieves session metadata for a given session.
   15    */
   16   rpc GetSessionMetadata (GetRegistrationSessionMetadataRequest) returns (GetRegistrationSessionMetadataResponse) {}
   17 
   18   /**
   19    * Sends a verification code to a destination phone number within the context
   20    * of a previously-created registration session.
   21    */
   22   rpc SendVerificationCode (SendVerificationCodeRequest) returns (SendVerificationCodeResponse) {}
   23 
   24   /**
   25    * Checks a client-provided verification code for a given registration
   26    * session.
   27    */
   28   rpc CheckVerificationCode (CheckVerificationCodeRequest) returns (CheckVerificationCodeResponse) {}
   29 }
   30 
   31 message CreateRegistrationSessionRequest {
   32   /**
   33    * The phone number for which to create a new registration session.
   34    */
   35   uint64 e164 = 1;
   36 
   37   /**
   38    * Indicates whether an account already exists with the given e164 (i.e. this
   39    * session represents a "re-registration" attempt).
   40    */
   41   bool account_exists_with_e164 = 2;
   42 }
   43 
   44 message CreateRegistrationSessionResponse {
   45   oneof response {
   46     /**
   47      * Metadata for the newly-created session.
   48      */
   49     RegistrationSessionMetadata session_metadata = 1;
   50 
   51     /**
   52      * A response explaining why a session could not be created as requested.
   53      */
   54     CreateRegistrationSessionError error = 2;
   55   }
   56 }
   57 
   58 message RegistrationSessionMetadata {
   59   /**
   60    * An opaque sequence of bytes that uniquely identifies the registration
   61    * session associated with this registration attempt.
   62    */
   63   bytes session_id = 1;
   64 
   65   /**
   66    * Indicates whether a valid verification code has been submitted in the scope
   67    * of this session.
   68    */
   69   bool verified = 2;
   70 
   71   /**
   72    * The phone number associated with this registration session.
   73    */
   74   uint64 e164 = 3;
   75 
   76   /**
   77    * Indicates whether the caller may request delivery of a verification code
   78    * via SMS now or at some time in the future. If true, the time a caller must
   79    * wait before requesting a verification code via SMS is given in the
   80    * `next_sms_seconds` field.
   81    */
   82   bool may_request_sms = 4;
   83 
   84   /**
   85    * The duration, in seconds, after which a caller will next be allowed to
   86    * request delivery of a verification code via SMS if `may_request_sms` is
   87    * true. If zero, a caller may request a verification code via SMS
   88    * immediately. If `may_request_sms` is false, this field has no meaning.
   89    */
   90   uint64 next_sms_seconds = 5;
   91 
   92   /**
   93    * Indicates whether the caller may request delivery of a verification code
   94    * via a phone call now or at some time in the future. If true, the time a
   95    * caller must wait before requesting a verification code via SMS is given in
   96    * the `next_voice_call_seconds` field. If false, simply waiting will not
   97    * allow the caller to request a phone call and the caller may need to
   98    * perform some other action (like attempting verification code delivery via
   99    * SMS) before requesting a voice call.
  100    */
  101   bool may_request_voice_call = 6;
  102 
  103   /**
  104    * The duration, in seconds, after which a caller will next be allowed to
  105    * request delivery of a verification code via a phone call if
  106    * `may_request_voice_call` is true. If zero, a caller may request a
  107    * verification code via a phone call immediately. If `may_request_voice_call`
  108    * is false, this field has no meaning.
  109    */
  110   uint64 next_voice_call_seconds = 7;
  111 
  112   /**
  113    * Indicates whether the caller may submit new verification codes now or at
  114    * some time in the future. If true, the time a caller must wait before
  115    * submitting a verification code is given in the `next_code_check_seconds`
  116    * field. If false, simply waiting will not allow the caller to submit a
  117    * verification code and the caller may need to perform some other action
  118    * (like requesting delivery of a verification code) before checking a
  119    * verification code.
  120    */
  121   bool may_check_code = 8;
  122 
  123   /**
  124    * The duration, in seconds, after which a caller will next be allowed to
  125    * submit a verification code if `may_check_code` is true. If zero, a caller
  126    * may submit a verification code immediately. If `may_check_code` is false,
  127    * this field has no meaning.
  128    */
  129   uint64 next_code_check_seconds = 9;
  130 
  131   /**
  132    * The duration, in seconds, after which this session will expire.
  133    */
  134   uint64 expiration_seconds = 10;
  135 }
  136 
  137 message CreateRegistrationSessionError {
  138   /**
  139    * The type of error that prevented a session from being created.
  140    */
  141   CreateRegistrationSessionErrorType error_type = 1;
  142 
  143   /**
  144    * Indicates that this error may succeed if retried without modification after
  145    * a delay indicated by `retry_after_seconds`. If false, callers should not
  146    * retry the request without modification.
  147    */
  148   bool may_retry = 2;
  149 
  150   /**
  151    * If this error may be retried,, indicates the duration in seconds from the
  152    * present after which the request may be retried without modification. This
  153    * value has no meaning otherwise.
  154    */
  155   uint64 retry_after_seconds = 3;
  156 }
  157 
  158 enum CreateRegistrationSessionErrorType {
  159   CREATE_REGISTRATION_SESSION_ERROR_TYPE_UNSPECIFIED = 0;
  160 
  161   /**
  162    * Indicates that a session could not be created because too many requests to
  163    * create a session for the given phone number have been received in some
  164    * window of time. Callers should wait and try again later.
  165    */
  166   CREATE_REGISTRATION_SESSION_ERROR_TYPE_RATE_LIMITED = 1;
  167 
  168   /**
  169    * Indicates that the provided phone number could not be parsed.
  170    */
  171   CREATE_REGISTRATION_SESSION_ERROR_TYPE_ILLEGAL_PHONE_NUMBER = 2;
  172 }
  173 
  174 message GetRegistrationSessionMetadataRequest {
  175   /**
  176    * The ID of the session for which to retrieve metadata.
  177    */
  178   bytes session_id = 1;
  179 }
  180 
  181 message GetRegistrationSessionMetadataResponse {
  182   oneof response {
  183     RegistrationSessionMetadata session_metadata = 1;
  184     GetRegistrationSessionMetadataError error = 2;
  185   }
  186 }
  187 
  188 message GetRegistrationSessionMetadataError {
  189   GetRegistrationSessionMetadataErrorType error_type = 1;
  190 }
  191 
  192 enum GetRegistrationSessionMetadataErrorType {
  193   GET_REGISTRATION_SESSION_METADATA_ERROR_TYPE_UNSPECIFIED = 0;
  194 
  195   /**
  196    * No session was found with the given identifier.
  197    */
  198   GET_REGISTRATION_SESSION_METADATA_ERROR_TYPE_NOT_FOUND = 1;
  199 }
  200 
  201 message SendVerificationCodeRequest {
  202 
  203   reserved 1;
  204 
  205   /**
  206    * The message transport to use to send a verification code to the destination
  207    * phone number.
  208    */
  209   MessageTransport transport = 2;
  210 
  211   /**
  212    * A prioritized list of languages accepted by the destination; should be
  213    * provided in the same format as the value of an HTTP Accept-Language header.
  214    */
  215   string accept_language = 3;
  216 
  217   /**
  218    * The type of client requesting a verification code.
  219    */
  220   ClientType client_type = 4;
  221 
  222   /**
  223    * The ID of a session within which to send (or re-send) a verification code.
  224    */
  225   bytes session_id = 5;
  226 
  227   /**
  228    * If provided, always attempt to use the specified sender to send
  229    * this message.
  230    */
  231   string sender_name = 6;
  232 }
  233 
  234 enum MessageTransport {
  235   MESSAGE_TRANSPORT_UNSPECIFIED = 0;
  236   MESSAGE_TRANSPORT_SMS = 1;
  237   MESSAGE_TRANSPORT_VOICE = 2;
  238 }
  239 
  240 enum ClientType {
  241   CLIENT_TYPE_UNSPECIFIED = 0;
  242   CLIENT_TYPE_IOS = 1;
  243   CLIENT_TYPE_ANDROID_WITH_FCM = 2;
  244   CLIENT_TYPE_ANDROID_WITHOUT_FCM = 3;
  245 }
  246 
  247 message SendVerificationCodeResponse {
  248   reserved 1;
  249 
  250   /**
  251    * Metadata for the named session. May be absent if the session could not be
  252    * found or has expired.
  253    */
  254   RegistrationSessionMetadata session_metadata = 2;
  255 
  256   /**
  257    * If a code could not be sent, explains the underlying error. Will be absent
  258    * if a code was sent successfully. Note that both an error and session
  259    * metadata may be present in the same response because the session metadata
  260    * may include information helpful for resolving the underlying error (i.e.
  261    * "next attempt" times).
  262    */
  263   SendVerificationCodeError error = 3;
  264 }
  265 
  266 message SendVerificationCodeError {
  267   /**
  268    * The type of error that prevented a verification code from being sent.
  269    */
  270   SendVerificationCodeErrorType error_type = 1;
  271 
  272   /**
  273    * Indicates that this error may succeed if retried without modification after
  274    * a delay indicated by `retry_after_seconds`. If false, callers should not
  275    * retry the request without modification.
  276    */
  277   bool may_retry = 2;
  278 
  279   /**
  280    * If this error may be retried,, indicates the duration in seconds from the
  281    * present after which the request may be retried without modification. This
  282    * value has no meaning otherwise.
  283    */
  284   uint64 retry_after_seconds = 3;
  285 }
  286 
  287 enum SendVerificationCodeErrorType {
  288   SEND_VERIFICATION_CODE_ERROR_TYPE_UNSPECIFIED = 0;
  289 
  290   /**
  291    * The sender received and understood the request to send a verification code,
  292    * but declined to do so (i.e. due to rate limits or suspected fraud).
  293    */
  294   SEND_VERIFICATION_CODE_ERROR_TYPE_SENDER_REJECTED = 1;
  295 
  296   /**
  297    * The sender could not process or would not accept some part of a request
  298    * (e.g. a valid phone number that cannot receive SMS messages).
  299    */
  300   SEND_VERIFICATION_CODE_ERROR_TYPE_SENDER_ILLEGAL_ARGUMENT = 2;
  301 
  302   /**
  303    * A verification could could not be sent via the requested channel due to
  304    * timing/rate restrictions. The response object containing this error should
  305    * include session metadata that indicates when the next attempt is allowed.
  306    */
  307   SEND_VERIFICATION_CODE_ERROR_TYPE_RATE_LIMITED = 3;
  308 
  309   /**
  310    * No session was found with the given ID.
  311    */
  312   SEND_VERIFICATION_CODE_ERROR_TYPE_SESSION_NOT_FOUND = 4;
  313 
  314   /**
  315    * A new verification could could not be sent because the session has already
  316    * been verified.
  317    */
  318   SEND_VERIFICATION_CODE_ERROR_TYPE_SESSION_ALREADY_VERIFIED = 5;
  319 
  320   /**
  321    * A verification code could not be sent via the requested transport because
  322    * the destination phone number (or the sender) does not support the requested
  323    * transport.
  324    */
  325   SEND_VERIFICATION_CODE_ERROR_TYPE_TRANSPORT_NOT_ALLOWED = 6;
  326 
  327   /**
  328    * The sender declined to send the verification code due to suspected fraud
  329    */
  330   SEND_VERIFICATION_CODE_ERROR_TYPE_SUSPECTED_FRAUD = 7;
  331 
  332 }
  333 
  334 message CheckVerificationCodeRequest {
  335   /**
  336    * The session ID returned when sending a verification code.
  337    */
  338   bytes session_id = 1;
  339 
  340   /**
  341    * The client-provided verification code.
  342    */
  343   string verification_code = 2;
  344 }
  345 
  346 message CheckVerificationCodeResponse {
  347   reserved 1;
  348 
  349   /**
  350    * Metadata for the named session. May be absent if the session could not be
  351    * found or has expired.
  352    */
  353   RegistrationSessionMetadata session_metadata = 2;
  354 
  355   /**
  356    * If a code could not be checked, explains the underlying error. Will be
  357    * absent if no error occurred. Note that both an error and session
  358    * metadata may be present in the same response because the session metadata
  359    * may include information helpful for resolving the underlying error (i.e.
  360    * "next attempt" times).
  361    */
  362   CheckVerificationCodeError error = 3;
  363 }
  364 
  365 message CheckVerificationCodeError {
  366   /**
  367    * The type of error that prevented a verification code from being checked.
  368    */
  369   CheckVerificationCodeErrorType error_type = 1;
  370 
  371   /**
  372    * Indicates that this error may succeed if retried without modification after
  373    * a delay indicated by `retry_after_seconds`. If false, callers should not
  374    * retry the request without modification.
  375    */
  376   bool may_retry = 2;
  377 
  378   /**
  379    * If this error may be retried,, indicates the duration in seconds from the
  380    * present after which the request may be retried without modification. This
  381    * value has no meaning otherwise.
  382    */
  383   uint64 retry_after_seconds = 3;
  384 }
  385 
  386 enum CheckVerificationCodeErrorType {
  387   CHECK_VERIFICATION_CODE_ERROR_TYPE_UNSPECIFIED = 0;
  388 
  389   /**
  390    * The caller has attempted to submit a verification code even though no
  391    * verification codes have been sent within the scope of this session. The
  392    * caller must issue a "send code" request before trying again.
  393    */
  394   CHECK_VERIFICATION_CODE_ERROR_TYPE_NO_CODE_SENT = 1;
  395 
  396   /**
  397    * The caller has made too many guesses within some period of time. Callers
  398    * should wait for the duration prescribed in the session metadata object
  399    * elsewhere in the response before trying again.
  400    */
  401   CHECK_VERIFICATION_CODE_ERROR_TYPE_RATE_LIMITED = 2;
  402 
  403   /**
  404    * The session identified in this request could not be found (possibly due to
  405    * session expiration).
  406    */
  407   CHECK_VERIFICATION_CODE_ERROR_TYPE_SESSION_NOT_FOUND = 3;
  408 
  409   /**
  410    * The session identified in this request is still active, but the most
  411    * recently-sent code has expired. Callers should request a new code, then
  412    * try again.
  413    */
  414   CHECK_VERIFICATION_CODE_ERROR_TYPE_ATTEMPT_EXPIRED = 4;
  415 }