Skip to content

Latest commit

 

History

History
447 lines (344 loc) · 11.4 KB

DOTS_protocol_specification_cheat_sheet.md

File metadata and controls

447 lines (344 loc) · 11.4 KB
Raw

DOTS protocol specification cheat sheet

Protocol Stack

Signal Channel Data Channel
Application CoAP[RFC7252] RESTCONF[RFC8040]
Encoding CBOR JSON
Security DTLS | TLS TLS
Transport UDP | TCP TCP

Signal Channel

CoAP URI

  • based on draft-signal-channel-18

Mitigation Request

Method Mandatry URI-Path Content-Type
PUT /.well-known/dots/v1/mitigate/cuid=dz6pHjaADkaFTbjr0JGBpw/mid=123/ application/cbor
GET(retrieve all) /.well-known/dots/v1/mitigate/cuid=dz6pHjaADkaFTbjr0JGBpw/ application/cbor
GET(specific one) /.well-known/dots/v1/mitigate/cuid=dz6pHjaADkaFTbjr0JGBpw/mid=123/ application/cbor
DELETE /.well-known/dots/v1/mitigate/cuid=dz6pHjaADkaFTbjr0JGBpw/mid=123/ application/cbor

* cdid is optional URI-path can be inserted only by DOTS gateway and MUST be placed before cuid

Session Configuration

Method Mandatry URI-Path Content-Type
PUT /.well-known/dots/v1/config/sid=123/ application/cbor
GET(default) /.well-known/dots/v1/config/ application/cbor
GET(specific one) /.well-known/dots/v1/config/sid=123/ application/cbor
DELETE /.well-known/dots/v1/config/sid=123/ application/cbor

CoAP Type

Operation Request(Client->Server) Response(Server-> Client)
Mitigation Request NonConfirmable(NON) NonConfirmable(NON)
Session Configuration Confirmable(CON) Acknowledgement(ACK)*

* see more detail in section 4.5 of the signal-channel draft

IDs

Mitigation Request

cuid

  • Client Unique Identifier
  • globally unique
  • generated by DOTS clients
  • output of a cryptographic hash
  • 16 bytes / base64url encoded
  • SHOULD NOT change over time

mid

  • Mitigation request Identifier
  • locally unique
  • generated by DOTS clients
  • integer
  • MUST be unique for each mitigation request

cdid

  • Client Domain IDentifier
  • globally unique
  • inserted only by DOTS gateway
  • MUST NOT be generated and included by DOTS clients.
  • 16 bytes / base64url encoded

Session Configuration

sid

  • Session Identifier
  • locally unique
  • generated by DOTS clients
  • integer
  • MUST increase monotonically.

Message Body

Mitigation Request

PUT(Request)

Parameter attribute CBOR Key CBOR Major Type
target-prefix optional* 6 4 array / 3 text string
target-port-range optional 7 4 array
lower-port optional 8 0 unsigned
upper-port optional 9 0 unsigned
target-protocol optional 10 4 array / 0 unsigned
target-fqdn optional* 11 4 array / 3 text string
target-uri optional* 12 4 array / 3 text string
alias-name optional* 13 4 array / 3 text string
lifetime mandatory 14 0 unsigned / 1 negative

* at least one of these optional parameters is mandatory

:::info a DOTS client MUST NOT include multiple 'scope' parameters in the same PUT request :::

PUT(Response)

Not specified

GET(Request)

No Body

GET(Response)

Mitigation Status Parameters(in addition to mitigation parameters)

Parameter attribute CBOR Key CBOR Major Type
mitigation-start mandatory 15 0 unsigned
lifetime mandatory 14 0 unsigned / 1 negative
status mandatory 16 0 unsigned
bytes-dropped optional 25 0 unsigned
bps-dropped optional 26 0 unsigned
pkts-dropped optional 27 0 unsigned
pps-dropped optional 28 0 unsigned

DELETE(Request)

No Body

DELETE(Response)

No Body

Session Configuration

GET(Request)

No Body

GET(Response)

Parameter attribute CBOR Key CBOR Major Type
mitigating-config optional(?) 32 5 map
heartbeat-interval optional 33 5 map
missing-hb-allowed optional 37 5 map
max-retransmit optional 38 5 map
ack-timeout optional 39 5 map
ack-random-factor optional 40 5 map
idle-config optional(?) 44 5 map
trigger-mitigation optional 45 7 bits 20 / 7 bits 21
config-interval optional 46 0 unsigned

values

Parameter CBOR Key CBOR Major Type used by
max-value 34 0 unsigned heartbeat-interval, missing-hb-allowed, max-retransmit, ack-timeout
min-value 35 0 unsigned heartbeat-interval, missing-hb-allowed, max-retransmit, ack-timeout
current-value 36 0 unsigned heartbeat-interval, missing-hb-allowed, max-retransmit, ack-timeout
max-value-decimal 41 6 tag 4 [-2, integer]* ack-random-factor
min-value-decimal 42 6 tag 4 [-2, integer]* ack-random-factor
current-value-decimal 43 6 tag 4 [-2, integer]* ack-random-factor

* it means fixed point number with -2 decimal places(c.f. 3 is represented as 3.00)

PUT(Request)

Parameter attribute CBOR Key CBOR Major Type
mitigating-config optional(?) 32 5 map
heartbeat-interval optional* 33 5 map
missing-hb-allowed optional* 37 5 map
max-retransmit optional* 38 5 map
ack-timeout optional* 39 5 map
ack-random-factor optional 40 5 map
idle-config optional(?) 44 5 map
trigger-mitigation optional* 45 7 bits 20 / 7 bits 21

