Expand description
The structures used in the Sigul protocol.
All structures described in this documenation are to be sent in network byte order (big endian).
§Outer TLS Session
Both the client and server connect to the bridge service using TLS, authenticated via client certificates. Once the connection is established, the connecting side (the client or server) sends a protocol header and waits for an acknowledgement from the bridge. After the acknowledgement is received, no further communication occurs in the outer TLS session.
§Protocol Header and Ack
Every connection to the bridge must begin with the protocol header, which announces the protocol version to follow. The server may reject the request if the version is unknown or unsupported. A server may support multiple versions, but must always use the version requested by the client if it is supported.
|–––––––––––––|
| Protocol Header |
|---|
| u64 |
| u32 |
| u8 |
| ––––––––––––– |
The bridge responds with an acknowledgement which includes a session ID for the connection and a status to indicate whether the inner TLS connection can proceed.
|–––––––––––––|
| Protocol Ack |
|---|
| u128 |
| u8 |
| ––––––––––––– |
The session ID is a UUID generated by the bridge and provided to both the client and the server. This can be used to identify a connection on both the client and server.
Refer to [BridgeStatus] for possible status values.
The protocol version is increased whenever any of the following structures are changed. Thus, all structures described below are specific to version 2 of the protocol.
§Inner TLS Session
After the protocol header is acknowledged, the client starts a second TLS session within the first one. In this session, the client must configure the TLS session to accept the Sigul server’s hostname and must present its client TLS certificate. All future communication occurs over this nested TLS session.
§Frames
Each message in the inner TLS session must start with a frame, which describes the size of the data to follow. Requests include two sections; the first is a JSON-serialized, UTF-8 encoded dictionary describing the request and its parameters. The second section is an arbitrary, request-specific binary blob. This binary blob is used exclusively for various signing requests and management commands do not include one. When the command does not have a binary blob, the size in the frame must be set to 0.
|—————————|
| Frame Header |
|---|
| u64 |
| u64 |
| ————————— |
Enums§
- Certificate
- Describes the public portion of keys managed by Siguldry.
- Digest
Algorithm - The digest algorithm to use when signing.
- Error
- Possible errors due to protocol violations.
- GpgSignature
Type - KeyAlgorithm
- Possible key types.
- Role
- The possible roles a connection can have.
- Server
Error - Errors that occur when handling client requests.
Constants§
- MAGIC
- Magic number used in the protocol header.
- PROTOCOL_
VERSION - The Sigul wire protocol version this implementation supports