Signal registration service

This is a multi-provider phone number verification service for use with Signal.

When Signal users first create an account, they do so by associating that account with a phone number. Signal verifies that users actually control that phone number by sending a verification code to that number via SMS or via a phone call. This service manages the process of sending verification codes and checking codes provided by clients.

Major components

External callers interact with this service by sending gRPC requests. The gRPC interface is defined in registration_service.proto. gRPC requests are handled by RegistrationServiceGrpcEndpoint, which sanitizes client input and dispatches requests to RegistrationService, which orchestrates the major business logic for the entire service.

RegistrationService uses a SenderSelectionStrategy to choose a concrete VerificationCodeSender implementation to send a verification code to a client. VerificationCodeSenders are responsible for sending verification codes via a specific transport (i.e. SMS or voice) and service provider and later for verifying codes provided by clients. A SessionRepository stores session data (i.e. verification codes or references to external verification sessions) for VerificationCodeSenders.

Configuration

At a minimum, the registration service needs at least one VerificationCodeSender, a SenderSelectionStrategy, and a SessionRepository. No beans of those types will be instantiated unless they're configured, and so some configuration properties must be provided. The following table describes the currently-supported (and required, in production environments) configuration properties.

Property	Description
analytics.bigtable.table-id	The identifier for a Cloud Bigtable table to be used to store verification attempts pending follow-up analysis (optional)
analytics.bigtable.column-family-name	The name of a column family within analytics.bigtable.table-id to be used to store verification attempts pending follow-up analysis (optional)
analytics.pubsub.analyzed-attempts.topic	The name of a GCP pub/sub topic to which to send events when attempts are fully analyzed
analytics.pubsub.completed-attempts.topic	The name of a GCP pub/sub topic to which to send attempts without analysis
analytics.twilio.sms.price-estimate.default-number-types	A prioritized list of Twilio number types used by default to send messages to when using Twilio Programmable Messaging
analytics.twilio.sms.price-estimate.nanpa-number-types	A prioritized list of Twilio number types used to send messages to NANPA numbers when using Twilio Programmable Messaging
analytics.twilio.sms.price-estimate.regional-number-types	A map of ISO region codes to prioritized lists of Twilio number types used to send messages when using Twilio Programmable Messaging; may be empty
analytics.twilio.verify.fee-amount	The amount of the fee charged by Twilio Verify for successful verifications
analytics.twilio.verify.fee-currency	The currency of the fee charged by Twilio Verify for successful verifications
fictitious-numbers.firestore.collection-name	The name of the Cloud Firestore collection that stores verification codes for fictitious phone numbers
fictitious-numbers.firestore.expiration-field-name	The name of the field in documents in the Cloud Firestore collection for verification codes for fictitious phone numbers that identifies when the document expires and may be removed automatically
gcp.bigtable.project-id	The identifier for a Google Cloud Platform project that contains the Cloud Bigtable instance to be used for various data storage applications
gcp.bigtable.instance-id	The identifier for a Cloud Bigtable instance to be used for various data storage applications
gcp.pubsub.project-id	The identifier for a Google Cloud Platform project that contains the pubsub topics to be used
messagebird.access-key	The access key used to authenticate with MessageBird
messagebird.default-sender-id	The default originating number or alphanumeric sender id for MessageBird messages and calls
messagebird.region-sender-ids	The originating number or alphanumeric sender id for MessageBird messages and calls by region
messagebird.sms.session-ttl	The maximum lifetime of a registration started by sending a verification code via MessageBird sms (optional)
messagebird.verify.session-ttl	The maximum lifetime of a registration started by sending a verification code via MessageBird verify (optional)
messagebird.voice.session-ttl	The maximum lifetime of a registration started by sending a verification code via MessageBird voice (optional)
messagebird.voice.supported-languages	A list of BCP 47 language tags for which translations of spoken messages delivered via the MessageBird Voice API are available
prescribed-verification-codes.firestore.collection-name	The name of the Cloud Firestore collection that contains prescribed verification codes
rate-limits.check-verification-code.delays	A list of durations that callers must wait between successive attempts to check verification codes
rate-limits.leaky-bucket.session-creation.max-capacity	The maximum number of permits in a session creation rate limiter "bucket"
rate-limits.leaky-bucket.session-creation.permit-regeneration-period	The time required for a permit in a session creation rate limiter "bucket" to regenerate
rate-limits.leaky-bucket.session-creation.min-delay	The minimum amount of time that must elapse between taking permits from a session creation rate limiter "bucket"
rate-limits.send-sms-verification-code.delays	A list of durations that callers must wait between successive attempts to send verification codes via SMS
rate-limits.send-voice-verification-code.delay-after-first-sms	The amount of time a caller must wait after requesting their first SMS before they may request a phone call
rate-limits.send-voice-verification-code.delays	A list of durations that callers must wait between successive attempts to send verification codes via phone calls
selection.[transport].fallback-senders	A nonempty ordered list of senders to fall back on. The first sender that supports the request will be used, or the first sender if no sender supports the request.
selection.[transport].default-weights	A map by service of weights by which requests are assigned to services. (e.g. twilio-verify = 50, messagebird-verify = 50) (optional)
selection.[transport].region-weights	A map by region of weights that override the default weights (e.g. us.twilio-verify = 9, us.messagebird-verify = 1) (optional)
selection.[transport].region-overrides	A map of regions to service that indicate that a region should always go to that service (e.g. de = messagebird-verify) (optional)
session-repository.bigtable.table-name	The name of the Bigtable table that contains registration sessions
session-repository.bigtable.column-family-name	The name of the Bigtable column family name within the configured Bigtable table that contains registration sessions
twilio.account-sid	The SID of the Twilio account to use to send verification codes via Twilio's Programmable Messaging, Programmable Voice, and Verify APIs
twilio.api-key-sid	The SID of the Twilio API key used to authenticate with Twilio
twilio.api-key-secret	The secret component of the API key used to authenticate with Twilio
twilio.messaging.nanpa-messaging-service-sid	The SID of the Twilio messaging service to be used to send SMS messages to NANPA phone numbers
twilio.messaging.global-messaging-service-sid	The SID of the Twilio messaging service to be used to send SMS messages to phone numbers outside of NANPA
twilio.messaging.session-ttl	The maximum lifetime of a registration started by sending a verification code via the Twilio Programmable Messaging API (optional)
twilio.voice.phone-numbers	A list of E.164-formatted phone numbers from which Twilio voice calls can originate
twilio.voice.cdn-uri	The base URI from which voice messages translated to various languages may be retrieved
twilio.voice.supported-languages	A list of BCP 47 language tags for which translations of spoken messages delivered via the Twilio Programmable Voice API are available
twilio.voice.session-ttl	The maximum lifetime of a registration started by sending a verification code via the Twilio Programmable Voice API (optional)
twilio.verify.service-sid	The SID of a Twilio Verify service to be used to send verification codes
twilio.verify.service-friendly-name	A "friendly" name for the Twilio Verify service, which may appear in verification messages (optional)
twilio.verify.android-app-hash	The app hash to include in SMS messages sent by Twilio Verify for Android devices that support Automatic SMS Verification
twilio.verify.supported-languages	A list of BCP 47 language tags supported by Twilio Verify
verification.sms.android-app-hash	The app hash to include in SMS messages for Android devices that support Automatic SMS Verification
verification.sms.message-variants-by-region	A map of two-letter region codes (e.g. "US") to names of SMS message variants; message variants should have corresponding entries in the SMS message string table
verification.[transport].supported-languages	A list of BCP 47 language tags for which translations of a verification SMS message sent via the Twilio Programmable Messaging API are available