* at least one of these optional parameters is mandatory

PUT(Reponse)

Not specified

DELETE(Request)

No Body

DELETE(Response)

No Body

Default Values

Name Value Unit
signal channel port TBD(4646)
lifetime 3600 sec
active-but-terminating 120 sec
heartbeat-interval 30 sec
missing-hb-allowed 5
max-retransmit 3
ack-timeout 2 sec
ack-random-factor 1.5

Data Channel

RESTCONF URI

Register DOTS clients

Method URI-Path Content-Type
POST /restconf/data/ietf-dots-data-channel:dots-data HTTP1.1 application/yang-data+json
PUT /restconf/data/ietf-dots-data-channel:dots-data/dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP1.1 application/yang-data+json
DELETE /restconf/data/ietf-dots-data-channel:dots-data/dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP1.1 application/yang-data+json

Register Alias

Method URI-Path Content-Type
POST /restconf/data/ietf-dots-data-channel:dots-data/dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP1.1 application/yang-data+json
GET(all alias) /restconf/data/ietf-dots-data-channel:dots-data/dots-client=dz6pHjaADkaFTbjr0JGBpw/aliases?content=config HTTP1.1 application/yang-data+json
GET(specific alias) /restconf/data/ietf-dots-data-channel:dots-data/dots-client=dz6pHjaADkaFTbjr0JGBpw/aliases/alias=Server2?content=config HTTP1.1 application/yang-data+json
DELETE /restconf/data/ietf-dots-data-channel:dots-data/dots-client=dz6pHjaADkaFTbjr0JGBpw/aliases/alias=Server2 HTTP1.1 application/yang-data+json

Register Filtering Rules

Method URI-Path Content-Type
POST /restconf/data/ietf-dots-data-channel:dots-data/dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP1.1 application/yang-data+json
GET(all ACLs) /restconf/data/ietf-dots-data-channel:dots-data/dots-client=dz6pHjaADkaFTbjr0JGBpw/access-lists?content=all HTTP1.1 application/yang-data+json
GET(specific ACL) /restconf/data/ietf-dots-data-channel:dots-data/dots-client=dz6pHjaADkaFTbjr0JGBpw/access-lists/acl=sample-ipv6-acl?content=all HTTP1.1 application/yang-data+json
DELETE /restconf/data/ietf-dots-data-channel:dots-data/dots-client=dz6pHjaADkaFTbjr0JGBpw/access-lists/acl=sample-ipv6-acl HTTP1.1 application/yang-data+json

Message Body

Register DOTS clients(Request)

 {
   "ietf-dots-data-channel:dots-client": [
     {
       "cuid": "string",
       "cdid": "string"
     }
   ]
 }

* cdid is optional which can be inserted only by DOTS gateway

Register DOTS clients(Response)

Not specified

Create Alias(Request)

Method: POST

 {
   "ietf-dots-data-channel:aliases": {
     "alias": [
       {
         "name": "string",
         "target-prefix": [
           "string"
         ],
         "target-port-range": [
           {
             "lower-port": integer,
             "upper-port": integer
           }
         ],
         "target-protocol": [
           integer
         ],
         "target-fqdn": [
           "string"
         ],
         "target-uri": [
           "string"
         ],
         "lifetime": integer
       }
     ]
   }
 }

mandatory: name, lifetime

* at least one of these optional parameters(target-prefix, target-fqdn, target-uri) is mandatory

Create Alias(Response)

Not specified

Retrieve Alias(Request)

Method: GET No body

Retrieve Alias(Response)

 {
   "ietf-dots-data-channel:aliases": {
     "alias": [
       {
         "name": "string",
         "target-prefix": [
           "string"
         ],
         "target-port-range": [
           {
             "lower-port": integer,
             "upper-port": integer
           }
         ],
         "target-protocol": [
           integer
         ],
         "target-fqdn": [
           "string"
         ],
         "target-uri": [
           "string"
         ],
         "lifetime": integer
       }
     ]
   }
 }

DELETE Alias(Request)

Method: DELETE No body

DELETE Alias(Response)

Not specified

Create Filtering Rule(Request)

Method: POST

{
  "ietf-dots-data-channel:access-lists": {
    "acl": [
      {
        "name": "sample-ipv4-acl",
        "type": "ipv4-acl-type",
        "lifetime": 10080,
        "aces": {
          "ace": [
            {
              "name": "rule1",
              "matches": {
                "l3": {
                  "ipv4" {
                     "destination-ipv4-network": "198.51.100.0/24"
                     "source-ipv4-network": "192.0.2.0/24",
                  }
                }
              },
              "actions": {
                "forwarding": "drop"
              }
            }
          ]
        }
      }
    ]
  }
}

Create Filtering Rule(Response)

Not specified

Retrieve Filtering Rules(Request)

Method: GET No body

Retrieve Filtering Rules(Response)

{
  "ietf-dots-data-channel:access-lists": {
    "acl": [
      {
        "name": "sample-ipv4-acl",
        "type": "ipv4-acl-type",
        "lifetime": 10080,
        "aces": {
          "ace": [
            {
              "name": "rule1",
              "matches": {
                "l3": {
                  "ipv4" {
                     "destination-ipv4-network": "198.51.100.0/24"
                     "source-ipv4-network": "192.0.2.0/24",
                  }
                }
              },
              "actions": {
                "forwarding": "drop"
              }
            }
          ]
        }
      }
    ]
  }
}

DELETE Filtering Rule(Request)

Method: DELETE No body

DELETE Filtering Rule(Response)

Not specified

Default Values

Name Value Unit
Data channel port TBD
lifetime(of alias) 10080 min