| Internet-Draft | Key Service Specification TCP | March 2024 |
| Leptons | Expires 18 September 2024 | [Page] |
A simple protocol for management and authentication key over the Transmission Control Protocol (TCP) or Transport Layer Security (TLS).¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 18 September 2024.¶
Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
Key are used together for authentication from client to server. A key MUST be 160 bits, unique, and generated by a strong cryptography algorithm such as RAND_bytes(3) from OpenSSL. There are three kinds of key StandardKey, RootKey and ClientKey. They are described in next sections.¶
The first 64 bits of a key called key identity. The identity MUST be unique. There are three key identities StandardKeyId, RootKeyId and ClientKeyId respectively.¶
Standard key is used for authentication from client to server as a standard user, see Section 3. The key does not support other operations than authentication. It's managed by root user via the protocol, see Section 1.3.¶
Root key is used for authentication from client to sever as a root user, see Section 4. The key supports management StandardKey via the protocol:¶
Client key reprents for the client that has permission to communicate with the server. Without ClientKey, other type of keys cannot be authenticated to the server. This called two key authentication. There are two use cases:¶
StandardKey for authentication as a standard user. See Section 3.2.¶ RootKey for authentication as a root user. See Section 4.2.¶ For humans, a key MUST be encoded as Base36, which is:¶
0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ.¶ 0 represents for 0, 1 for 1, A for 10, B for 11, Z for 35, and so on.¶ -.¶ For example, the key 0x3E29F382F292A26FDD6BAEF64614BEAFFE62CDBC can be display as below:¶
+------------ 6 blocks ------------+
| |
v v
79ETG-6PA79-MTO58-R4554-CZSU2-HHYJSS
^
|
+--- Block of 5 symbols
¶ The communication between client and server is sequenced. If the client sends a message to server, then it MUST wait for a response message. Break this rule may lead to unspecified behaviors.¶
Handshake is mandatory to establish the protocol. Client MUST connect to server over TCP or TLS. Then it MUST send Handshake message to server and wait for HandshakeResult. If returned status other than Success then the client MUST terminate the connection.¶
If handshake successfully then client and server are ready to communicate by messages. See Section 3 and Section 4 for more operations.¶
Client Server | | | Connect TCP/TLS | |==============================================================>| |<--------------------------------------------------------------| | Ok | | | | | | Handshake | |==============================================================>| |<--------------------------------------------------------------| | HandshakeResult | | |¶
Client Server | | | AuthenticateStandard | |==============================================================>| |<--------------------------------------------------------------| | AuthenticateStandardResult | | | | | | Ping | |==============================================================>| |<--------------------------------------------------------------| | Pong | | |¶
Client MUST send AuthenticateStandard message to server and wait for AuthenticateStandardResult. If returned status other than Success then the client MUST terminate the connection. The client MAY try authentication later.¶
Client Server | | | AuthenticateRoot | |==============================================================>| |<--------------------------------------------------------------| | AuthenticateRootResult | | | | | | NewStandardKey | |==============================================================>| |<--------------------------------------------------------------| | NewStandardKeyResult | | | | | | EnableStandardKey | |==============================================================>| |<--------------------------------------------------------------| | EnableStandardKeyResult | | | | | | DisabledStandardKey | |==============================================================>| |<--------------------------------------------------------------| | DisableStandardKeyResult | | | | | | FindStandardKey | |==============================================================>| |<--------------------------------------------------------------| | FindStandardKeyResult | | | | | | Ping | |==============================================================>| |<--------------------------------------------------------------| | Pong | | |¶
Client MUST send AuthenticateRoot message to server and wait for AuthenticateRootMessage. If returned status is other than Success then the client MUST terminate connection. The client MAY try authentication later.¶
Client MUST send NewStandardKey message to server and wait for NewStandardKeyResult result. The client MUST keep the connection, what ever the result is.¶
Client MUST send EnableStandardKey message to server and wait for EnableStandardKey. The client MUST keep the connection, what ever the result is.¶
Client MUST send DisableStandardKey message to server and wait for DisableStandardKey. The client MUST keep the connection, what ever the result is.¶
Client MUST send FindStandardKey message to server and wait for FindStandardKey. The client MUST keep the connection, what ever the result is.¶
With a new TCP/TLS connection, the sever MUST wait for Handshake message and respond HandshakeResult.¶
If server does not accepts client IP for some reasons, then it MUST terminate the connection.¶
If the server does not support protocol Version, then it MUST respond status VersionNotSupported and terminate the connection.¶
If client sends a non Handshake message, then the server MUST respond status MessageTypeInvalid and terminate the connection.¶
Otherwise, the server MUST respond status Ok.¶
After handshake success, the server MUST accept one of the following messages AuthenticateStandard or AuthenticateRoot. If client sends other messages, then the server MUST respond MessageTypeInvalid and terminate the connection.¶
After handshake success, server MUST accept AuthenticateStandard message and respond AuthenticateStandardResult.¶
If keys are invalid, then server MUST responds status Unauthorized and terminate the connection.¶
If keys are valid and there is no authenticated connection with the same key, then the server MUST respond status Ok. If there is a connection with the same key, then response status AuthenticationConflict.¶
After AuthenticateStandard success, the server MUST accept only Ping message. Otherwise, it MUST terminate the connection.¶
After handshake success, server MUST accept AuthenticateRoot message, and respond AuthenticateRootResult.¶
If keys are invalid, then server MUST responds status Unauthorized and terminate the connection.¶
If keys are valid, then the server MUST respond status Ok.¶
After AuthenticateRoot success, the server MUST accept the following messages: NewStandardKey, EnableStandardKey, DisableStandardKey, FindStandardKey, and Ping. Otherwise, it MUST terminate the connection.¶
With a root connection, server MUST accept NewStandardKey message and respond NewStandardKeyResult.¶
If NoteLength and Note is invalid, then server MUST respond status MessageDataInvalid. If there are no more key identities, then server MUST respond status Exhausted.¶
A key MUST be generated by strong cryptography algorithm. If success, then save the key and respond it with status Ok.¶
With a root connection, server MUST accept EnableStandardKey message and respond EnableStandardKeyResult.¶
If the key is not existed, then response status NotFound. If the key is existed and it's already enabled, then response status NotChanged.¶
If the key is existed and it's disabled, then enable it and response status Ok.¶
With a root connection, server MUST accept DisableStandardKey message and respond DisableStandardKeyResult.¶
If the key is not existed, then response status NotFound. If the key is existed and it's already disabled, then response status NotChanged.¶
If the key is existed and it's enabled, then disable it. If there are any connection that is authenticated by the key, then terminate it. Finally, response status Ok.¶
With a root connection, server MUST accept FindStandardKey message and respond FindStandardKeyResult.¶
If the key is not existed, then response status NotFound. Otherwise, respond status Ok and key's data.¶
If client does not send any message after ConnectionTimeout is reached, then server MUST terminate the connection.¶
Status is a 8 bits unsigned integer that indicate a success or failed message. There are message that does not contain status. There are list of status:¶
Client error status is in range [0x20, 0x2F]. There are status:¶
0x20 - MessageTypeInvalid. The peer does not accept message type.¶ 0x21 - MessageDataInvalid. The data part is invalid.¶ 0x22 - Unauthorized. Invalid credential.¶ 0x23 - NotFound. The resource does not exist.¶ 0x24 - AuthenticationConflict. There is already connection that is authenticated by the same key.¶ A message includes two parts: Type and Data. Type is 16 bits and included for any messages. Data may be zero or multi-bytes. There are finite message types, and they are specified in the next sections.¶
+===============+===============+===================================+ | Size | Name | Description | +===============+===============+===================================+ | 16 bits | Type | Type of message. | |---------------+---------------+-----------------------------------+ | 0 or | Variant | Data of message. | | multi-bytes | | | +---------------+---------------+-----------------------------------+¶
+===============+===============+===================================+ | Size | Name | Description | +===============+===============+===================================+ | 16 bits | Type | MUST be 0x1000. | |---------------+---------------+-----------------------------------+ | 8 bits | Version | The protocol version | | | | MUST be 0x01. | +---------------+---------------+-----------------------------------+¶
+===============+===============+===================================+ | Size | Name | Description | +===============+===============+===================================+ | 16 bits | Type | MUST be 0x1001. | +---------------+---------------+-----------------------------------+ | 8 bits | Status | 0x10 = Ok | | | | 0x30 = InternalError | | | | 0x31 = VersionNotSupported | +---------------+---------------+-----------------------------------+¶
+===============+===============+===================================+ | Size | Name | Description | +===============+===============+===================================+ | 16 bits | Type | MUST be 0x2000. | +---------------+---------------+-----------------------------------+ | 160 bits | ClientKey | | +---------------+---------------+-----------------------------------+ | 160 bits | StandardKey | | +---------------+---------------+-----------------------------------+¶
+===============+===============+===================================+ | Size | Name | Description | +===============+===============+===================================+ | 16 bits | Type | MUST be 0x2001. | +---------------+---------------+-----------------------------------+ | 8 bits | Status | 0x10 = Ok | | | | 0x22 = Unauthorized | | | | 0x24 = AuthenticationConflict | | | | 0x30 = InternalError | +---------------+---------------+-----------------------------------+¶
+===============+===============+===================================+ | Size | Name | Description | +===============+===============+===================================+ | 16 bits | Type | MUST be 0x3000. | +---------------+---------------+-----------------------------------+ | 160 bits | ClientKey | | +---------------+---------------+-----------------------------------+ | 160 bits | RootKey | | +---------------+---------------+-----------------------------------+¶
+===============+===============+===================================+ | Size | Name | Description | +===============+===============+===================================+ | 16 bits | Type | MUST be 0x3001. | +---------------+---------------+-----------------------------------+ | 8 bits | Status | 0x10 = Ok | | | | 0x22 = Unauthorized | | | | 0x30 = InternalError | +---------------+---------------+-----------------------------------+¶
This operation requires authenticated RootKey.¶
+===============+===============+===================================+ | Size | Name | Description | +===============+===============+===================================+ | 16 bits | Type | MUST be 0x3002. | +---------------+---------------+-----------------------------------+ | 8 bits | NoteLength | | +---------------+---------------+-----------------------------------+ | 0-255 bytes | Note | UTF-8 encoded | +---------------+---------------+-----------------------------------+¶
+===============+===============+===================================+ | Size | Name | Description | +===============+===============+===================================+ | 16 bits | Type | MUST be 0x3003. | +---------------+---------------+-----------------------------------+ | 8 bits | Status | 0x10 = Ok | | | | 0x21 = MessageDataInvalid | | | | 0x30 = InternalError | | | | 0x32 = Exhausted | | | | | | | | MUST include next blocks on | | | | success. Otherwise, skip it | +---------------+---------------+-----------------------------------+ | 160 bits | Key | Created key. | +---------------+---------------+-----------------------------------+¶
This operation requires authenticated RootKey.¶
+===============+===============+===================================+ | Size | Name | Description | +===============+===============+===================================+ | 16 bits | Type | MUST be 0x3004 | +---------------+---------------+-----------------------------------+ | 64 bits | KeyId | MUST be the first 64 bits | | | | of StandardKey. | +---------------+---------------+-----------------------------------+¶
+===============+===============+===================================+ | Size | Name | Description | +===============+===============+===================================+ | 16 bits | Type | 0x3005 | |---------------+---------------+-----------------------------------+ | 8 bits | Status | 0x10 = Ok | | | | 0x11 = NotChanged | | | | 0x23 = NotFound | | | | 0x30 = InternalError | +---------------+---------------+-----------------------------------+¶
This operation requires authenticated RootKey.¶
+===============+===============+===================================+ | Size | Name | Description | +===============+===============+===================================+ | 16 bits | Type | MUST be 0x3006. | +---------------+---------------+-----------------------------------+ | 64 bits | KeyId | MUST be the first 64 bits | | | | of StandardKey. | +---------------+---------------+-----------------------------------+¶
+===============+===============+===================================+ | Size | Name | Description | +===============+===============+===================================+ | 16 bits | Type | MUST be 0x3007. | |---------------+---------------+-----------------------------------+ | 8 bits | Status | 0x10 = Ok | | | | 0x11 = NotChanged | | | | 0x23 = NotFound | | | | 0x30 = InternalError | +---------------+---------------+-----------------------------------+¶
This operation requires authenticated RootKey.¶
+===============+===============+===================================+ | Size | Name | Description | +===============+===============+===================================+ | 16 bits | Type | MUST be 0x3008. | |---------------+---------------+-----------------------------------+ | 64 bits | KeyId | The first 64 bits of StandardKey. | +---------------+---------------+-----------------------------------+¶
+===============+===============+===================================+ | Size | Name | Description | +===============+===============+===================================+ | 16 bits | Type | MUST be 0x3009. | |---------------+---------------+-----------------------------------+ | 8 bits | Status | 0x10 = Ok | | | | 0x23 = NotFound | | | | 0x30 = InternalError | | | | | | | | MUST include next blocks on | | | | success. Otherwise, skip it. | |---------------+---------------+-----------------------------------+ | 8 bits | Enabled | 0x00 = No | | | | 0x01 = Yes | |---------------+---------------+-----------------------------------+ | 64 bits | CreatedAt | UNIX timestamp in seconds. | |---------------+---------------+-----------------------------------+ | 8 bits | NoteLength | | |---------------+---------------+-----------------------------------+ | 0-255 bytes | Note | UTF-8 encoded. | +---------------+---------------+-----------------------------------+¶