Running in development mode

For local testing, this service can be run in the dev Micronaut environment. In the dev environment, the following components are provided (assuming no others of have been configured):

• A trivial verification code sender that always uses the last six digits of a phone number as a verification code
• A trivial sender selection strategy that always chooses the last-six-digits "sender"
• An in-memory session store

These components are, obviously, not suitable for production use and are intended only to facilitate local development and testing.

To run the registration service locally with the dev environment enabled:

./mvnw mn:run -Dmicronaut.environments=dev

Testing with command-line tools

The registration service include a set of CLI tools to facilitate testing and development. The tools allow operators to create and inspect registration sessions, send verification codes, and check verification codes.

To build the CLI tools:

./mvnw clean package

To run the tool and get an exhaustive list of subcommands and flags:

java -cp target/registration-service-0.1.jar org.signal.registration.cli.RegistrationClient

…which yields (at the time of writing):

Usage: <main class> [--api-key=<apiKey>] [--host=<host>] [--port=<port>]
                    [[--plaintext] |
                    --trusted-server-certificate=<trustedServerCertificate>]
                    [COMMAND]
      --api-key=<apiKey>   API key for this call
      --host=<host>        Registration service hostname (default: localhost)
      --plaintext          Use plaintext instead of TLS? (default: false)
      --port=<port>        Registration service port (default: 50051)
      --trusted-server-certificate=<trustedServerCertificate>
                           Path to a trusted server certificate; signal.org
                           certificate trusted by default
Commands:
  create-session, create          Start a new registration session
  get-session, get                Describe an existing registration session
  send-verification-code, send    Send a verification code to a phone number
                                  associated with a session
  check-verification-code, check  Check a verification code for a registration
                                  session

As a concrete example of interacting with a local registration service running on port 50051, callers may create a registration session with the following command:

java -cp target/registration-service-0.1.jar org.signal.registration.cli.RegistrationClient \
  --host=localhost \
  --port=50051 \
  --plaintext \
  create-session +18005550123

…which yields (in this example):

Created registration session 2a3d2a2a41ff41fb9ce41687ddcc51a4

To send an SMS verification code for that session:

java -cp target/registration-service-0.1.jar org.signal.registration.cli.RegistrationClient \
  --host=localhost \
  --port=50051 \
  --plaintext \
  send-verification-code 2a3d2a2a41ff41fb9ce41687ddcc51a4

…and, finally, to submit a verification code for that session:

java -cp target/registration-service-0.1.jar org.signal.registration.cli.RegistrationClient \
  --host=localhost \
  --port=50051 \
  --plaintext \
  check-verification-code 2a3d2a2a41ff41fb9ce41687ddcc51a4 550123