File: README.md
Signal-Server
Documentation
Looking for protocol documentation? Check out the website!
How to Build
This project uses FoundationDB and requires the FoundationDB client library to be installed on the host system. With that in place, the server can be built and tested with:
$ ./mvnw clean testSecurity
Security issues should be sent to [email protected].
Help
We cannot provide direct technical support. Get help running this software in your own environment in our unofficial community forum.
Cryptography Notice
This distribution includes cryptographic software. The country in which you currently reside may have restrictions on the import, possession, use, and/or re-export to another country, of encryption software.
BEFORE using any encryption software, please check your country's laws, regulations and policies concerning the import, possession, or use, and re-export of encryption software, to see if this is permitted.
See https://www.wassenaar.org/ for more information.
The U.S. Government Department of Commerce, Bureau of Industry and Security (BIS), has classified this software as Export Commodity Control Number (ECCN) 5D002.C.1, which includes information security software using or performing cryptographic functions with asymmetric algorithms.
The form and manner of this distribution makes it eligible for export under the License Exception ENC Technology Software Unrestricted (TSU) exception (see the BIS Export Administration Regulations, Section 740.13) for both object code and source code.
License
Copyright 2013 Signal Messenger, LLC
Licensed under the GNU AGPLv3: https://www.gnu.org/licenses/agpl-3.0.html
File: service/src/main/proto/org/signal/chat/README.md
Chat gRPC API
Request metadata
Clients may provide headers for gRPC requests via gRPC metadata which translates directly to HTTP/2 headers.
- Clients should provide a
User-Agentheader on all gRPC requests. - Clients may provide an
Accept-Languageon any gRPC requests.
Authentication
To authenticate for a specific signal account + device, clients may provide a Basic authorization header
on the request. The username must be the account identifier encoded in the 8-4-4-4-12 format followed by a '.'
character and then the device id serialized as a string.
All services either require or forbid providing authentication via an Authorization header. If the service is annotated
with the require.auth option AUTH_ONLY_AUTHENTICATED, all requests to the service must contain valid authentication
headers. If the service is annotated with the option AUTH_ONLY_ANONYMOUS the client must not provide an authorization
header. If provided, the request will fail with a BAD_AUTHENTICATION error.
Errors
In the gRPC protocol all errors are at the request level. That is, errors are returned in response to individual requests and do not impact other H2 streams on the same connection nor terminate the connection.
For errors that may be returned by any RPCs, the chat server will return the well-defined gRPC status codes returned as part of every RPC call. For errors that are specific to a particular RPC, the error must be encoded in the service proto definition and will be returned with a Status of OK.
Status errors include additional metadata as described in AIP-193 (google's richer error model). Every Status != OK response returned by the chat server's application layer will include a Grpc-Status-Details-Bin response trailer with a google.rpc.Status proto.
Each google.rpc.Status must have a status matching the top-level status on the gRPC response. Additionally, a single ErrorInfo must always be present in the details field of the Status. The ErrorInfo must contain a domain field and a reason field.
The domain for a status error generated by the chat server will always be grpc.chat.signal.org
The server may set the reason to match the enum string for the Status.Code if there is no need to further distinguish a code. Clients should inspect the reason, not the status, for automated error handling.
The chat server may return the following errors from any RPC
| Status Code | Reason | Description |
|---|---|---|
INVALID_ARGUMENT |
UPGRADE_REQUIRED |
The client version provided in the User-Agent is no longer supported. The client must upgrade to use the service. |
INVALID_ARGUMENT |
CONSTRAINT_VIOLATED |
The RPC argument violated a constraint that was annotated or documented in the service definition. It is always possible to check this constraint without communicating with the chat server. This always represents a client bug or out of date client. The details may include a BadRequest message that indicates additional information about the invalid field. |
INVALID_ARGUMENT |
BAD_AUTHENTICATION |
The request has incorrectly set authentication credentials for the RPC. This represents a client bug where the authorization mode is not correct for the RPC. For example, The RPC was for an anonymous service, but included an Authentication header in the RPC metadata. The RPC should only be made by the primary device, but the request had linked device credentials. |
UNAUTHENTICATED |
INVALID_CREDENTIALS |
The account credentials provided in the authorization header are not valid. |
RESOURCE_EXHAUSTED |
RESOURCE_EXHAUSTED |
A server-side resource was exhausted. The details field may include a RetryInfo message that includes the amount of time in seconds the client should wait before retrying the request. If a RetryInfo is present, the client must wait the indicated time before retrying the request. If absent, the client should retry with an exponential backoff. |
ABORTED |
STREAM_CLOSED |
The server terminated a streaming RPC for some domain specific reason. The details field must include a message with additional information about why the stream was closed. This message must be defined in the corresponding service proto for the streaming RPC. This status must only be returned from server-side streaming RPCs. Clients must handle a STREAM_CLOSED status even if no corresponding message is defined in the version of the proto they are targeting. Unless otherwise noted, if a stream termination message is defined, clients must handle the error at any point in the message stream. |
UNAVAILABLE |
UNAVAILABLE |
There was an internal error processing the RPC. The client should retry the request with exponential backoff. |
Logging Errors
When logging error responses, clients may always log the status code, domain, and reason.
For errors with domain grpc.chat.signal.org and reason CONSTRAINT_VIOLATED, clients should check the details field for a BadRequest proto. If present, they should log the field of each violation in field_violations.
GOAWAY
In a partial or total server outage, the server may start rejecting new connection requests or terminating existing connections with an HTTP/2 GOAWAY frame with code 0x40.
If clients receive a 0x40 GOAWAY they should retry connections with an aggressive exponential backoff.