...
Description
Identify the version of the protocol being used by the client and server. Note that there is both a major and minor version number, and while the major version has already been sent as part of the binary connection negotiation (as that version may be needed to even read this handshake message), it is still required in this message for completeness sake. The connection_API.proto file contains enums for the version fields where MajorVerions.CURRENT_MAJOR_VERSION and MinorVersions.CURRENT_MINOR_VERSION will be the version implemented by this package of proto files.
Request
| HandshakeRequest |
| Field Name | Data type | Description | Mandatory? |
|---|
| majorVersion | int32 | The major version of the client's protocol | Y |
| minorVersion | int32 | The minor version of the client's protocol | Y |
Response
| HandshakeResponse |
| Field Name | Data type | Description | Mandatory? |
|---|
| serverMajorVersion | int32 | The major version of the servers protocol | Y |
| serverMinorVersion | int32 | The minor version of the server's protocol | Y |
| handshakePassed | boolean | Whether the server is able to communicate with the client's protocol version | Y |
Expected behavior
If the server returns a handshakePassed of true, the client can then proceed to send any messages defined in it's version of the protocol and expect the corresponding response messages.
- Prior to a successful handshake operations, every other request sent to the server should fail with a HANDSHAKE_REQUIRED error.
Errors
| | |
|---|
| 1102 | UNSUPPORTED_OPERATION | This will be returned in response to a HandshakeRequest if the handshake has already been completed for this connection |
| Anchor |
|---|
|
| Authentication | | Authentication |
|---|
|
Authentication
Description
Pass client credentials to the server's security manager. Credentials are passed in as key, value pairs of strings and are interpreted by the security manager on the server. For a default Shiro security manager, the credentials might be as simple as
| Pre |
|---|
| {{"user", "bob"}, {"password", "bobspassword"}} |
Request
| AuthenticationRequest |
| Field Name | Data type | Description | Mandatory? |
|---|
| credentials | map<string,string> | A set of key, value properties defined by the server's security manager | Y |
Response
| AuthenticationResponse |
| Field Name | Data type | Description | Mandatory? |
|---|
| authenticated | boolean | Whether authenticated succeeded. | Y |
Expected behavior
If authentication is required, after the connection has completed handshaking, any request other than authentication will fail with an AUTHENTICATION_FAILED error.
- Once a connection is authenticated with user credentials, any operations that user doesn't have permission for will fail with AUTHORIZATION_FAILED.
- It's not possible to change the credentials associated with a connection. Changing credentials requires creating a new connection.
Errors
| | |
|---|
| 1103 | UNSUPPORTED_AUTHENTICATION_MODE | The server's security manager is not compatible with protobuf authentication |
| 1202 | ALREADY_AUTHENTICATED | The connection has already been authenticated |
| 1203 | AUTHENTICATION_NOT_SUPPORTED | The server doesn't support authentication |