Repository: zubairhamed/canopus Branch: master Commit: e374f5b1a0f3 Files: 55 Total size: 252.9 KB Directory structure: gitextract_9p8qk6we/ ├── .gitignore ├── .gitmodules ├── Godeps/ │ └── Godeps.json ├── LICENSE ├── README.md ├── bytecontent.go ├── canopus.go ├── client.go ├── conn.go ├── corelink.go ├── coreresource.go ├── coreresource_test.go ├── dtls.go ├── empty.go ├── event.go ├── event_test.go ├── examples/ │ ├── block1/ │ │ ├── client.go │ │ ├── ietf-block.htm │ │ └── server.go │ ├── discovery/ │ │ └── main.go │ ├── dtls/ │ │ └── simple-psk/ │ │ ├── client.go │ │ └── server.go │ ├── observe/ │ │ ├── client.go │ │ └── server.go │ ├── proxy/ │ │ ├── coap/ │ │ │ ├── client.go │ │ │ ├── proxy.go │ │ │ └── server.go │ │ └── http/ │ │ ├── client.go │ │ └── server.go │ └── simple/ │ ├── client.go │ └── server.go ├── init.go ├── json.go ├── message.go ├── message_test.go ├── options.go ├── plaintext.go ├── proxy.go ├── request.go ├── request_test.go ├── response.go ├── response_test.go ├── routes.go ├── routes_test.go ├── server.go ├── server_test.go ├── serverconn.go ├── session.go ├── test-coverage.sh ├── types.go ├── utilconn_test.go ├── utildebug.go ├── utils.go ├── utils_test.go └── xml.go ================================================ FILE CONTENTS ================================================ ================================================ FILE: .gitignore ================================================ # Compiled Object files, Static and Dynamic libs (Shared Objects) *.o *.a *.so # Folders _obj _test # Architecture specific extensions/prefixes *.[568vq] [568vq].out *.cgo1.go *.cgo2.c _cgo_defun.c _cgo_gotypes.go _cgo_export.* _testmain.go *.exe *.test *.prof Godeps/_workspace Readme ================================================ FILE: .gitmodules ================================================ [submodule "openssl"] path = openssl url = https://github.com/openssl/openssl.git ================================================ FILE: Godeps/Godeps.json ================================================ { "ImportPath": "github.com/zubairhamed/canopus", "GoVersion": "go1.7", "Deps": [ { "ImportPath": "github.com/davecgh/go-spew/spew", "Rev": "5215b55f46b2b919f50a1df0eaa5886afe4e3b3d" }, { "ImportPath": "github.com/pmezard/go-difflib/difflib", "Rev": "d8ed2627bdf02c080bf22230dbb337003b7aba2d" }, { "ImportPath": "github.com/stretchr/testify/assert", "Comment": "v1.0-80-g67106a5", "Rev": "67106a5111a06241c8d84952c33214675f51a34a" } ] } ================================================ FILE: LICENSE ================================================ Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "{}" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright 2015, Zubair Hamed Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ================================================ FILE: README.md ================================================ # Canopus [![GoDoc](https://godoc.org/github.com/zubairhamed/canopus?status.svg)](https://godoc.org/github.com/zubairhamed/canopus) [![Build Status](https://drone.io/github.com/zubairhamed/canopus/status.png?)](https://drone.io/github.com/zubairhamed/canopus/latest) [![Coverage Status](https://coveralls.io/repos/zubairhamed/canopus/badge.svg?branch=master)](https://coveralls.io/r/zubairhamed/canopus?branch=master) [![Go Report Card](https://goreportcard.com/badge/github.com/zubairhamed/canopus)](https://goreportcard.com/report/github.com/zubairhamed/canopus) #### Canopus is a client/server implementation of the [Constrained Application Protocol (CoAP)][RFC7252] [RFC7252]: http://tools.ietf.org/html/rfc7252 ## Updates #### 25.11.2016 I've added basic dTLS Support based on [Julien Vermillard's][JVERMILLARD] [implementation][NATIVEDTLS]. Thanks Julien! It should now support PSK-based authentication. I've also gone ahead and refactored the APIs to make it that bit more Go idiomatic. [JVERMILLARD]: https://github.com/jvermillard [NATIVEDTLS]: https://github.com/jvermillard/nativedtls ## Building and running 1. git submodule update --init --recursive 2. cd openssl 3. ./config && make 4. You should then be able to run the examples in the /examples folder #### Simple Example ```go // Server // See /examples/simple/server/main.go server := canopus.NewServer() server.Get("/hello", func(req canopus.Request) canopus.Response { msg := canopus.ContentMessage(req.GetMessage().GetMessageId(), canopus.MessageAcknowledgment) msg.SetStringPayload("Acknowledged: " + req.GetMessage().GetPayload().String()) res := canopus.NewResponse(msg, nil) return res }) server.ListenAndServe(":5683") // Client // See /examples/simple/client/main.go conn, err := canopus.Dial("localhost:5683") if err != nil { panic(err.Error()) } req := canopus.NewRequest(canopus.MessageConfirmable, canopus.Get, canopus.GenerateMessageID()).(*canopus.CoapRequest) req.SetStringPayload("Hello, canopus") req.SetRequestURI("/hello") resp, err := conn.Send(req) if err != nil { panic(err.Error()) } fmt.Println("Got Response:" + resp.GetMessage().GetPayload().String()) ``` #### Observe / Notify ```go // Server // See /examples/observe/server/main.go server := canopus.NewServer() server.Get("/watch/this", func(req canopus.Request) canopus.Response { msg := canopus.NewMessageOfType(canopus.MessageAcknowledgment, req.GetMessage().GetMessageId(), canopus.NewPlainTextPayload("Acknowledged")) res := canopus.NewResponse(msg, nil) return res }) ticker := time.NewTicker(3 * time.Second) go func() { for { select { case <-ticker.C: changeVal := strconv.Itoa(rand.Int()) fmt.Println("[SERVER << ] Change of value -->", changeVal) server.NotifyChange("/watch/this", changeVal, false) } } }() server.OnObserve(func(resource string, msg canopus.Message) { fmt.Println("[SERVER << ] Observe Requested for " + resource) }) server.ListenAndServe(":5683") // Client // See /examples/observe/client/main.go conn, err := canopus.Dial("localhost:5683") tok, err := conn.ObserveResource("/watch/this") if err != nil { panic(err.Error()) } obsChannel := make(chan canopus.ObserveMessage) done := make(chan bool) go conn.Observe(obsChannel) notifyCount := 0 for { select { case obsMsg, _ := <-obsChannel: if notifyCount == 5 { fmt.Println("[CLIENT >> ] Canceling observe after 5 notifications..") go conn.CancelObserveResource("watch/this", tok) go conn.StopObserve(obsChannel) return } else { notifyCount++ // msg := obsMsg.Msg\ resource := obsMsg.GetResource() val := obsMsg.GetValue() fmt.Println("[CLIENT >> ] Got Change Notification for resource and value: ", notifyCount, resource, val) } } } ``` ### dTLS with PSK ```go // Server // See /examples/dtls/simple-psk/server/main.go server := canopus.NewServer() server.Get("/hello", func(req canopus.Request) canopus.Response { msg := canopus.ContentMessage(req.GetMessage().GetMessageId(), canopus.MessageAcknowledgment) msg.SetStringPayload("Acknowledged: " + req.GetMessage().GetPayload().String()) res := canopus.NewResponse(msg, nil) return res }) server.HandlePSK(func(id string) []byte { return []byte("secretPSK") }) server.ListenAndServeDTLS(":5684") // Client // See /examples/dtls/simple-psk/client/main.go conn, err := canopus.DialDTLS("localhost:5684", "canopus", "secretPSK") if err != nil { panic(err.Error()) } req := canopus.NewRequest(canopus.MessageConfirmable, canopus.Get, canopus.GenerateMessageID()) req.SetStringPayload("Hello, canopus") req.SetRequestURI("/hello") resp, err := conn.Send(req) if err != nil { panic(err.Error()) } fmt.Println("Got Response:" + resp.GetMessage().GetPayload().String()) ``` #### CoAP-CoAP Proxy ```go // Server // See /examples/proxy/coap/server/main.go server := canopus.NewServer() server.Get("/proxycall", func(req canopus.Request) canopus.Response { msg := canopus.ContentMessage(req.GetMessage().GetMessageId(), canopus.MessageAcknowledgment) msg.SetStringPayload("Data from :5685 -- " + req.GetMessage().GetPayload().String()) res := canopus.NewResponse(msg, nil) return res }) server.ListenAndServe(":5685") // Proxy Server // See /examples/proxy/coap/proxy/main.go server := canopus.NewServer() server.ProxyOverCoap(true) server.Get("/proxycall", func(req canopus.Request) canopus.Response { canopus.PrintMessage(req.GetMessage()) msg := canopus.ContentMessage(req.GetMessage().GetMessageId(), canopus.MessageAcknowledgment) msg.SetStringPayload("Acknowledged: " + req.GetMessage().GetPayload().String()) res := canopus.NewResponse(msg, nil) return res }) server.ListenAndServe(":5683") // Client // See /examples/proxy/coap/client/main.go conn, err := canopus.Dial("localhost:5683") if err != nil { panic(err.Error()) } req := canopus.NewRequest(canopus.MessageConfirmable, canopus.Get, canopus.GenerateMessageID()) req.SetProxyURI("coap://localhost:5685/proxycall") resp, err := conn.Send(req) if err != nil { println("err", err) } canopus.PrintMessage(resp.GetMessage()) ``` #### CoAP-HTTP Proxy ```go // Server // See /examples/proxy/http/server/main.go server := canopus.NewServer() server.ProxyOverHttp(true) server.ListenAndServe(":5683") // Client // See /examples/proxy/http/client/main.go conn, err := canopus.Dial("localhost:5683") if err != nil { panic(err.Error()) } req := canopus.NewRequest(canopus.MessageConfirmable, canopus.Get, canopus.GenerateMessageID()) req.SetProxyURI("https://httpbin.org/get") resp, err := conn.Send(req) if err != nil { println("err", err) } canopus.PrintMessage(resp.GetMessage()) ``` ================================================ FILE: bytecontent.go ================================================ package canopus // Represents a message payload containing an array of bytes func NewBytesPayload(v []byte) MessagePayload { return &BytesPayload{ content: v, } } type BytesPayload struct { content []byte } func (p *BytesPayload) GetBytes() []byte { return p.content } func (p *BytesPayload) Length() int { return len(p.content) } func (p *BytesPayload) String() string { return string(p.content) } ================================================ FILE: canopus.go ================================================ package canopus import ( "errors" "math/rand" "net" "sync" "time" ) // CurrentMessageID stores the current message id used/generated for messages var CurrentMessageID = 0 var MESSAGEID_MUTEX *sync.Mutex func init() { rand.Seed(time.Now().UTC().UnixNano()) CurrentMessageID = rand.Intn(65535) MESSAGEID_MUTEX = &sync.Mutex{} } var GENERATE_ID uint16 = 0 const UDP = "udp" // Types of Messages const ( MessageConfirmable = 0 MessageNonConfirmable = 1 MessageAcknowledgment = 2 MessageReset = 3 ) // Fragments/parts of a CoAP Message packet const ( DataHeader = 0 DataCode = 1 DataMsgIDStart = 2 DataMsgIDEnd = 4 DataTokenStart = 4 ) // OptionCode type represents a valid CoAP Option Code type OptionCode int const ( // OptionIfMatch request-header field is used with a method to make it conditional. // A client that has one or more entities previously obtained from the resource can verify // that one of those entities is current by including a list of their associated entity tags // in the If-Match header field. OptionIfMatch OptionCode = 1 OptionURIHost OptionCode = 3 OptionEtag OptionCode = 4 OptionIfNoneMatch OptionCode = 5 OptionObserve OptionCode = 6 OptionURIPort OptionCode = 7 OptionLocationPath OptionCode = 8 OptionURIPath OptionCode = 11 OptionContentFormat OptionCode = 12 OptionMaxAge OptionCode = 14 OptionURIQuery OptionCode = 15 OptionAccept OptionCode = 17 OptionLocationQuery OptionCode = 20 OptionBlock2 OptionCode = 23 OptionBlock1 OptionCode = 27 OptionSize2 OptionCode = 28 OptionProxyURI OptionCode = 35 OptionProxyScheme OptionCode = 39 OptionSize1 OptionCode = 60 ) // CoapCode defines a valid CoAP Code Type type CoapCode uint8 const ( Get CoapCode = 1 Post CoapCode = 2 Put CoapCode = 3 Delete CoapCode = 4 // 2.x CoapCodeEmpty CoapCode = 0 CoapCodeCreated CoapCode = 65 // 2.01 CoapCodeDeleted CoapCode = 66 // 2.02 CoapCodeValid CoapCode = 67 // 2.03 CoapCodeChanged CoapCode = 68 // 2.04 CoapCodeContent CoapCode = 69 // 2.05 CoapCodeContinue CoapCode = 95 // 2.31 // 4.x CoapCodeBadRequest CoapCode = 128 // 4.00 CoapCodeUnauthorized CoapCode = 129 // 4.01 CoapCodeBadOption CoapCode = 130 // 4.02 CoapCodeForbidden CoapCode = 131 // 4.03 CoapCodeNotFound CoapCode = 132 // 4.04 CoapCodeMethodNotAllowed CoapCode = 133 // 4.05 CoapCodeNotAcceptable CoapCode = 134 // 4.06 CoapCodeRequestEntityIncomplete CoapCode = 136 // 4.08 CoapCodeConflict CoapCode = 137 // 4.09 CoapCodePreconditionFailed CoapCode = 140 // 4.12 CoapCodeRequestEntityTooLarge CoapCode = 141 // 4.13 CoapCodeUnsupportedContentFormat CoapCode = 143 // 4.15 // 5.x CoapCodeInternalServerError CoapCode = 160 // 5.00 CoapCodeNotImplemented CoapCode = 161 // 5.01 CoapCodeBadGateway CoapCode = 162 // 5.02 CoapCodeServiceUnavailable CoapCode = 163 // 5.03 CoapCodeGatewayTimeout CoapCode = 164 // 5.04 CoapCodeProxyingNotSupported CoapCode = 165 // 5.05 ) const DefaultAckTimeout = 2 const DefaultAckRandomFactor = 1.5 const DefaultMaxRetransmit = 4 const DefaultNStart = 1 const DefaultLeisure = 5 const DefaultProbingRate = 1 const CoapDefaultHost = "" const CoapDefaultPort = 5683 const CoapsDefaultPort = 5684 const PayloadMarker = 0xff const MaxPacketSize = 1500 // MessageIDPurgeDuration defines the number of seconds before a MessageID Purge is initiated const MessageIDPurgeDuration = 60 type RouteHandler func(Request) Response // Proxy Filter type ProxyFilter func(Message, net.Addr) bool type ProxyHandler func(c CoapServer, msg Message, session Session) type MediaType int const ( MediaTypeTextPlain MediaType = 0 MediaTypeTextXML MediaType = 1 MediaTypeTextCsv MediaType = 2 MediaTypeTextHTML MediaType = 3 MediaTypeImageGif MediaType = 21 MediaTypeImageJpeg MediaType = 22 MediaTypeImagePng MediaType = 23 MediaTypeImageTiff MediaType = 24 MediaTypeAudioRaw MediaType = 25 MediaTypeVideoRaw MediaType = 26 MediaTypeApplicationLinkFormat MediaType = 40 MediaTypeApplicationXML MediaType = 41 MediaTypeApplicationOctetStream MediaType = 42 MediaTypeApplicationRdfXML MediaType = 43 MediaTypeApplicationSoapXML MediaType = 44 MediaTypeApplicationAtomXML MediaType = 45 MediaTypeApplicationXmppXML MediaType = 46 MediaTypeApplicationExi MediaType = 47 MediaTypeApplicationFastInfoSet MediaType = 48 MediaTypeApplicationSoapFastInfoSet MediaType = 49 MediaTypeApplicationJSON MediaType = 50 MediaTypeApplicationXObitBinary MediaType = 51 MediaTypeTextPlainVndOmaLwm2m MediaType = 1541 MediaTypeTlvVndOmaLwm2m MediaType = 1542 MediaTypeJSONVndOmaLwm2m MediaType = 1543 MediaTypeOpaqueVndOmaLwm2m MediaType = 1544 ) const ( MethodGet = "GET" MethodPut = "PUT" MethodPost = "POST" MethodDelete = "DELETE" MethodOptions = "OPTIONS" MethodPatch = "PATCH" ) type BlockSizeType byte const ( BlockSize16 BlockSizeType = 0 BlockSize32 BlockSizeType = 1 BlockSize64 BlockSizeType = 2 BlockSize128 BlockSizeType = 3 BlockSize256 BlockSizeType = 4 BlockSize512 BlockSizeType = 5 BlockSize1024 BlockSizeType = 6 ) // Errors var ErrPacketLengthLessThan4 = errors.New("Packet length less than 4 bytes") var ErrInvalidCoapVersion = errors.New("Invalid CoAP version. Should be 1.") var ErrOptionLengthUsesValue15 = errors.New(("Message format error. Option length has reserved value of 15")) var ErrOptionDeltaUsesValue15 = errors.New(("Message format error. Option delta has reserved value of 15")) var ErrUnknownMessageType = errors.New("Unknown message type") var ErrInvalidTokenLength = errors.New("Invalid Token Length ( > 8)") var ErrUnknownCriticalOption = errors.New("Unknown critical option encountered") var ErrUnsupportedMethod = errors.New("Unsupported Method") var ErrNoMatchingRoute = errors.New("No matching route found") var ErrUnsupportedContentFormat = errors.New("Unsupported Content-Format") var ErrNoMatchingMethod = errors.New("No matching method") var ErrNilMessage = errors.New("Message is nil") var ErrNilConn = errors.New("Connection object is nil") var ErrNilAddr = errors.New("Address cannot be nil") var ErrMessageSizeTooLongBlockOptionValNotSet = errors.New("Message is too long, block option or value not set") // Security Options const ( SecNoSec = "NoSec" SecPreSharedKey = "PreSharedKey" SecRawPublicKey = "RawPublicKey" SecCertificate = "Certificate" ) // Interfaces type CoapServer interface { ListenAndServe(addr string) ListenAndServeDTLS(addr string) Stop() Get(path string, fn RouteHandler) Route Delete(path string, fn RouteHandler) Route Put(path string, fn RouteHandler) Route Post(path string, fn RouteHandler) Route Options(path string, fn RouteHandler) Route Patch(path string, fn RouteHandler) Route NewRoute(path string, method CoapCode, fn RouteHandler) Route NotifyChange(resource, value string, confirm bool) OnNotify(fn FnEventNotify) OnStart(fn FnEventStart) OnClose(fn FnEventClose) OnDiscover(fn FnEventDiscover) OnError(fn FnEventError) OnObserve(fn FnEventObserve) OnObserveCancel(fn FnEventObserveCancel) OnMessage(fn FnEventMessage) OnBlockMessage(fn FnEventBlockMessage) ProxyOverHttp(enabled bool) ProxyOverCoap(enabled bool) GetEvents() Events AllowProxyForwarding(Message, net.Addr) bool GetRoutes() []Route ForwardCoap(msg Message, session Session) ForwardHTTP(msg Message, session Session) AddObservation(resource, token string, session Session) HasObservation(resource string, addr net.Addr) bool RemoveObservation(resource string, addr net.Addr) HandlePSK(func(id string) []byte) GetSession(addr string) Session DeleteSession(ssn Session) GetCookieSecret() []byte } type ServerConnection interface { ReadFrom(b []byte) (n int, addr net.Addr, err error) WriteTo(b []byte, addr net.Addr) (n int, err error) Close() error LocalAddr() net.Addr SetDeadline(t time.Time) error SetReadDeadline(t time.Time) error SetWriteDeadline(t time.Time) error } type Option interface { Name() string IsElective() bool IsCritical() bool StringValue() string IntValue() int GetCode() OptionCode GetValue() interface{} } type Session interface { GetConnection() ServerConnection GetAddress() net.Addr Write([]byte) (int, error) Read([]byte) (n int, err error) GetServer() CoapServer WriteBuffer([]byte) int } type Request interface { GetAttributes() map[string]string GetAttribute(o string) string GetAttributeAsInt(o string) int GetMessage() Message GetURIQuery(q string) string SetProxyURI(uri string) SetMediaType(mt MediaType) SetPayload([]byte) SetStringPayload(s string) SetRequestURI(uri string) SetConfirmable(con bool) SetToken(t string) SetURIQuery(k string, v string) } type Response interface { GetMessage() Message GetError() error GetPayload() []byte GetURIQuery(q string) string } type Connection interface { ObserveResource(resource string) (tok string, err error) CancelObserveResource(resource string, token string) (err error) StopObserve(ch chan ObserveMessage) Observe(ch chan ObserveMessage) Send(req Request) (resp Response, err error) Write(b []byte) (n int, err error) Read(b []byte) (n int, err error) Close() error } // Represents the payload/content of a CoAP Message type MessagePayload interface { GetBytes() []byte Length() int String() string } type Message interface { GetToken() []byte GetMessageId() uint16 GetMessageType() uint8 GetAcceptedContent() MediaType GetCodeString() string GetCode() CoapCode GetMethod() uint8 GetTokenLength() uint8 GetTokenString() string GetOptions(id OptionCode) []Option GetOption(id OptionCode) Option GetAllOptions() []Option GetOptionsAsString(id OptionCode) []string GetLocationPath() string GetURIPath() string GetPayload() MessagePayload SetToken([]byte) SetMessageId(uint16) SetMessageType(uint8) SetBlock1Option(opt Option) SetStringPayload(s string) SetPayload(MessagePayload) AddOption(code OptionCode, value interface{}) AddOptions(opts []Option) CloneOptions(cm Message, opts ...OptionCode) ReplaceOptions(code OptionCode, opts []Option) RemoveOptions(id OptionCode) } type Route interface { GetMethod() string GetMediaTypes() []MediaType GetConfiguredPath() string Matches(path string) (bool, map[string]string) AutoAcknowledge() bool Handle(req Request) Response } type FnEventNotify func(string, interface{}, Message) type FnEventStart func(CoapServer) type FnEventClose func(CoapServer) type FnEventDiscover func() type FnEventError func(error) type FnEventObserve func(string, Message) type FnEventObserveCancel func(string, Message) type FnEventMessage func(Message, bool) type FnEventBlockMessage func(Message, bool) type EventCode int const ( EventStart EventCode = 0 EventClose EventCode = 1 EventDiscover EventCode = 2 EventMessage EventCode = 3 EventError EventCode = 4 EventObserve EventCode = 5 EventObserveCancel EventCode = 6 EventNotify EventCode = 7 ) type ObserveMessage interface { GetResource() string GetValue() interface{} GetMessage() Message } type Events interface { OnNotify(fn FnEventNotify) OnStart(fn FnEventStart) OnClose(fn FnEventClose) OnDiscover(fn FnEventDiscover) OnError(fn FnEventError) OnObserve(fn FnEventObserve) OnObserveCancel(fn FnEventObserveCancel) OnMessage(fn FnEventMessage) OnBlockMessage(fn FnEventBlockMessage) Notify(resource string, value interface{}, msg Message) Started(server CoapServer) Closed(server CoapServer) Discover() Error(err error) Observe(resource string, msg Message) ObserveCancelled(resource string, msg Message) Message(msg Message, inbound bool) BlockMessage(msg Message, inbound bool) } type BlockMessage interface { } ================================================ FILE: client.go ================================================ package canopus import "net" func Dial(address string) (conn Connection, err error) { udpConn, err := net.Dial("udp", address) if err != nil { return } conn = &UDPConnection{ conn: udpConn, } return } func DialDTLS(address, identity, psk string) (conn Connection, err error) { udpConn, err := net.Dial("udp", address) if err != nil { return } conn, err = NewDTLSConnection(udpConn, identity, psk) if err != nil { return } return } func NewObserveMessage(r string, val interface{}, msg Message) ObserveMessage { return &CoapObserveMessage{ Resource: r, Value: val, Msg: msg, } } type CoapObserveMessage struct { CoapMessage Resource string Value interface{} Msg Message } func (m *CoapObserveMessage) GetResource() string { return m.Resource } func (m *CoapObserveMessage) GetValue() interface{} { return m.Value } func (m *CoapObserveMessage) GetMessage() Message { return m.GetMessage() } ================================================ FILE: conn.go ================================================ package canopus import ( "log" "net" "sync" ) func MessageSizeAllowed(req Request) bool { msg := req.GetMessage() b, _ := MessageToBytes(msg) if len(b) > 65536 { return false } return true } type UDPConnection struct { conn net.Conn } func (c *UDPConnection) ObserveResource(resource string) (tok string, err error) { req := NewRequest(MessageConfirmable, Get) req.SetRequestURI(resource) req.GetMessage().AddOption(OptionObserve, 0) resp, err := c.Send(req) tok = string(resp.GetMessage().GetToken()) return } func (c *UDPConnection) CancelObserveResource(resource string, token string) (err error) { req := NewRequest(MessageConfirmable, Get) req.SetRequestURI(resource) req.GetMessage().AddOption(OptionObserve, 1) _, err = c.Send(req) return } func (c *UDPConnection) StopObserve(ch chan ObserveMessage) { close(ch) } func (c *UDPConnection) Close() error { return c.conn.Close() } func (c *UDPConnection) Observe(ch chan ObserveMessage) { readBuf := make([]byte, MaxPacketSize) for { len, err := c.Read(readBuf) if err == nil { msgBuf := make([]byte, len) copy(msgBuf, readBuf) msg, err := BytesToMessage(msgBuf) if msg.GetOption(OptionObserve) != nil { ch <- NewObserveMessage(msg.GetURIPath(), msg.GetPayload(), msg) } if err != nil { log.Println("Error occured reading UDP", err) close(ch) } } else { log.Println("Error occured reading UDP", err) close(ch) } } } func (c *UDPConnection) Send(req Request) (resp Response, err error) { msg := req.GetMessage() opt := msg.GetOption(OptionBlock1) if opt == nil { // Block1 was not set if MessageSizeAllowed(req) != true { return nil, ErrMessageSizeTooLongBlockOptionValNotSet } } else { // Block1 was set // log.Println("Block 1 was set") } if opt != nil { blockOpt := Block1OptionFromOption(opt) if blockOpt.Value == nil { if MessageSizeAllowed(req) != true { err = ErrMessageSizeTooLongBlockOptionValNotSet return } else { // - Block # = one and only block (sz = unspecified), whereas 0 = 16bits // - MOre bit = 0 } } else { // BLock transfer request payload := msg.GetPayload().GetBytes() payloadLen := uint32(len(payload)) blockSize := blockOpt.BlockSizeLength() currSeq := uint32(0) totalBlocks := uint32(payloadLen / blockSize) completed := false var wg sync.WaitGroup wg.Add(1) for completed == false { if currSeq <= totalBlocks { var blockPayloadStart uint32 var blockPayloadEnd uint32 var blockPayload []byte blockPayloadStart = currSeq * uint32(blockSize) more := true if currSeq == totalBlocks { more = false blockPayloadEnd = payloadLen } else { blockPayloadEnd = blockPayloadStart + uint32(blockSize) } blockPayload = payload[blockPayloadStart : blockPayloadEnd+1] blockOpt = NewBlock1Option(blockOpt.Size(), more, currSeq) msg.ReplaceOptions(blockOpt.Code, []Option{blockOpt}) modifiedMsg := msg.(*CoapMessage) modifiedMsg.SetMessageId(GenerateMessageID()) modifiedMsg.SetPayload(NewBytesPayload(blockPayload)) // send message _, err2 := c.SendMessage(msg) if err2 != nil { wg.Done() return } currSeq = currSeq + 1 } else { completed = true wg.Done() } } } } resp, err = c.SendMessage(msg) return } func (c *UDPConnection) SendMessage(msg Message) (resp Response, err error) { if msg == nil { return nil, ErrNilMessage } b, err := MessageToBytes(msg) if err != nil { return } if msg.GetMessageType() == MessageNonConfirmable { go c.Write(b) resp = NewResponse(NewEmptyMessage(msg.GetMessageId()), nil) return } _, err = c.Write(b) if err != nil { return } msgBuf := make([]byte, 1500) if msg.GetMessageType() == MessageAcknowledgment { resp = NewResponse(NewEmptyMessage(msg.GetMessageId()), nil) return } n, err := c.Read(msgBuf) if err != nil { return } respMsg, err := BytesToMessage(msgBuf[:n]) if err != nil { return } resp = NewResponse(respMsg, nil) if msg.GetMessageType() == MessageConfirmable { // TODO: Send out message and wait for a confirm. If confirmation not retrieved, // resend (taking into account timeouts and back-off transmissions // c.Send(NewRequestFromMessage(msg)) } return } func (c *UDPConnection) Write(b []byte) (int, error) { return c.conn.Write(b) } func (c *UDPConnection) Read(b []byte) (int, error) { return c.conn.Read(b) } ================================================ FILE: corelink.go ================================================ package canopus // Represents a message payload containing core-link format values type CoreLinkFormatPayload struct { } func (p *CoreLinkFormatPayload) GetBytes() []byte { return make([]byte, 0) } func (p *CoreLinkFormatPayload) Length() int { return 0 } func (p *CoreLinkFormatPayload) String() string { return "" } ================================================ FILE: coreresource.go ================================================ package canopus // Instantiates a new core-attribute with a given key/value func NewCoreAttribute(key string, value interface{}) *CoreAttribute { return &CoreAttribute{ Key: key, Value: value, } } // Instantiates a new Core Resource Object func NewCoreResource() *CoreResource { c := &CoreResource{} return c } ================================================ FILE: coreresource_test.go ================================================ package canopus import ( "testing" "github.com/stretchr/testify/assert" ) func TestCoreResourceParsing(t *testing.T) { cases1 := []struct { in string elemCount int targets []string attrCount []int attributes []map[string]string }{ { ",,,,,,,", 8, []string{"/1", "/2", "/3", "/4", "/5/0", "/5/1", "/5/2", "/5/3"}, []int{0, 0, 0, 0, 0, 0, 0, 0, 0}, nil, }, { ";ct=40;title=\"Sensor Index\",;rt=\"temperature-c\";if=\"sensor\",;rt=\"light-lux\";if=\"sensor\",;anchor=\"/sensors/temp\";rel=\"describedby\",;anchor=\"/sensors/temp\";rel=\"alternate\"", 5, []string{"/sensors", "/sensors/temp", "/sensors/light", "http://www.example.com/sensors/t123", "/t"}, []int{1, 2, 2, 2, 2}, []map[string]string{ map[string]string{ "ct": "40", "title": "Sensor Index", }, map[string]string{ "rt": "temperature-c", "if": "sensor", }, map[string]string{ "rt": "light-lux", "if": "sensor", }, map[string]string{ "anchor": "/sensors/temp", "rel": "describedby", }, map[string]string{ "anchor": "/sensors/temp", "rel": "alternate", }, }, }, } for _, c := range cases1 { resources := CoreResourcesFromString(c.in) assert.Equal(t, len(resources), c.elemCount) for i, o := range resources { assert.Equal(t, o.Target, c.targets[i]) for _, a := range o.Attributes { key := a.Key val := a.Value assert.Equal(t, c.attributes[i][key], val) } } } } ================================================ FILE: dtls.go ================================================ package canopus /* #cgo LDFLAGS: -L${SRCDIR}/openssl -lssl -lcrypto -ldl #cgo CFLAGS: -g -Wno-deprecated -Wno-error -I${SRCDIR}/openssl/include -Wno-incompatible-pointer-types -Wno-return-type #include #include #include #include #include #include extern int go_session_bio_write(BIO* bio, char* buf, int num); extern int go_session_bio_read(BIO* bio, char* buf, int num); extern int go_session_bio_free(BIO* bio); extern unsigned int go_server_psk_callback(SSL *ssl, char *identity, char *psk, unsigned int max_psk_len); extern int generate_cookie_callback(SSL* ssl, unsigned char* cookie, unsigned int *cookie_len); extern int verify_cookie_callback(SSL* ssl, unsigned char* cookie, unsigned int cookie_len); static long go_session_bio_ctrl(BIO *bp,int cmd,long larg,void *parg) { return 1; } static int write_wrapper(BIO* bio, char* data, int n) { return go_session_bio_write(bio,data,n); } static int go_session_bio_create( BIO *b ) { BIO_set_init(b,1); BIO_set_flags(b, BIO_FLAGS_READ | BIO_FLAGS_WRITE); return 1; } // a BIO for a client conencted to our server static BIO_METHOD* go_session_bio_method; static BIO_METHOD* BIO_go_session() { return go_session_bio_method; } static void set_errno(int e) { errno = e; } static char *getGoData(BIO* bio) { return BIO_get_data(bio); } static unsigned int server_psk_callback(SSL *ssl, char *identity, unsigned char *psk, unsigned int max_psk_len) { return go_server_psk_callback(ssl,identity,(char*)psk,max_psk_len); } static void init_lib() { setvbuf(stdout, NULL, _IOLBF, 0); SSL_library_init(); ERR_load_BIO_strings(); SSL_load_error_strings(); } static int init_session_bio_method() { go_session_bio_method = BIO_meth_new(BIO_TYPE_SOURCE_SINK,"go session dtls"); BIO_meth_set_write(go_session_bio_method,write_wrapper); BIO_meth_set_read(go_session_bio_method,go_session_bio_read); BIO_meth_set_ctrl(go_session_bio_method,go_session_bio_ctrl); BIO_meth_set_create(go_session_bio_method,go_session_bio_create); BIO_meth_set_destroy(go_session_bio_method,go_session_bio_free); } static void init_server_ctx(SSL_CTX *ctx) { SSL_CTX_set_min_proto_version(ctx, 0xFEFD); // 1.2 SSL_CTX_set_max_proto_version(ctx, 0xFEFD); // 1.2 SSL_CTX_set_read_ahead(ctx, 1); SSL_CTX_set_cookie_generate_cb(ctx, &generate_cookie_callback); SSL_CTX_set_cookie_verify_cb(ctx, &verify_cookie_callback); } static int get_errno(void) { return errno; } static void setGoData(BIO* bio, char *data) { BIO_set_data(bio, data); } static void set_cookie_option(SSL *ssl) { SSL_set_options(ssl, SSL_OP_COOKIE_EXCHANGE); } static void set_psk_callback(SSL *ssl) { SSL_set_psk_server_callback(ssl, &server_psk_callback); } static void setGoSessionId(BIO* bio, unsigned int clientId) { unsigned int * pId = malloc(sizeof(unsigned int)); *pId = clientId; BIO_set_data(bio,pId); } // Client extern int go_conn_bio_write(BIO* bio, char* buf, int num); extern int go_conn_bio_read(BIO* bio, char* buf, int num); extern int go_conn_bio_free(BIO* bio); extern unsigned int go_psk_callback(SSL *ssl, char *hint, char *identity, unsigned int max_identity_len, char *psk, unsigned int max_psk_len); static long go_bio_ctrl(BIO *bp,int cmd,long larg,void *parg) { //always return operation not supported //http://www.openssl.org/docs/crypto/BIO_ctrl.html //printf("go_bio_ctrl %d\n", cmd); return 1; } static int go_bio_create( BIO *b ) { BIO_set_init(b,1); //BIO_set_num(b,-1); //BIO_set_ptr(b,NULL); BIO_set_flags(b, BIO_FLAGS_READ | BIO_FLAGS_WRITE); return 1; } static BIO_METHOD go_bio_method = { BIO_TYPE_SOURCE_SINK, "go dtls", (int (*)(BIO *, const char *, int))go_conn_bio_write, go_conn_bio_read, NULL, NULL, go_bio_ctrl, // ctrl go_bio_create, // new go_conn_bio_free // delete }; static BIO_METHOD* BIO_go() { return &go_bio_method; } static void set_proto_1_2(SSL_CTX *ctx) { SSL_CTX_set_min_proto_version(ctx, 0xFEFD); // 1.2 SSL_CTX_set_max_proto_version(ctx, 0xFEFD); // 1.2 } static unsigned int psk_callback(SSL *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len) { return go_psk_callback(ssl,hint,identity,max_identity_len,(char*)psk,max_psk_len); } static void init_ctx(SSL_CTX *ctx) { SSL_CTX_set_read_ahead(ctx, 1); SSL_CTX_set_psk_client_callback(ctx,&psk_callback); } static void setGoClientId(BIO* bio, unsigned int clientId) { unsigned int * pId = malloc(sizeof(unsigned int)); *pId = clientId; BIO_set_data(bio,pId); } */ import "C" import ( "bytes" "crypto/hmac" "crypto/sha256" "errors" "fmt" "io" "net" "reflect" "sync" "sync/atomic" "syscall" "unsafe" ) func init() { // low level init of OpenSSL C.init_lib() // init server BIO server_bio_method_init() } func server_bio_method_init() { C.init_session_bio_method() } func NewServerDtlsContext() (ctx *ServerDtlsContext, err error) { sslCtx := C.SSL_CTX_new(C.DTLSv1_2_server_method()) if sslCtx == nil { err = errors.New("error creating SSL context") return } C.init_server_ctx(sslCtx) ret := int(C.SSL_CTX_set_cipher_list(sslCtx, C.CString("PSK-AES256-CCM8:PSK-AES128-CCM8"))) if ret != 1 { err = errors.New("impossible to set cipherlist") } ctx = &ServerDtlsContext{ sslCtx: sslCtx, } return } type ServerDtlsContext struct { sslCtx *C.SSL_CTX } //export go_session_bio_read func go_session_bio_read(bio *C.BIO, buf *C.char, num C.int) C.int { session := DTLS_SERVER_SESSIONS[*(*int32)(C.BIO_get_data(bio))] socketData := <-session.rcvd data := goSliceFromCString(buf, int(num)) if data == nil { return 0 } wrote := copy(data, socketData) return C.int(wrote) } //export go_session_bio_write func go_session_bio_write(bio *C.BIO, buf *C.char, num C.int) C.int { session := DTLS_SERVER_SESSIONS[*(*int32)(C.BIO_get_data(bio))] data := goSliceFromCString(buf, int(num)) n, err := session.GetConnection().WriteTo(data, session.GetAddress()) if err != nil && err != io.EOF { //We expect either a syscall error //or a netOp error wrapping a syscall error TESTERR: switch err.(type) { case syscall.Errno: C.set_errno(C.int(err.(syscall.Errno))) case *net.OpError: err = err.(*net.OpError).Err break TESTERR } return C.int(-1) } return C.int(n) } //export go_session_bio_free func go_session_bio_free(bio *C.BIO) C.int { // TODO // some flags magic if C.int(C.BIO_get_shutdown(bio)) != 0 { C.BIO_set_data(bio, nil) C.BIO_set_flags(bio, 0) C.BIO_set_init(bio, 0) } return C.int(1) } //export go_server_psk_callback func go_server_psk_callback(ssl *C.SSL, identity *C.char, psk *C.char, max_psk_len C.uint) C.uint { bio := C.SSL_get_rbio(ssl) session := DTLS_SERVER_SESSIONS[*(*int32)(C.BIO_get_data(bio))] server := session.GetServer().(*DefaultCoapServer) goPskID := C.GoString(identity) serverPsk := server.fnPskHandler(goPskID) if serverPsk == nil { return 0 } if len(serverPsk) >= int(max_psk_len) { return 0 } targetPsk := goSliceFromCString(psk, int(max_psk_len)) return C.uint(copy(targetPsk, serverPsk)) } //export generate_cookie_callback func generate_cookie_callback(ssl *C.SSL, cookie *C.uchar, cookie_len *C.uint) C.int { bio := C.SSL_get_rbio(ssl) session := DTLS_SERVER_SESSIONS[*(*int32)(C.BIO_get_data(bio))] mac := hmac.New(sha256.New, session.GetServer().GetCookieSecret()) mac.Write([]byte(session.GetAddress().String())) cookieValue := mac.Sum(nil) if len(cookieValue) >= int(*cookie_len) { logMsg("Not enough cookie space (should not happen..)") return 0 } data := goSliceFromUCString(cookie, int(*cookie_len)) *cookie_len = C.uint(copy(data, cookieValue)) return 1 } //export verify_cookie_callback func verify_cookie_callback(ssl *C.SSL, cookie *C.uchar, cookie_len C.uint) C.int { bio := C.SSL_get_rbio(ssl) session := DTLS_SERVER_SESSIONS[*(*int32)(C.BIO_get_data(bio))] mac := hmac.New(sha256.New, session.GetServer().GetCookieSecret()) mac.Write([]byte(session.GetAddress().String())) cookieValue := mac.Sum(nil) if len(cookieValue) != int(cookie_len) { return 0 } data := goSliceFromUCString(cookie, int(cookie_len)) if bytes.Equal(data, cookieValue) { return 1 } else { return 0 } } // Provides a zero copy interface for returning a go slice backed by a c array. func goSliceFromCString(cArray *C.char, size int) (cslice []byte) { //See http://code.google.com/p/go-wiki/wiki/cgo //It turns out it's really easy to //make a string from a *C.char and vise versa. //not so easy to write to a c array. sliceHeader := (*reflect.SliceHeader)((unsafe.Pointer(&cslice))) sliceHeader.Cap = size sliceHeader.Len = size sliceHeader.Data = uintptr(unsafe.Pointer(cArray)) return } // Provides a zero copy interface for returning a go slice backed by a c array. func goSliceFromUCString(cArray *C.uchar, size int) (cslice []byte) { //See http://code.google.com/p/go-wiki/wiki/cgo //It turns out it's really easy to //make a string from a *C.char and vise versa. //not so easy to write to a c array. sliceHeader := (*reflect.SliceHeader)((unsafe.Pointer(&cslice))) sliceHeader.Cap = size sliceHeader.Len = size sliceHeader.Data = uintptr(unsafe.Pointer(cArray)) return } func getErrorString(code C.ulong) string { if code == 0 { return "" } msg := fmt.Sprintf("%s:%s:%s\n", C.GoString(C.ERR_lib_error_string(code)), C.GoString(C.ERR_func_error_string(code)), C.GoString(C.ERR_reason_error_string(code))) if len(msg) == 4 { //being lazy here, all the strings were empty return "" } //Check for extra line data var file *C.char var line C.int var data *C.char var flags C.int if int(C.ERR_get_error_line_data(&file, &line, &data, &flags)) != 0 { msg += fmt.Sprintf("%s:%s", C.GoString(file), int(line)) if flags&C.ERR_TXT_STRING != 0 { msg += ":" + C.GoString(data) } if flags&C.ERR_TXT_MALLOCED != 0 { C.CRYPTO_free(unsafe.Pointer(data), C.CString(""), 0) } } return msg } func newSslSession(session *DTLSServerSession, ctx *ServerDtlsContext, pskCallback func(id string) []byte) (err error) { ssl := C.SSL_new(ctx.sslCtx) id := atomic.AddInt32(&NEXT_SESSION_ID, 1) if pskCallback != nil { C.set_psk_callback(ssl) } bio := C.BIO_new(C.BIO_go_session()) if bio == nil { err = errors.New("Error creating session: Bio is nil") return } C.SSL_set_bio(ssl, bio, bio) session.ssl = ssl session.bio = bio DTLS_SERVER_SESSIONS[id] = session C.setGoSessionId(bio, C.uint(id)) C.set_cookie_option(ssl) C.SSL_set_accept_state(ssl) C.DTLSv1_listen return } type DTLSServerSession struct { UDPServerSession ssl *C.SSL bio *C.BIO } func (s *DTLSServerSession) GetConnection() ServerConnection { return s.conn } func (s *DTLSServerSession) Write(b []byte) (int, error) { // TODO test is connected ? length := len(b) ret := C.SSL_write(s.ssl, unsafe.Pointer(&b[0]), C.int(length)) if err := s.getError(ret); err != nil { return 0, err } return int(ret), nil } func (s *DTLSServerSession) Read(b []byte) (n int, err error) { // TODO test if closed? length := len(b) // s.rcvd <- s.buf ret := C.SSL_read(s.ssl, unsafe.Pointer(&b[0]), C.int(length)) if err = s.getError(ret); err != nil { n = 0 return } // if there's no error, but a return value of 0 // let's say it's an EOF if ret == 0 { n = 0 err = io.EOF return } n = int(ret) return } func (s *DTLSServerSession) getError(ret C.int) error { err := C.SSL_get_error(s.ssl, ret) switch err { case C.SSL_ERROR_NONE: return nil case C.SSL_ERROR_ZERO_RETURN: return io.EOF case C.SSL_ERROR_SYSCALL: if int(C.ERR_peek_error()) != 0 { return syscall.Errno(C.get_errno()) } default: msg := "" for { errCode := C.ERR_get_error() if errCode == 0 { break } msg += getErrorString(errCode) } C.ERR_clear_error() return errors.New(msg) } return nil } // Client DTLS func NewDTLSConnection(c net.Conn, identity, psk string) (conn Connection, err error) { sslCtx := C.SSL_CTX_new(C.DTLSv1_2_client_method()) C.set_proto_1_2(sslCtx) C.init_ctx(sslCtx) ret := int(C.SSL_CTX_set_cipher_list(sslCtx, C.CString("PSK-AES256-CCM8:PSK-AES128-CCM8"))) if ret != 1 { err = errors.New("impossible to set cipherlist") return } ssl := C.SSL_new(sslCtx) // self := DTLSClient{false, 0, C.BIO_new(C.BIO_go()), dtlsCtx.ctx, ssl, conn, nil, nil} bio := C.BIO_new(C.BIO_go()) conn = &DTLSConnection{ UDPConnection: UDPConnection{ conn: c, }, sslCtx: sslCtx, ssl: ssl, bio: bio, psk: []byte(psk), pskId: &identity, } C.SSL_set_bio(ssl, bio, bio) id := atomic.AddInt32(&NEXT_SESSION_ID, 1) C.setGoClientId(bio, C.uint(id)) DTLS_CLIENT_CONNECTIONS[id] = conn.(*DTLSConnection) return } type DTLSConnection struct { UDPConnection closed bool connected int32 // connection handshake was done, atomic (0 false, 1 true) sslCtx *C.SSL_CTX bio *C.BIO ssl *C.SSL pskId *string psk []byte } func (c *DTLSConnection) ObserveResource(resource string) (tok string, err error) { req := NewRequest(MessageConfirmable, Get) req.SetRequestURI(resource) req.GetMessage().AddOption(OptionObserve, 0) resp, err := c.Send(req) tok = string(resp.GetMessage().GetToken()) return } func (c *DTLSConnection) CancelObserveResource(resource string, token string) (err error) { req := NewRequest(MessageConfirmable, Get) req.SetRequestURI(resource) req.GetMessage().AddOption(OptionObserve, 1) _, err = c.Send(req) return } func (c *DTLSConnection) StopObserve(ch chan ObserveMessage) { close(ch) } func (c *DTLSConnection) Observe(ch chan ObserveMessage) { readBuf := make([]byte, MaxPacketSize) for { len, err := c.Read(readBuf) if err == nil { msgBuf := make([]byte, len) copy(msgBuf, readBuf) msg, err := BytesToMessage(msgBuf) if msg.GetOption(OptionObserve) != nil { ch <- NewObserveMessage(msg.GetURIPath(), msg.GetPayload(), msg) } if err != nil { logMsg("Error occured reading UDP", err) close(ch) } } else { logMsg("Error occured reading UDP", err) close(ch) } } } func (c *DTLSConnection) Send(req Request) (resp Response, err error) { msg := req.GetMessage() opt := msg.GetOption(OptionBlock1) if opt == nil { // Block1 was not set if MessageSizeAllowed(req) != true { return nil, ErrMessageSizeTooLongBlockOptionValNotSet } } else { // Block1 was set // fmt.Println("Block 1 was set") } if opt != nil { blockOpt := Block1OptionFromOption(opt) if blockOpt.Value == nil { if MessageSizeAllowed(req) != true { err = ErrMessageSizeTooLongBlockOptionValNotSet return } else { // - Block # = one and only block (sz = unspecified), whereas 0 = 16bits // - MOre bit = 0 } } else { // BLock transfer request payload := msg.GetPayload().GetBytes() payloadLen := uint32(len(payload)) blockSize := blockOpt.BlockSizeLength() currSeq := uint32(0) totalBlocks := uint32(payloadLen / blockSize) completed := false var wg sync.WaitGroup wg.Add(1) for completed == false { if currSeq <= totalBlocks { var blockPayloadStart uint32 var blockPayloadEnd uint32 var blockPayload []byte blockPayloadStart = currSeq*uint32(blockSize) + (currSeq * 1) more := true if currSeq == totalBlocks { more = false blockPayloadEnd = payloadLen } else { blockPayloadEnd = blockPayloadStart + uint32(blockSize) } blockPayload = payload[blockPayloadStart:blockPayloadEnd] blockOpt = NewBlock1Option(blockOpt.Size(), more, currSeq) msg.ReplaceOptions(blockOpt.Code, []Option{blockOpt}) modifiedMsg := msg.(*CoapMessage) modifiedMsg.SetMessageId(GenerateMessageID()) modifiedMsg.SetPayload(NewBytesPayload(blockPayload)) // send message _, err2 := c.sendMessage(msg) if err2 != nil { wg.Done() return } currSeq = currSeq + 1 } else { completed = true wg.Done() } } } } resp, err = c.sendMessage(msg) return } func (c *DTLSConnection) sendMessage(msg Message) (resp Response, err error) { if msg == nil { return nil, ErrNilMessage } b, err := MessageToBytes(msg) if err != nil { return } if msg.GetMessageType() == MessageNonConfirmable { go c.Write(b) resp = NewResponse(NewEmptyMessage(msg.GetMessageId()), nil) return } _, err = c.Write(b) if err != nil { return } msgBuf := make([]byte, 1500) if msg.GetMessageType() == MessageAcknowledgment { resp = NewResponse(NewEmptyMessage(msg.GetMessageId()), nil) return } n, err := c.Read(msgBuf) if err != nil { return } respMsg, err := BytesToMessage(msgBuf[:n]) if err != nil { return } resp = NewResponse(respMsg, nil) if msg.GetMessageType() == MessageConfirmable { // TODO: Send out message and wait for a confirm. If confirmation not retrieved, // resend (taking into account timeouts and back-off transmissions // c.Send(NewRequestFromMessage(msg)) } return } func (c *DTLSConnection) Write(b []byte) (int, error) { if atomic.CompareAndSwapInt32(&c.connected, 0, 1) { if err := c.connect(); err != nil { return 0, err } } length := len(b) ret := C.SSL_write(c.ssl, unsafe.Pointer(&b[0]), C.int(length)) if err := c.getError(ret); err != nil { return 0, err } return int(ret), nil } func (c *DTLSConnection) Read(b []byte) (int, error) { if atomic.CompareAndSwapInt32(&c.connected, 0, 1) { if err := c.connect(); err != nil { return 0, err } } length := len(b) ret := C.SSL_read(c.ssl, unsafe.Pointer(&b[0]), C.int(length)) if err := c.getError(ret); err != nil { return 0, err } // if there's no error, but a return value of 0 // let's say it's an EOF if ret == 0 { return 0, io.EOF } return int(ret), nil } func (c *DTLSConnection) Close() error { if c.closed { return nil } c.closed = true defer func() { C.SSL_free(c.ssl) }() ret := C.SSL_shutdown(c.ssl) if int(ret) == 0 { ret = C.SSL_shutdown(c.ssl) if int(ret) != 1 { return c.getError(ret) } } return nil } func (c *DTLSConnection) connect() error { ret := C.SSL_connect(c.ssl) if err := c.getError(ret); err != nil { return err } return nil } func (c *DTLSConnection) getError(ret C.int) error { err := C.SSL_get_error(c.ssl, ret) switch err { case C.SSL_ERROR_NONE: return nil case C.SSL_ERROR_ZERO_RETURN: return io.EOF case C.SSL_ERROR_SYSCALL: if int(C.ERR_peek_error()) != 0 { return syscall.Errno(C.get_errno()) } default: msg := "" for { errCode := C.ERR_get_error() if errCode == 0 { break } msg += getErrorString(errCode) } C.ERR_clear_error() return errors.New(msg) } return nil } //export go_conn_bio_write func go_conn_bio_write(bio *C.BIO, buf *C.char, num C.int) C.int { client := DTLS_CLIENT_CONNECTIONS[*(*int32)(C.BIO_get_data(bio))] data := goSliceFromCString(buf, int(num)) n, err := client.conn.Write(data) if err != nil && err != io.EOF { //We expect either a syscall error //or a netOp error wrapping a syscall error TESTERR: switch err.(type) { case syscall.Errno: C.set_errno(C.int(err.(syscall.Errno))) case *net.OpError: err = err.(*net.OpError).Err break TESTERR } return C.int(-1) } return C.int(n) } //export go_conn_bio_read func go_conn_bio_read(bio *C.BIO, buf *C.char, num C.int) C.int { client := DTLS_CLIENT_CONNECTIONS[*(*int32)(C.BIO_get_data(bio))] data := goSliceFromCString(buf, int(num)) n, err := client.conn.Read(data) if err == nil { return C.int(n) } if err == io.EOF || err == io.ErrUnexpectedEOF { return 0 } //We expect either a syscall error //or a netOp error wrapping a syscall error TESTERR: switch err.(type) { case syscall.Errno: C.set_errno(C.int(err.(syscall.Errno))) case *net.OpError: err = err.(*net.OpError).Err break TESTERR } return C.int(-1) } //export go_conn_bio_free func go_conn_bio_free(bio *C.BIO) C.int { client := DTLS_CLIENT_CONNECTIONS[*(*int32)(C.BIO_get_data(bio))] client.Close() if C.int(C.BIO_get_shutdown(bio)) != 0 { C.BIO_set_data(bio, nil) C.BIO_set_flags(bio, 0) C.BIO_set_init(bio, 0) } return C.int(1) } //export go_psk_callback func go_psk_callback(ssl *C.SSL, hint *C.char, identity *C.char, max_identity_len C.uint, psk *C.char, max_psk_len C.uint) C.uint { bio := C.SSL_get_rbio(ssl) client := DTLS_CLIENT_CONNECTIONS[*(*int32)(C.BIO_get_data(bio))] if client.pskId == nil || client.psk == nil { return 0 } if len(*client.pskId) >= int(max_identity_len) || len(client.psk) >= int(max_psk_len) { logMsg("PSKID or PSK too large") return 0 } targetId := goSliceFromCString(identity, int(max_identity_len)) copy(targetId, *client.pskId) targetPsk := goSliceFromCString(psk, int(max_psk_len)) return C.uint(copy(targetPsk, client.psk)) } ================================================ FILE: empty.go ================================================ package canopus func NewEmptyPayload() MessagePayload { return &EmptyPayload{} } // Represents an empty message payload type EmptyPayload struct { } func (p *EmptyPayload) GetBytes() []byte { return []byte{} } func (p *EmptyPayload) Length() int { return 0 } func (p *EmptyPayload) String() string { return "" } ================================================ FILE: event.go ================================================ package canopus func NewEvents() *ServerEvents { return &ServerEvents{ evtFnNotify: []FnEventNotify{}, evtFnStart: []FnEventStart{}, evtFnClose: []FnEventClose{}, evtFnDiscover: []FnEventDiscover{}, evtFnError: []FnEventError{}, evtFnObserve: []FnEventObserve{}, evtFnObserveCancel: []FnEventObserveCancel{}, evtFnMessage: []FnEventMessage{}, evtFnBlockMessage: []FnEventBlockMessage{}, } } // This holds the various events which are triggered throughout // an application's lifetime type ServerEvents struct { evtFnNotify []FnEventNotify evtFnStart []FnEventStart evtFnClose []FnEventClose evtFnDiscover []FnEventDiscover evtFnError []FnEventError evtFnObserve []FnEventObserve evtFnObserveCancel []FnEventObserveCancel evtFnMessage []FnEventMessage evtFnBlockMessage []FnEventBlockMessage } // OnNotify is Fired when an observeed resource is notified func (ce *ServerEvents) OnNotify(fn FnEventNotify) { ce.evtFnNotify = append(ce.evtFnNotify, fn) } // Fired when the server/client starts up func (ce *ServerEvents) OnStart(fn FnEventStart) { ce.evtFnStart = append(ce.evtFnStart, fn) } // Fired when the server/client closes func (ce *ServerEvents) OnClose(fn FnEventClose) { ce.evtFnClose = append(ce.evtFnClose, fn) } // Fired when a discovery request is triggered func (ce *ServerEvents) OnDiscover(fn FnEventDiscover) { ce.evtFnDiscover = append(ce.evtFnDiscover, fn) } // Catch-all event which is fired when an error occurs func (ce *ServerEvents) OnError(fn FnEventError) { ce.evtFnError = append(ce.evtFnError, fn) } // Fired when an observe request is triggered for a resource func (ce *ServerEvents) OnObserve(fn FnEventObserve) { ce.evtFnObserve = append(ce.evtFnObserve, fn) } // Fired when an observe-cancel request is triggered foa r esource func (ce *ServerEvents) OnObserveCancel(fn FnEventObserveCancel) { ce.evtFnObserveCancel = append(ce.evtFnObserveCancel, fn) } // Fired when a message is received func (ce *ServerEvents) OnMessage(fn FnEventMessage) { ce.evtFnMessage = append(ce.evtFnMessage, fn) } // Fired when a block messageis received func (ce *ServerEvents) OnBlockMessage(fn FnEventBlockMessage) { ce.evtFnBlockMessage = append(ce.evtFnBlockMessage, fn) } // Fires the "OnNotify" event func (ce *ServerEvents) Notify(resource string, value interface{}, msg Message) { for _, fn := range ce.evtFnNotify { fn(resource, value, msg) } } // Fires the "OnStarted" event func (ce *ServerEvents) Started(server CoapServer) { for _, fn := range ce.evtFnStart { fn(server) } } // Fires the "OnClosed" event func (ce *ServerEvents) Closed(server CoapServer) { for _, fn := range ce.evtFnClose { fn(server) } } // Fires the "OnDiscover" event func (ce *ServerEvents) Discover() { for _, fn := range ce.evtFnDiscover { fn() } } // Fires the "OnError" event given an error object func (ce *ServerEvents) Error(err error) { for _, fn := range ce.evtFnError { fn(err) } } // Fires the "OnObserve" event for a given resource func (ce *ServerEvents) Observe(resource string, msg Message) { for _, fn := range ce.evtFnObserve { fn(resource, msg) } } // Fires the "OnObserveCancelled" event for a given resource func (ce *ServerEvents) ObserveCancelled(resource string, msg Message) { for _, fn := range ce.evtFnObserveCancel { fn(resource, msg) } } // Fires the "OnMessage" event. The 'inbound' variables determines if the // message is inbound or outgoing func (ce *ServerEvents) Message(msg Message, inbound bool) { for _, fn := range ce.evtFnMessage { fn(msg, inbound) } } // Fires the "OnBlockMessage" event. The 'inbound' variables determines if the // message is inbound or outgoing func (ce *ServerEvents) BlockMessage(msg Message, inbound bool) { for _, fn := range ce.evtFnBlockMessage { fn(msg, inbound) } } ================================================ FILE: event_test.go ================================================ package canopus import ( "errors" "testing" "time" "github.com/stretchr/testify/assert" ) func TestEvents(t *testing.T) { events := NewEvents() assert.NotNil(t, events) // OnNotify evtOnNotifyCalled := false events.OnNotify(func(string, interface{}, Message) { evtOnNotifyCalled = true }) events.Notify("/test", "", nil) // OnStarted evtOnStartedCalled := false events.OnStart(func(CoapServer) { evtOnStartedCalled = true }) events.Started(nil) // OnClosed evtOnClosedCalled := false events.OnClose(func(CoapServer) { evtOnClosedCalled = true }) events.Closed(nil) // OnDiscover evtOnDiscoverCalled := false events.OnDiscover(func() { evtOnDiscoverCalled = true }) events.Discover() // OnError evtOnErrorCalled := false events.OnError(func(error) { evtOnErrorCalled = true }) events.Error(errors.New("An error occured")) // OnObserve evtOnObserveCalled := false events.OnObserve(func(string, Message) { evtOnObserveCalled = true }) events.Observe("/test", nil) // OnObserveCancelled evtOnObserveCancelledCalled := false events.OnObserveCancel(func(string, Message) { evtOnObserveCancelledCalled = true }) events.ObserveCancelled("/test", nil) // OnMessage evtOnMessageCalled := false events.OnMessage(func(Message, bool) { evtOnMessageCalled = true }) events.Message(nil, true) time.Sleep(3000) assert.True(t, evtOnNotifyCalled) assert.True(t, evtOnStartedCalled) assert.True(t, evtOnClosedCalled) assert.True(t, evtOnDiscoverCalled) assert.True(t, evtOnErrorCalled) assert.True(t, evtOnObserveCalled) assert.True(t, evtOnObserveCancelledCalled) assert.True(t, evtOnMessageCalled) } ================================================ FILE: examples/block1/client.go ================================================ package main import ( "io/ioutil" "log" "github.com/zubairhamed/canopus" ) func main() { conn, err := canopus.Dial("localhost:5683") file, err := ioutil.ReadFile("./ietf-block.htm") if err != nil { log.Fatal(err) } req := canopus.NewRequest(canopus.MessageConfirmable, canopus.Post) blockOpt := canopus.NewBlock1Option(canopus.BlockSize16, true, 0) req.GetMessage().SetBlock1Option(blockOpt) req.SetRequestURI("/blockupload") req.SetPayload(file) resp, err := conn.Send(req) if err != nil { log.Println(err) } else { log.Println("Got Response:") log.Println(resp.GetMessage().GetPayload().String()) } } ================================================ FILE: examples/block1/ietf-block.htm ================================================ draft-ietf-core-block-15 - Block-wise transfers in CoAP
[Docs] [txt|pdf] [Tracker] [WG] [Email] [Diff1] [Diff2] [Nits]

Versions: (draft-bormann-core-coap-block) 00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 

CoRE Working Group                                            C. Bormann
Internet-Draft                                   Universitaet Bremen TZI
Intended status: Standards Track                          Z. Shelby, Ed.
Expires: January 5, 2015                                             ARM
                                                           July 04, 2014


                      Blockwise transfers in CoAP
                        draft-ietf-core-block-15

Abstract

   CoAP is a RESTful transfer protocol for constrained nodes and
   networks.  Basic CoAP messages work well for the small payloads we
   expect from temperature sensors, light switches, and similar
   building-automation devices.  Occasionally, however, applications
   will need to transfer larger payloads -- for instance, for firmware
   updates.  With HTTP, TCP does the grunt work of slicing large
   payloads up into multiple packets and ensuring that they all arrive
   and are handled in the right order.

   CoAP is based on datagram transports such as UDP or DTLS, which
   limits the maximum size of resource representations that can be
   transferred without too much fragmentation.  Although UDP supports
   larger payloads through IP fragmentation, it is limited to 64 KiB
   and, more importantly, doesn't really work well for constrained
   applications and networks.

   Instead of relying on IP fragmentation, this specification extends
   basic CoAP with a pair of "Block" options, for transferring multiple
   blocks of information from a resource representation in multiple
   request-response pairs.  In many important cases, the Block options
   enable a server to be truly stateless: the server can handle each
   block transfer separately, with no need for a connection setup or
   other server-side memory of previous block transfers.

   In summary, the Block options provide a minimal way to transfer
   larger representations in a block-wise fashion.

Status of This Memo

   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 http://datatracker.ietf.org/drafts/current/.



Bormann & Shelby         Expires January 5, 2015                [Page 1]

Internet-Draft         Blockwise transfers in CoAP             July 2014


   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 January 5, 2015.

Copyright Notice

   Copyright (c) 2014 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
   (http://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 Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
   2.  Block-wise transfers  . . . . . . . . . . . . . . . . . . . .   5
     2.1.  The Block2 and Block1 Options . . . . . . . . . . . . . .   5
     2.2.  Structure of a Block Option . . . . . . . . . . . . . . .   6
     2.3.  Block Options in Requests and Responses . . . . . . . . .   8
     2.4.  Using the Block2 Option . . . . . . . . . . . . . . . . .  10
     2.5.  Using the Block1 Option . . . . . . . . . . . . . . . . .  11
     2.6.  Combining Blockwise Transfers with the Observe Option . .  12
     2.7.  Combining Block1 and Block2 . . . . . . . . . . . . . . .  13
     2.8.  Combining Block2 with Multicast . . . . . . . . . . . . .  13
     2.9.  Response Codes  . . . . . . . . . . . . . . . . . . . . .  14
       2.9.1.  2.31 Continue . . . . . . . . . . . . . . . . . . . .  14
       2.9.2.  4.08 Request Entity Incomplete  . . . . . . . . . . .  14
       2.9.3.  4.13 Request Entity Too Large . . . . . . . . . . . .  14
   3.  Examples  . . . . . . . . . . . . . . . . . . . . . . . . . .  15
     3.1.  Block2 Examples . . . . . . . . . . . . . . . . . . . . .  15
     3.2.  Block1 Examples . . . . . . . . . . . . . . . . . . . . .  19
     3.3.  Combining Block1 and Block2 . . . . . . . . . . . . . . .  20
     3.4.  Combining Observe and Block2  . . . . . . . . . . . . . .  22
   4.  The Size2 and Size1 Options . . . . . . . . . . . . . . . . .  25
   5.  HTTP Mapping Considerations . . . . . . . . . . . . . . . . .  26
   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  27
   7.  Security Considerations . . . . . . . . . . . . . . . . . . .  28
     7.1.  Mitigating Resource Exhaustion Attacks  . . . . . . . . .  29



Bormann & Shelby         Expires January 5, 2015                [Page 2]

Internet-Draft         Blockwise transfers in CoAP             July 2014


     7.2.  Mitigating Amplification Attacks  . . . . . . . . . . . .  29
   8.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .  30
   9.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  30
     9.1.  Normative References  . . . . . . . . . . . . . . . . . .  30
     9.2.  Informative References  . . . . . . . . . . . . . . . . .  30
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  31

1.  Introduction

   The work on Constrained RESTful Environments (CoRE) aims at realizing
   the REST architecture in a suitable form for the most constrained
   nodes (such as microcontrollers with limited RAM and ROM [RFC7228])
   and networks (such as 6LoWPAN, [RFC4944]) [RFC7252].  The CoAP
   protocol is intended to provide RESTful [REST] services not unlike
   HTTP [RFC7230], while reducing the complexity of implementation as
   well as the size of packets exchanged in order to make these services
   useful in a highly constrained network of themselves highly
   constrained nodes.

   This objective requires restraint in a number of sometimes
   conflicting ways:

   o  reducing implementation complexity in order to minimize code size,

   o  reducing message sizes in order to minimize the number of
      fragments needed for each message (in turn to maximize the
      probability of delivery of the message), the amount of
      transmission power needed and the loading of the limited-bandwidth
      channel,

   o  reducing requirements on the environment such as stable storage,
      good sources of randomness or user interaction capabilities.

   CoAP is based on datagram transports such as UDP, which limit the
   maximum size of resource representations that can be transferred
   without creating unreasonable levels of IP fragmentation.  In
   addition, not all resource representations will fit into a single
   link layer packet of a constrained network, which may cause
   adaptation layer fragmentation even if IP layer fragmentation is not
   required.  Using fragmentation (either at the adaptation layer or at
   the IP layer) for the transport of larger representations would be
   possible up to the maximum size of the underlying datagram protocol
   (such as UDP), but the fragmentation/reassembly process burdens the
   lower layers with conversation state that is better managed in the
   application layer.

   The present specification defines a pair of CoAP options to enable
   _block-wise_ access to resource representations.  The Block options



Bormann & Shelby         Expires January 5, 2015                [Page 3]

Internet-Draft         Blockwise transfers in CoAP             July 2014


   provide a minimal way to transfer larger resource representations in
   a block-wise fashion.  The overriding objective is to avoid the need
   for creating conversation state at the server for block-wise GET
   requests.  (It is impossible to fully avoid creating conversation
   state for POST/PUT, if the creation/replacement of resources is to be
   atomic; where that property is not needed, there is no need to create
   server conversation state in this case, either.)

   In summary, this specification adds a pair of Block options to CoAP
   that can be used for block-wise transfers.  Benefits of using these
   options include:

   o  Transfers larger than what can be accommodated in constrained-
      network link-layer packets can be performed in smaller blocks.

   o  No hard-to-manage conversation state is created at the adaptation
      layer or IP layer for fragmentation.

   o  The transfer of each block is acknowledged, enabling individual
      retransmission if required.

   o  Both sides have a say in the block size that actually will be
      used.

   o  The resulting exchanges are easy to understand using packet
      analyzer tools and thus quite accessible to debugging.

   o  If needed, the Block options can also be used (without changes) to
      provide random access to power-of-two sized blocks within a
      resource representation.

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in RFC
   2119, BCP 14 [RFC2119] and indicate requirement levels for compliant
   CoAP implementations.

   In this document, the term "byte" is used in its now customary sense
   as a synonym for "octet".

   Where bit arithmetic is explained, this document uses the notation
   familiar from the programming language C, except that the operator
   "**" stands for exponentiation.








Bormann & Shelby         Expires January 5, 2015                [Page 4]

Internet-Draft         Blockwise transfers in CoAP             July 2014


2.  Block-wise transfers

   As discussed in the introduction, there are good reasons to limit the
   size of datagrams in constrained networks:

   o  by the maximum datagram size (~ 64 KiB for UDP)

   o  by the desire to avoid IP fragmentation (MTU of 1280 for IPv6)

   o  by the desire to avoid adaptation layer fragmentation (60-80 bytes
      for 6LoWPAN [RFC4919])

   When a resource representation is larger than can be comfortably
   transferred in the payload of a single CoAP datagram, a Block option
   can be used to indicate a block-wise transfer.  As payloads can be
   sent both with requests and with responses, this specification
   provides two separate options for each direction of payload transfer.
   In identifying these options, we use the number 1 to refer to the
   transfer of the resource representation that pertains to the request,
   and the number 2 to refer to the transfer of the resource
   representation for the response.

   In the following, the term "payload" will be used for the actual
   content of a single CoAP message, i.e. a single block being
   transferred, while the term "body" will be used for the entire
   resource representation that is being transferred in a block-wise
   fashion.  The Content-Format option applies to the body, not to the
   payload, in particular the boundaries between the blocks may be in
   places that are not separating whole units in terms of the structure,
   encoding, or content-coding used by the Content-Format.

   In most cases, all blocks being transferred for a body (except for
   the last one) will be of the same size.  The block size is not fixed
   by the protocol.  To keep the implementation as simple as possible,
   the Block options support only a small range of power-of-two block
   sizes, from 2**4 (16) to 2**10 (1024) bytes.  As bodies often will
   not evenly divide into the power-of-two block size chosen, the size
   need not be reached in the final block (but even for the final block,
   the chosen power-of-two size will still be indicated in the block
   size field of the Block option).

2.1.  The Block2 and Block1 Options









Bormann & Shelby         Expires January 5, 2015                [Page 5]

Internet-Draft         Blockwise transfers in CoAP             July 2014


       +-----+---+---+---+---+--------+--------+--------+---------+
       | No. | C | U | N | R | Name   | Format | Length | Default |
       +-----+---+---+---+---+--------+--------+--------+---------+
       |  23 | C | U | - | - | Block2 | uint   |    0-3 | (none)  |
       |     |   |   |   |   |        |        |        |         |
       |  27 | C | U | - | - | Block1 | uint   |    0-3 | (none)  |
       +-----+---+---+---+---+--------+--------+--------+---------+

                       Table 1: Block Option Numbers

   Both Block1 and Block2 options can be present both in request and
   response messages.  In either case, the Block1 Option pertains to the
   request payload, and the Block2 Option pertains to the response
   payload.

   Hence, for the methods defined in [RFC7252], Block1 is useful with
   the payload-bearing POST and PUT requests and their responses.
   Block2 is useful with GET, POST, and PUT requests and their payload-
   bearing responses (2.01, 2.02, 2.04, 2.05 -- see section "Payload" of
   [RFC7252]).

   Where Block1 is present in a request or Block2 in a response (i.e.,
   in that message to the payload of which it pertains) it indicates a
   block-wise transfer and describes how this specific block-wise
   payload forms part of the entire body being transferred ("descriptive
   usage").  Where it is present in the opposite direction, it provides
   additional control on how that payload will be formed or was
   processed ("control usage").

   Implementation of either Block option is intended to be optional.
   However, when it is present in a CoAP message, it MUST be processed
   (or the message rejected); therefore it is identified as a critical
   option.  It MUST NOT occur more than once.

2.2.  Structure of a Block Option

   Three items of information may need to be transferred in a Block
   (Block1 or Block2) option:

   o  The size of the block (SZX);

   o  whether more blocks are following (M);

   o  the relative number of the block (NUM) within a sequence of blocks
      with the given size.

   The value of the Block Option is a variable-size (0 to 3 byte)
   unsigned integer (uint, see Section 3.2 of [RFC7252]).  This integer



Bormann & Shelby         Expires January 5, 2015                [Page 6]

Internet-Draft         Blockwise transfers in CoAP             July 2014


   value encodes these three fields, see Figure 1.  (Due to the CoAP
   uint encoding rules, when all of NUM, M, and SZX happen to be zero, a
   zero-byte integer will be sent.)

           0
           0 1 2 3 4 5 6 7
          +-+-+-+-+-+-+-+-+
          |  NUM  |M| SZX |
          +-+-+-+-+-+-+-+-+

           0                   1
           0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
          +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
          |          NUM          |M| SZX |
          +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

           0                   1                   2
           0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3
          +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
          |                   NUM                 |M| SZX |
          +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                       Figure 1: Block option value

   The block size is encoded using a three-bit unsigned integer (0 for
   2**4 to 6 for 2**10 bytes), which we call the "SZX" ("size
   exponent"); the actual block size is then "2**(SZX + 4)".  SZX is
   transferred in the three least significant bits of the option value
   (i.e., "val & 7" where "val" is the value of the option).

   The fourth least significant bit, the M or "more" bit ("val & 8"),
   indicates whether more blocks are following or the current block-wise
   transfer is the last block being transferred.

   The option value divided by sixteen (the NUM field) is the sequence
   number of the block currently being transferred, starting from zero.
   The current transfer is therefore about the "size" bytes starting at
   byte "NUM << (SZX + 4)".

   Implementation note:  As an implementation convenience, "(val & ~0xF)
      << (val & 7)", i.e., the option value with the last 4 bits masked
      out, shifted to the left by the value of SZX, gives the byte
      position of the first byte of the block being transferred.

   More specifically, within the option value of a Block1 or Block2
   Option, the meaning of the option fields is defined as follows:





Bormann & Shelby         Expires January 5, 2015                [Page 7]

Internet-Draft         Blockwise transfers in CoAP             July 2014


   NUM:  Block Number, indicating the block number being requested or
      provided.  Block number 0 indicates the first block of a body
      (i.e., starting with the first byte of the body).

   M: More Flag ("not last block").  For descriptive usage, this flag,
      if unset, indicates that the payload in this message is the last
      block in the body; when set it indicates that there are one or
      more additional blocks available.  When a Block2 Option is used in
      a request to retrieve a specific block number ("control usage"),
      the M bit MUST be sent as zero and ignored on reception.  (In a
      Block1 Option in a response, the M flag is used to indicate
      atomicity, see below.)

   SZX:  Block Size.  The block size is represented as three-bit
      unsigned integer indicating the size of a block to the power of
      two.  Thus block size = 2**(SZX + 4).  The allowed values of SZX
      are 0 to 6, i.e., the minimum block size is 2**(0+4) = 16 and the
      maximum is 2**(6+4) = 1024.  The value 7 for SZX (which would
      indicate a block size of 2048) is reserved, i.e.  MUST NOT be sent
      and MUST lead to a 4.00 Bad Request response code upon reception
      in a request.

   There is no default value for the Block1 and Block2 Options.  Absence
   of one of these options is equivalent to an option value of 0 with
   respect to the value of NUM and M that could be given in the option,
   i.e. it indicates that the current block is the first and only block
   of the transfer (block number 0, M bit not set).  However, in
   contrast to the explicit value 0, which would indicate an SZX of 0
   and thus a size value of 16 bytes, there is no specific explicit size
   implied by the absence of the option -- the size is left unspecified.
   (As for any uint, the explicit value 0 is efficiently indicated by a
   zero-length option; this, therefore, is different in semantics from
   the absence of the option.)

2.3.  Block Options in Requests and Responses

   The Block options are used in one of three roles:

   o  In descriptive usage, i.e., a Block2 Option in a response (such as
      a 2.05 response for GET), or a Block1 Option in a request (a PUT
      or POST):

      *  The NUM field in the option value describes what block number
         is contained in the payload of this message.

      *  The M bit indicates whether further blocks need to be
         transferred to complete the transfer of that body.




Bormann & Shelby         Expires January 5, 2015                [Page 8]

Internet-Draft         Blockwise transfers in CoAP             July 2014


      *  The block size implied by SZX MUST match the size of the
         payload in bytes, if the M bit is set.  (SZX does not govern
         the payload size if M is unset).  For Block2, if the request
         suggested a larger value of SZX, the next request MUST move SZX
         down to the size given in the response.  (The effect is that,
         if the server uses the smaller of (1) its preferred block size
         and (2) the block size requested, all blocks for a body use the
         same block size.)

   o  A Block2 Option in control usage in a request (e.g., GET):

      *  The NUM field in the Block2 Option gives the block number of
         the payload that is being requested to be returned in the
         response.

      *  In this case, the M bit has no function and MUST be set to
         zero.

      *  The block size given (SZX) suggests a block size (in the case
         of block number 0) or repeats the block size of previous blocks
         received (in the case of a non-zero block number).

   o  A Block1 Option in control usage in a response (e.g., a 2.xx
      response for a PUT or POST request):

      *  The NUM field of the Block1 Option indicates what block number
         is being acknowledged.

      *  If the M bit was set in the request, the server can choose
         whether to act on each block separately, with no memory, or
         whether to handle the request for the entire body atomically,
         or any mix of the two.

         +  If the M bit is also set in the response, it indicates that
            this response does not carry the final response code to the
            request, i.e. the server collects further blocks from the
            same endpoint and plans to implement the request atomically
            (e.g., acts only upon reception of the last block of
            payload).  In this case, the response MUST NOT carry a
            Block2 option.

         +  Conversely, if the M bit is unset even though it was set in
            the request, it indicates the block-wise request was enacted
            now specifically for this block, and the response carries
            the final response to this request (and to any previous ones
            with the M bit set in the response's Block1 Option in this
            sequence of block-wise transfers); the client is still




Bormann & Shelby         Expires January 5, 2015                [Page 9]

Internet-Draft         Blockwise transfers in CoAP             July 2014


            expected to continue sending further blocks, the request
            method for which may or may not also be enacted per-block.

      *  Finally, the SZX block size given in a control Block1 Option
         indicates the largest block size preferred by the server for
         transfers toward the resource that is the same or smaller than
         the one used in the initial exchange; the client SHOULD use
         this block size or a smaller one in all further requests in the
         transfer sequence, even if that means changing the block size
         (and possibly scaling the block number accordingly) from now
         on.

   Using one or both Block options, a single REST operation can be split
   into multiple CoAP message exchanges.  As specified in [RFC7252],
   each of these message exchanges uses their own CoAP Message ID.

2.4.  Using the Block2 Option

   When a request is answered with a response carrying a Block2 Option
   with the M bit set, the requester may retrieve additional blocks of
   the resource representation by sending further requests with the same
   options as the initial request and a Block2 Option giving the block
   number and block size desired.  In a request, the client MUST set the
   M bit of a Block2 Option to zero and the server MUST ignore it on
   reception.

   To influence the block size used in a response, the requester MAY
   also use the Block2 Option on the initial request, giving the desired
   size, a block number of zero and an M bit of zero.  A server MUST use
   the block size indicated or a smaller size.  Any further block-wise
   requests for blocks beyond the first one MUST indicate the same block
   size that was used by the server in the response for the first
   request that gave a desired size using a Block2 Option.

   Once the Block2 Option is used by the requester and a first response
   has been received with a possibly adjusted block size, all further
   requests in a single block-wise transfer SHOULD ultimately use the
   same size, except that there may not be enough content to fill the
   last block (the one returned with the M bit not set).  (Note that the
   client may start using the Block2 Option in a second request after a
   first request without a Block2 Option resulted in a Block2 option in
   the response.)  The server SHOULD use the block size indicated in the
   request option or a smaller size, but the requester MUST take note of
   the actual block size used in the response it receives to its initial
   request and proceed to use it in subsequent requests.  The server
   behavior MUST ensure that this client behavior results in the same
   block size for all responses in a sequence (except for the last one




Bormann & Shelby         Expires January 5, 2015               [Page 10]

Internet-Draft         Blockwise transfers in CoAP             July 2014


   with the M bit not set, and possibly the first one if the initial
   request did not contain a Block2 Option).

   Block-wise transfers can be used to GET resources the representations
   of which are entirely static (not changing over time at all, such as
   in a schema describing a device), or for dynamically changing
   resources.  In the latter case, the Block2 Option SHOULD be used in
   conjunction with the ETag Option, to ensure that the blocks being
   reassembled are from the same version of the representation: The
   server SHOULD include an ETag option in each response.  If an ETag
   option is available, the client's reassembler, when reassembling the
   representation from the blocks being exchanged, MUST compare ETag
   Options.  If the ETag Options do not match in a GET transfer, the
   requester has the option of attempting to retrieve fresh values for
   the blocks it retrieved first.  To minimize the resulting
   inefficiency, the server MAY cache the current value of a
   representation for an ongoing sequence of requests.  (The server may
   identify the sequence by the combination of the requesting end-point
   and the URI being the same in each block-wise request.)  Note well
   that this specification makes no requirement for the server to
   establish any state; however, servers that offer quickly changing
   resources may thereby make it impossible for a client to ever
   retrieve a consistent set of blocks.

2.5.  Using the Block1 Option

   In a request with a request payload (e.g., PUT or POST), the Block1
   Option refers to the payload in the request (descriptive usage).

   In response to a request with a payload (e.g., a PUT or POST
   transfer), the block size given in the Block1 Option indicates the
   block size preference of the server for this resource (control
   usage).  Obviously, at this point the first block has already been
   transferred by the client without benefit of this knowledge.  Still,
   the client SHOULD heed the preference indicated and, for all further
   blocks, use the block size preferred by the server or a smaller one.
   Note that any reduction in the block size may mean that the second
   request starts with a block number larger than one, as the first
   request already transferred multiple blocks as counted in the smaller
   size.

   To counter the effects of adaptation layer fragmentation on packet
   delivery probability, a client may want to give up retransmitting a
   request with a relatively large payload even before MAX_RETRANSMIT
   has been reached, and try restating the request as a block-wise
   transfer with a smaller payload.  Note that this new attempt is then
   a new message-layer transaction and requires a new Message ID.
   (Because of the uncertainty whether the request or the



Bormann & Shelby         Expires January 5, 2015               [Page 11]

Internet-Draft         Blockwise transfers in CoAP             July 2014


   acknowledgement was lost, this strategy is useful mostly for
   idempotent requests.)

   In a blockwise transfer of a request payload (e.g., a PUT or POST)
   that is intended to be implemented in an atomic fashion at the
   server, the actual creation/replacement takes place at the time the
   final block, i.e. a block with the M bit unset in the Block1 Option,
   is received.  In this case, all success responses to non-final blocks
   carry the response code 2.31 (Continue, Section 2.9.1).  If not all
   previous blocks are available at the server at the time of processing
   the final block, the transfer fails and error code 4.08 (Request
   Entity Incomplete, Section 2.9.2) MUST be returned.  A server MAY
   also return a 4.08 error code for any (final or non-final) Block1
   transfer that is not in sequence; clients that do not have specific
   mechanisms to handle this case therefore SHOULD always start with
   block zero and send the following blocks in order.

   The error code 4.13 (Request Entity Too Large) can be returned at any
   time by a server that does not currently have the resources to store
   blocks for a block-wise request payload transfer that it would intend
   to implement in an atomic fashion.  (Note that a 4.13 response to a
   request that does not employ Block1 is a hint for the client to try
   sending Block1, and a 4.13 response with a smaller SZX in its Block1
   option than requested is a hint to try a smaller SZX.)

   The Block1 option provides no way for a single endpoint to perform
   multiple concurrently proceeding block-wise request payload transfer
   (e.g., PUT or POST) operations to the same resource.  Starting a new
   block-wise sequence of requests to the same resource (before an old
   sequence from the same endpoint was finished) simply overwrites the
   context the server may still be keeping.  (This is probably exactly
   what one wants in this case - the client may simply have restarted
   and lost its knowledge of the previous sequence.)

2.6.  Combining Blockwise Transfers with the Observe Option

   The Observe Option provides a way for a client to be notified about
   changes over time of a resource [I-D.ietf-core-observe].  Resources
   observed by clients may be larger than can be comfortably processed
   or transferred in one CoAP message.  The following rules apply to the
   combination of blockwise transfers with notifications.

   Observation relationships always apply to an entire resource; the
   Block2 option does not provide a way to observe a single block of a
   resource.

   As with basic GET transfers, the client can indicate its desired
   block size in a Block2 Option in the GET request establishing or



Bormann & Shelby         Expires January 5, 2015               [Page 12]

Internet-Draft         Blockwise transfers in CoAP             July 2014


   renewing the observation relationship.  If the server supports
   blockwise transfers, it SHOULD take note of the block size and apply
   it as a maximum size to all notifications/responses resulting from
   the GET request (until the client is removed from the list of
   observers or the entry in that list is updated by the server
   receiving a new GET request for the resource from the client).

   When sending a 2.05 (Content) notification, the server only sends the
   first block of the representation.  The client retrieves the rest of
   the representation as if it had caused this first response by a GET
   request, i.e., by using additional GET requests with Block2 options
   containing NUM values greater than zero.  (This results in the
   transfer of the entire representation, even if only some of the
   blocks have changed with respect to a previous notification.)

   As with other dynamically changing resources, to ensure that the
   blocks being reassembled are from the same version of the
   representation, the server SHOULD include an ETag option in each
   response, and the reassembling client MUST compare the ETag options
   (Section 2.4).

   See Section 3.4 for examples.

2.7.  Combining Block1 and Block2

   In PUT and particularly in POST exchanges, both the request body and
   the response body may be large enough to require the use of block-
   wise transfers.  First, the Block1 transfer of the request body
   proceeds as usual.  In the exchange of the last slice of this block-
   wise transfer, the response carries the first slice of the Block2
   transfer (NUM is zero).  To continue this Block2 transfer, the client
   continues to send requests similar to the requests in the Block1
   phase, but leaves out the Block1 options and includes a Block2
   request option with non-zero NUM.

   Block2 transfers that retrieve the response body for a request that
   used Block1 MUST be performed in sequential order.

2.8.  Combining Block2 with Multicast

   A client can use the Block2 option in a multicast GET request with
   NUM = 0 to aid in limiting the size of the response.

   Similarly, a response to a multicast GET request can use a Block2
   option with NUM = 0 if the representation is large, or to further
   limit the size of the response.





Bormann & Shelby         Expires January 5, 2015               [Page 13]

Internet-Draft         Blockwise transfers in CoAP             July 2014


   In both cases, the client retrieves any further blocks using unicast
   exchanges; in the unicast requests, the client SHOULD heed any block
   size preferences indicated by the server in the response to the
   multicast request.

   Other uses of the Block options in conjunction with multicast
   messages are for further study.

2.9.  Response Codes

   Two response codes are defined by this specification beyond those
   already defined in [RFC7252], and another response code is extended
   in its meaning.

2.9.1.  2.31 Continue

   This new success status code indicates that the transfer of this
   block of the request body was successful and that the server
   encourages sending further blocks, but that a final outcome of the
   whole block-wise request cannot yet be determined.  No payload is
   returned with this response code.

2.9.2.  4.08 Request Entity Incomplete

   This new client error status code indicates that the server has not
   received the blocks of the request body that it needs to proceed.
   The client has not sent all blocks, not sent them in the order
   required by the server, or has sent them long enough ago that the
   server has already discarded them.

2.9.3.  4.13 Request Entity Too Large

   In [RFC7252], section 5.9.2.9, the response code 4.13 (Request Entity
   Too Large) is defined to be like HTTP 413 "Request Entity Too Large".
   [RFC7252] also recommends that this response SHOULD include a Size1
   Option (Section 4) to indicate the maximum size of request entity the
   server is able and willing to handle, unless the server is not in a
   position to make this information available.

   The present specification allows the server to return this response
   code at any time during a Block1 transfer to indicate that it does
   not currently have the resources to store blocks for a transfer that
   it would intend to implement in an atomic fashion.  It also allows
   the server to return a 4.13 response to a request that does not
   employ Block1 as a hint for the client to try sending Block1.
   Finally, a 4.13 response to a request with a Block1 option (control
   usage, see Section 2.3) where the response carries a smaller SZX in
   its Block1 option is a hint to try that smaller SZX.



Bormann & Shelby         Expires January 5, 2015               [Page 14]

Internet-Draft         Blockwise transfers in CoAP             July 2014


3.  Examples

   This section gives a number of short examples with message flows for
   a block-wise GET, and for a PUT or POST.  These examples demonstrate
   the basic operation, the operation in the presence of
   retransmissions, and examples for the operation of the block size
   negotiation.

   In all these examples, a Block option is shown in a decomposed way
   indicating the kind of Block option (1 or 2) followed by a colon, and
   then the block number (NUM), more bit (M), and block size exponent
   (2**(SZX+4)) separated by slashes.  E.g., a Block2 Option value of 33
   would be shown as 2:2/0/32), or a Block1 Option value of 59 would be
   shown as 1:3/1/128.

3.1.  Block2 Examples

   The first example (Figure 2) shows a GET request that is split into
   three blocks.  The server proposes a block size of 128, and the
   client agrees.  The first two ACKs contain 128 bytes of payload each,
   and third ACK contains between 1 and 128 bytes.

   CLIENT                                                     SERVER
     |                                                            |
     | CON [MID=1234], GET, /status                       ------> |
     |                                                            |
     | <------   ACK [MID=1234], 2.05 Content, 2:0/1/128          |
     |                                                            |
     | CON [MID=1235], GET, /status, 2:1/0/128            ------> |
     |                                                            |
     | <------   ACK [MID=1235], 2.05 Content, 2:1/1/128          |
     |                                                            |
     | CON [MID=1236], GET, /status, 2:2/0/128            ------> |
     |                                                            |
     | <------   ACK [MID=1236], 2.05 Content, 2:2/0/128          |

                      Figure 2: Simple blockwise GET

   In the second example (Figure 3), the client anticipates the
   blockwise transfer (e.g., because of a size indication in the link-
   format description [RFC6690]) and sends a block size proposal.  All
   ACK messages except for the last carry 64 bytes of payload; the last
   one carries between 1 and 64 bytes.








Bormann & Shelby         Expires January 5, 2015               [Page 15]

Internet-Draft         Blockwise transfers in CoAP             July 2014


   CLIENT                                                     SERVER
     |                                                          |
     | CON [MID=1234], GET, /status, 2:0/0/64           ------> |
     |                                                          |
     | <------   ACK [MID=1234], 2.05 Content, 2:0/1/64         |
     |                                                          |
     | CON [MID=1235], GET, /status, 2:1/0/64           ------> |
     |                                                          |
     | <------   ACK [MID=1235], 2.05 Content, 2:1/1/64         |
     :                                                          :
     :                          ...                             :
     :                                                          :
     | CON [MID=1238], GET, /status, 2:4/0/64           ------> |
     |                                                          |
     | <------   ACK [MID=1238], 2.05 Content, 2:4/1/64         |
     |                                                          |
     | CON [MID=1239], GET, /status, 2:5/0/64           ------> |
     |                                                          |
     | <------   ACK [MID=1239], 2.05 Content, 2:5/0/64         |

              Figure 3: Blockwise GET with early negotiation

   In the third example (Figure 4), the client is surprised by the need
   for a blockwise transfer, and unhappy with the size chosen
   unilaterally by the server.  As it did not send a size proposal
   initially, the negotiation only influences the size from the second
   message exchange onward.  Since the client already obtained both the
   first and second 64-byte block in the first 128-byte exchange, it
   goes on requesting the third 64-byte block ("2/0/64").  None of this
   is (or needs to be) understood by the server, which simply responds
   to the requests as it best can.




















Bormann & Shelby         Expires January 5, 2015               [Page 16]

Internet-Draft         Blockwise transfers in CoAP             July 2014


   CLIENT                                                     SERVER
     |                                                          |
     | CON [MID=1234], GET, /status                     ------> |
     |                                                          |
     | <------   ACK [MID=1234], 2.05 Content, 2:0/1/128        |
     |                                                          |
     | CON [MID=1235], GET, /status, 2:2/0/64           ------> |
     |                                                          |
     | <------   ACK [MID=1235], 2.05 Content, 2:2/1/64         |
     |                                                          |
     | CON [MID=1236], GET, /status, 2:3/0/64           ------> |
     |                                                          |
     | <------   ACK [MID=1236], 2.05 Content, 2:3/1/64         |
     |                                                          |
     | CON [MID=1237], GET, /status, 2:4/0/64           ------> |
     |                                                          |
     | <------   ACK [MID=1237], 2.05 Content, 2:4/1/64         |
     |                                                          |
     | CON [MID=1238], GET, /status, 2:5/0/64           ------> |
     |                                                          |
     | <------   ACK [MID=1238], 2.05 Content, 2:5/0/64         |

               Figure 4: Blockwise GET with late negotiation

   In all these (and the following) cases, retransmissions are handled
   by the CoAP message exchange layer, so they don't influence the block
   operations (Figure 5, Figure 6).
























Bormann & Shelby         Expires January 5, 2015               [Page 17]

Internet-Draft         Blockwise transfers in CoAP             July 2014


   CLIENT                                                     SERVER
     |                                                          |
     | CON [MID=1234], GET, /status                     ------> |
     |                                                          |
     | <------   ACK [MID=1234], 2.05 Content, 2:0/1/128        |
     |                                                          |
     | CON [MID=1235], GE/////////////////////////              |
     |                                                          |
     | (timeout)                                                |
     |                                                          |
     | CON [MID=1235], GET, /status, 2:2/0/64           ------> |
     |                                                          |
     | <------   ACK [MID=1235], 2.05 Content, 2:2/1/64         |
     :                                                          :
     :                          ...                             :
     :                                                          :
     | CON [MID=1238], GET, /status, 2:5/0/64           ------> |
     |                                                          |
     | <------   ACK [MID=1238], 2.05 Content, 2:5/0/64         |

        Figure 5: Blockwise GET with late negotiation and lost CON

   CLIENT                                                     SERVER
     |                                                          |
     | CON [MID=1234], GET, /status                     ------> |
     |                                                          |
     | <------   ACK [MID=1234], 2.05 Content, 2:0/1/128        |
     |                                                          |
     | CON [MID=1235], GET, /status, 2:2/0/64           ------> |
     |                                                          |
     | //////////////////////////////////tent, 2:2/1/64         |
     |                                                          |
     | (timeout)                                                |
     |                                                          |
     | CON [MID=1235], GET, /status, 2:2/0/64           ------> |
     |                                                          |
     | <------   ACK [MID=1235], 2.05 Content, 2:2/1/64         |
     :                                                          :
     :                          ...                             :
     :                                                          :
     | CON [MID=1238], GET, /status, 2:5/0/64           ------> |
     |                                                          |
     | <------   ACK [MID=1238], 2.05 Content, 2:5/0/64         |

        Figure 6: Blockwise GET with late negotiation and lost ACK






Bormann & Shelby         Expires January 5, 2015               [Page 18]

Internet-Draft         Blockwise transfers in CoAP             July 2014


3.2.  Block1 Examples

   The following examples demonstrate a PUT exchange; a POST exchange
   looks the same, with different requirements on atomicity/idempotence.
   Note that, similar to GET, the responses to the requests that have a
   more bit in the request Block1 Option are provisional and carry the
   response code 2.31 (Continue); only the final response tells the
   client that the PUT did succeed.

   CLIENT                                                     SERVER
     |                                                          |
     | CON [MID=1234], PUT, /options, 1:0/1/128    ------>      |
     |                                                          |
     | <------   ACK [MID=1234], 2.31 Continue, 1:0/1/128       |
     |                                                          |
     | CON [MID=1235], PUT, /options, 1:1/1/128    ------>      |
     |                                                          |
     | <------   ACK [MID=1235], 2.31 Continue, 1:1/1/128       |
     |                                                          |
     | CON [MID=1236], PUT, /options, 1:2/0/128    ------>      |
     |                                                          |
     | <------   ACK [MID=1236], 2.04 Changed, 1:2/0/128        |

                   Figure 7: Simple atomic blockwise PUT

   A stateless server that simply builds/updates the resource in place
   (statelessly) may indicate this by not setting the more bit in the
   response (Figure 8); in this case, the response codes are valid
   separately for each block being updated.  This is of course only an
   acceptable behavior of the server if the potential inconsistency
   present during the run of the message exchange sequence does not lead
   to problems, e.g. because the resource being created or changed is
   not yet or not currently in use.


















Bormann & Shelby         Expires January 5, 2015               [Page 19]

Internet-Draft         Blockwise transfers in CoAP             July 2014


   CLIENT                                                     SERVER
     |                                                          |
     | CON [MID=1234], PUT, /options, 1:0/1/128    ------>      |
     |                                                          |
     | <------   ACK [MID=1234], 2.04 Changed, 1:0/0/128        |
     |                                                          |
     | CON [MID=1235], PUT, /options, 1:1/1/128    ------>      |
     |                                                          |
     | <------   ACK [MID=1235], 2.04 Changed, 1:1/0/128        |
     |                                                          |
     | CON [MID=1236], PUT, /options, 1:2/0/128    ------>      |
     |                                                          |
     | <------   ACK [MID=1236], 2.04 Changed, 1:2/0/128        |

                 Figure 8: Simple stateless blockwise PUT

   Finally, a server receiving a blockwise PUT or POST may want to
   indicate a smaller block size preference (Figure 9).  In this case,
   the client SHOULD continue with a smaller block size; if it does, it
   MUST adjust the block number to properly count in that smaller size.

   CLIENT                                                     SERVER
     |                                                          |
     | CON [MID=1234], PUT, /options, 1:0/1/128    ------>      |
     |                                                          |
     | <------   ACK [MID=1234], 2.04 Changed, 1:0/1/32         |
     |                                                          |
     | CON [MID=1235], PUT, /options, 1:4/1/32     ------>      |
     |                                                          |
     | <------   ACK [MID=1235], 2.04 Changed, 1:4/1/32         |
     |                                                          |
     | CON [MID=1236], PUT, /options, 1:5/1/32     ------>      |
     |                                                          |
     | <------   ACK [MID=1235], 2.04 Changed, 1:5/1/32         |
     |                                                          |
     | CON [MID=1237], PUT, /options, 1:6/0/32     ------>      |
     |                                                          |
     | <------   ACK [MID=1236], 2.04 Changed, 1:6/0/32         |

          Figure 9: Simple atomic blockwise PUT with negotiation

3.3.  Combining Block1 and Block2

   Block options may be used in both directions of a single exchange.
   The following example demonstrates a blockwise POST request,
   resulting in a separate blockwise response.





Bormann & Shelby         Expires January 5, 2015               [Page 20]

Internet-Draft         Blockwise transfers in CoAP             July 2014


   CLIENT                                                     SERVER
     |                                                              |
     | CON [MID=1234], POST, /soap, 1:0/1/128      ------>          |
     |                                                              |
     | <------   ACK [MID=1234], 2.31 Continue, 1:0/1/128           |
     |                                                              |
     | CON [MID=1235], POST, /soap, 1:1/1/128      ------>          |
     |                                                              |
     | <------   ACK [MID=1235], 2.31 Continue, 1:1/1/128           |
     |                                                              |
     | CON [MID=1236], POST, /soap, 1:2/0/128      ------>          |
     |                                                              |
     | <------   ACK [MID=1236], 2.04 Changed, 2:0/1/128, 1:2/0/128 |
     |                                                              |
     | CON [MID=1237], POST, /soap, 2:1/0/128      ------>          |
     | (no payload for requests with Block2 with NUM != 0)          |
     | (could also do late negotiation by requesting e.g. 2:2/0/64) |
     |                                                              |
     | <------   ACK [MID=1237], 2.04 Changed, 2:1/1/128            |
     |                                                              |
     | CON [MID=1238], POST, /soap, 2:2/0/128      ------>          |
     |                                                              |
     | <------   ACK [MID=1238], 2.04 Changed, 2:2/1/128            |
     |                                                              |
     | CON [MID=1239], POST, /soap, 2:3/0/128      ------>          |
     |                                                              |
     | <------   ACK [MID=1239], 2.04 Changed, 2:3/0/128            |

         Figure 10: Atomic blockwise POST with blockwise response

   This model does provide for early negotiation input to the Block2
   blockwise transfer, as shown below.



















Bormann & Shelby         Expires January 5, 2015               [Page 21]

Internet-Draft         Blockwise transfers in CoAP             July 2014


   CLIENT                                                     SERVER
     |                                                              |
     | CON [MID=1234], POST, /soap, 1:0/1/128 ------>               |
     |                                                              |
     | <------   ACK [MID=1234], 2.31 Continue, 1:0/1/128           |
     |                                                              |
     | CON [MID=1235], POST, /soap, 1:1/1/128 ------>               |
     |                                                              |
     | <------   ACK [MID=1235], 2.31 Continue, 1:1/1/128           |
     |                                                              |
     | CON [MID=1236], POST, /soap, 1:2/0/128, 2:0/0/64 ------>     |
     |                                                              |
     | <------   ACK [MID=1236], 2.04 Changed, 1:2/0/128, 2:0/1/64 |
     |                                                              |
     | CON [MID=1237], POST, /soap, 2:1/0/64      ------>           |
     | (no payload for requests with Block2 with NUM != 0)          |
     |                                                              |
     | <------   ACK [MID=1237], 2.04 Changed, 2:1/1/64             |
     |                                                              |
     | CON [MID=1238], POST, /soap, 2:2/0/64      ------>           |
     |                                                              |
     | <------   ACK [MID=1238], 2.04 Changed, 2:2/1/64             |
     |                                                              |
     | CON [MID=1239], POST, /soap, 2:3/0/64      ------>           |
     |                                                              |
     | <------   ACK [MID=1239], 2.04 Changed, 2:3/0/64             |

      Figure 11: Atomic blockwise POST with blockwise response, early
                                negotiation

3.4.  Combining Observe and Block2

   In the following example, the server first sends a direct response
   (Observe sequence number 62350) to the initial GET request (the
   resulting blockwise transfer is as in Figure 4 and has therefore been
   left out).  The second transfer is started by a 2.05 notification
   that contains just the first block (Observe sequence number 62354);
   the client then goes on to obtain the rest of the blocks.

       CLIENT  SERVER
         |      |
         +----->|     Header: GET 0x41011636
         | GET  |      Token: 0xfb
         |      |   Uri-Path: status-icon
         |      |    Observe: (empty)
         |      |
         |<-----+     Header: 2.05 0x61451636
         | 2.05 |      Token: 0xfb



Bormann & Shelby         Expires January 5, 2015               [Page 22]

Internet-Draft         Blockwise transfers in CoAP             July 2014


         |      |     Block2: 0/1/128
         |      |    Observe: 62350
         |      |       ETag: 6f00f38e
         |      |    Payload: [128 bytes]
         |      |
         |      |  (Usual GET transfer left out)
           ...
         |      |  (Notification of first block:)
         |      |
         |<-----+     Header: 2.05 0x4145af9c
         | 2.05 |      Token: 0xfb
         |      |     Block2: 0/1/128
         |      |    Observe: 62354
         |      |       ETag: 6f00f392
         |      |    Payload: [128 bytes]
         |      |
         +- - ->|     Header: 0x6000af9c
         |      |
         |      |  (Retrieval of remaining blocks)
         |      |
         +----->|     Header: GET 0x41011637
         | GET  |      Token: 0xfc
         |      |   Uri-Path: status-icon
         |      |     Block2: 1/0/128
         |      |
         |<-----+     Header: 2.05 0x61451637
         | 2.05 |      Token: 0xfc
         |      |     Block2: 1/1/128
         |      |       ETag: 6f00f392
         |      |    Payload: [128 bytes]
         |      |
         +----->|     Header: GET 0x41011638
         | GET  |      Token: 0xfc
         |      |   Uri-Path: status-icon
         |      |     Block2: 2/0/128
         |      |
         |<-----+     Header: 2.05 0x61451638
         | 2.05 |      Token: 0xfc
         |      |     Block2: 2/0/128
         |      |       ETag: 6f00f392
         |      |    Payload: [53 bytes]


            Figure 12: Observe sequence with blockwise response

   In the following example, the client also uses early negotiation to
   limit the block size to 64 bytes.




Bormann & Shelby         Expires January 5, 2015               [Page 23]

Internet-Draft         Blockwise transfers in CoAP             July 2014


       CLIENT  SERVER
         |      |
         +----->|     Header: GET 0x41011636
         | GET  |      Token: 0xfb
         |      |   Uri-Path: status-icon
         |      |    Observe: (empty)
         |      |     Block2: 0/0/64
         |      |
         |<-----+     Header: 2.05 0x61451636
         | 2.05 |      Token: 0xfb
         |      |     Block2: 0/1/64
         |      |    Observe: 62350
         |      |       ETag: 6f00f38e
         |      |    Max-Age: 60
         |      |    Payload: [64 bytes]
         |      |
         |      |  (Usual GET transfer left out)
           ...
         |      |  (Notification of first block:)
         |      |
         |<-----+     Header: 2.05 0x4145af9c
         | 2.05 |      Token: 0xfb
         |      |     Block2: 0/1/64
         |      |    Observe: 62354
         |      |       ETag: 6f00f392
         |      |    Payload: [64 bytes]
         |      |
         +- - ->|     Header: 0x6000af9c
         |      |
         |      |  (Retrieval of remaining blocks)
         |      |
         +----->|     Header: GET 0x41011637
         | GET  |      Token: 0xfc
         |      |   Uri-Path: status-icon
         |      |     Block2: 1/0/64
         |      |
         |<-----+     Header: 2.05 0x61451637
         | 2.05 |      Token: 0xfc
         |      |     Block2: 1/1/64
         |      |       ETag: 6f00f392
         |      |    Payload: [64 bytes]
           ....
         |      |
         +----->|     Header: GET 0x41011638
         | GET  |      Token: 0xfc
         |      |   Uri-Path: status-icon
         |      |     Block2: 4/0/64
         |      |



Bormann & Shelby         Expires January 5, 2015               [Page 24]

Internet-Draft         Blockwise transfers in CoAP             July 2014


         |<-----+     Header: 2.05 0x61451638
         | 2.05 |      Token: 0xfc
         |      |     Block2: 4/0/64
         |      |       ETag: 6f00f392
         |      |    Payload: [53 bytes]

            Figure 13: Observe sequence with early negotiation

4.  The Size2 and Size1 Options

   In many cases when transferring a large resource representation block
   by block, it is advantageous to know the total size early in the
   process.  Some indication may be available from the maximum size
   estimate attribute "sz" provided in a resource description [RFC6690].
   However, the size may vary dynamically, so a more up-to-date
   indication may be useful.

   This specification defines two CoAP Options, Size1 for indicating the
   size of the representation transferred in requests, and Size2 for
   indicating the size of the representation transferred in responses.
   (Size1 is already defined in [RFC7252] for the narrow case of
   indicating in 4.13 responses the maximum size of request payload that
   the server is able and willing to handle.)

   The Size2 Option may be used for two purposes:

   o  in a request, to ask the server to provide a size estimate along
      with the usual response ("size request").  For this usage, the
      value MUST be set to 0.

   o  in a response carrying a Block2 Option, to indicate the current
      estimate the server has of the total size of the resource
      representation, measured in bytes ("size indication").

   Similarly, the Size1 Option may be used for two purposes:

   o  in a request carrying a Block1 Option, to indicate the current
      estimate the client has of the total size of the resource
      representation, measured in bytes ("size indication").

   o  in a 4.13 response, to indicate the maximum size that would have
      been acceptable [RFC7252], measured in bytes.

   Apart from conveying/asking for size information, the Size options
   have no other effect on the processing of the request or response.
   If the client wants to minimize the size of the payload in the
   resulting response, it should add a Block2 option to the request with
   a small block size (e.g., setting SZX=0).



Bormann & Shelby         Expires January 5, 2015               [Page 25]

Internet-Draft         Blockwise transfers in CoAP             July 2014


   The Size Options are "elective", i.e., a client MUST be prepared for
   the server to ignore the size estimate request.  The Size Options
   MUST NOT occur more than once.

        +-----+---+---+---+---+-------+--------+--------+---------+
        | No. | C | U | N | R | Name  | Format | Length | Default |
        +-----+---+---+---+---+-------+--------+--------+---------+
        |  60 |   |   | x |   | Size1 | uint   |    0-4 | (none)  |
        |     |   |   |   |   |       |        |        |         |
        |  28 |   |   | x |   | Size2 | uint   |    0-4 | (none)  |
        +-----+---+---+---+---+-------+--------+--------+---------+

                       Table 2: Size Option Numbers

   Implementation Notes:

   o  As a quality of implementation consideration, blockwise transfers
      for which the total size considerably exceeds the size of one
      block are expected to include size indications, whenever those can
      be provided without undue effort (preferably with the first block
      exchanged).  If the size estimate does not change, the indication
      does not need to be repeated for every block.

   o  The end of a blockwise transfer is governed by the M bits in the
      Block Options, _not_ by exhausting the size estimates exchanged.

   o  As usual for an option of type uint, the value 0 is best expressed
      as an empty option (0 bytes).  There is no default value for
      either Size Option.

   o  The Size Options are neither critical nor unsafe, and are marked
      as No-Cache-Key.

5.  HTTP Mapping Considerations

   In this subsection, we give some brief examples for the influence the
   Block options might have on intermediaries that map between CoAP and
   HTTP.

   For mapping CoAP requests to HTTP, the intermediary may want to map
   the sequence of block-wise transfers into a single HTTP transfer.
   E.g., for a GET request, the intermediary could perform the HTTP
   request once the first block has been requested and could then
   fulfill all further block requests out of its cache.  A constrained
   implementation may not be able to cache the entire object and may use
   a combination of TCP flow control and (in particular if timeouts
   occur) HTTP range requests to obtain the information necessary for
   the next block transfer at the right time.



Bormann & Shelby         Expires January 5, 2015               [Page 26]

Internet-Draft         Blockwise transfers in CoAP             July 2014


   For PUT or POST requests, historically there was more variation in
   how HTTP servers might implement ranges; recently, [RFC7233] has
   defined that Range header fields received with a request method other
   than GET are not to be interpreted.  So, in general, the CoAP-to-HTTP
   intermediary will have to try sending the payload of all the blocks
   of a block-wise transfer for these other methods within one HTTP
   request.  If enough buffering is available, this request can be
   started when the last CoAP block is received.  A constrained
   implementation may want to relieve its buffering by already starting
   to send the HTTP request at the time the first CoAP block is
   received; any HTTP 408 status code that indicates that the HTTP
   server became impatient with the resulting transfer can then be
   mapped into a CoAP 4.08 response code (similarly, 413 maps to 4.13).

   For mapping HTTP to CoAP, the intermediary may want to map a single
   HTTP transfer into a sequence of block-wise transfers.  If the HTTP
   client is too slow delivering a request body on a PUT or POST, the
   CoAP server might time out and return a 4.08 response code, which in
   turn maps well to an HTTP 408 status code (again, 4.13 maps to 413).
   HTTP range requests received on the HTTP side may be served out of a
   cache and/or mapped to GET requests that request a sequence of blocks
   overlapping the range.

   (Note that, while the semantics of CoAP 4.08 and HTTP 408 differ,
   this difference is largely due to the different way the two protocols
   are mapped to transport.  HTTP has an underlying TCP connection,
   which supplies connection state, so a HTTP 408 status code can
   immediately be used to indicate that a timeout occurred during
   transmitting a request through that active TCP connection.  The CoAP
   4.08 response code indicates one or more missing blocks, which may be
   due to timeouts or resource constraints; as there is no connection
   state, there is no way to deliver such a response immediately;
   instead, it is delivered on the next block transfer.  Still, HTTP 408
   is probably the best mapping back to HTTP, as the timeout is the most
   likely cause for a CoAP 4.08.  Note that there is no way to
   distinguish a timeout from a missing block for a server without
   creating additional state, the need for which we want to avoid.)

6.  IANA Considerations

   This draft adds the following option numbers to the CoAP Option
   Numbers registry of [RFC7252]:









Bormann & Shelby         Expires January 5, 2015               [Page 27]

Internet-Draft         Blockwise transfers in CoAP             July 2014


                      +--------+--------+-----------+
                      | Number | Name   | Reference |
                      +--------+--------+-----------+
                      | 23     | Block2 | [RFCXXXX] |
                      |        |        |           |
                      | 27     | Block1 | [RFCXXXX] |
                      |        |        |           |
                      | 28     | Size2  | [RFCXXXX] |
                      +--------+--------+-----------+

                       Table 3: CoAP Option Numbers

   This draft adds the following response code to the CoAP Response
   Codes registry of [RFC7252]:

             +------+---------------------------+-----------+
             | Code | Description               | Reference |
             +------+---------------------------+-----------+
             | 2.31 | Continue                  | [RFCXXXX] |
             |      |                           |           |
             | 4.08 | Request Entity Incomplete | [RFCXXXX] |
             +------+---------------------------+-----------+

                       Table 4: CoAP Response Codes

7.  Security Considerations

   Providing access to blocks within a resource may lead to surprising
   vulnerabilities.  Where requests are not implemented atomically, an
   attacker may be able to exploit a race condition or confuse a server
   by inducing it to use a partially updated resource representation.
   Partial transfers may also make certain problematic data invisible to
   intrusion detection systems; it is RECOMMENDED that an intrusion
   detection system (IDS) that analyzes resource representations
   transferred by CoAP implement the Block options to gain access to
   entire resource representations.  Still, approaches such as
   transferring even-numbered blocks on one path and odd-numbered blocks
   on another path, or even transferring blocks multiple times with
   different content and obtaining a different interpretation of
   temporal order at the IDS than at the server, may prevent an IDS from
   seeing the whole picture.  These kinds of attacks are well understood
   from IP fragmentation and TCP segmentation; CoAP does not add
   fundamentally new considerations.

   Where access to a resource is only granted to clients making use of
   specific security associations, all blocks of that resource MUST be
   subject to the same security checks; it MUST NOT be possible for
   unprotected exchanges to influence blocks of an otherwise protected



Bormann & Shelby         Expires January 5, 2015               [Page 28]

Internet-Draft         Blockwise transfers in CoAP             July 2014


   resource.  As a related consideration, where object security is
   employed, PUT/POST should be implemented in the atomic fashion,
   unless the object security operation is performed on each access and
   the creation of unusable resources can be tolerated.

   A stateless server might be susceptible to an attack where the
   adversary sends a Block1 (e.g., PUT) block with a high block number:
   A naive implementation might exhaust its resources by creating a huge
   resource representation.

   Misleading size indications may be used by an attacker to induce
   buffer overflows in poor implementations, for which the usual
   considerations apply.

7.1.  Mitigating Resource Exhaustion Attacks

   Certain blockwise requests may induce the server to create state,
   e.g. to create a snapshot for the blockwise GET of a fast-changing
   resource to enable consistent access to the same version of a
   resource for all blocks, or to create temporary resource
   representations that are collected until pressed into service by a
   final PUT or POST with the more bit unset.  All mechanisms that
   induce a server to create state that cannot simply be cleaned up
   create opportunities for denial-of-service attacks.  Servers SHOULD
   avoid being subject to resource exhaustion based on state created by
   untrusted sources.  But even if this is done, the mitigation may
   cause a denial-of-service to a legitimate request when it is drowned
   out by other state-creating requests.  Wherever possible, servers
   should therefore minimize the opportunities to create state for
   untrusted sources, e.g. by using stateless approaches.

   Performing segmentation at the application layer is almost always
   better in this respect than at the transport layer or lower (IP
   fragmentation, adaptation layer fragmentation), for instance because
   there is application layer semantics that can be used for mitigation
   or because lower layers provide security associations that can
   prevent attacks.  However, it is less common to apply timeouts and
   keepalive mechanisms at the application layer than at lower layers.
   Servers MAY want to clean up accumulated state by timing it out (cf.
   response code 4.08), and clients SHOULD be prepared to run blockwise
   transfers in an expedient way to minimize the likelihood of running
   into such a timeout.

7.2.  Mitigating Amplification Attacks

   [RFC7252] discusses the susceptibility of CoAP end-points for use in
   amplification attacks.




Bormann & Shelby         Expires January 5, 2015               [Page 29]

Internet-Draft         Blockwise transfers in CoAP             July 2014


   A CoAP server can reduce the amount of amplification it provides to
   an attacker by offering large resource representations only in
   relatively small blocks.  With this, e.g., for a 1000 byte resource,
   a 10-byte request might result in an 80-byte response (with a 64-byte
   block) instead of a 1016-byte response, considerably reducing the
   amplification provided.

8.  Acknowledgements

   Much of the content of this draft is the result of discussions with
   the [RFC7252] authors, and via many CoRE WG discussions.

   Charles Palmer provided extensive editorial comments to a previous
   version of this draft, some of which the authors hope to have covered
   in this version.  Esko Dijk reviewed a more recent version, leading
   to a number of further editorial improvements, a solution to the 4.13
   ambiguity problem, and the section about combining Block and
   multicast.  Markus Becker proposed getting rid of an ill-conceived
   default value for the Block2 and Block1 options.  Peter Bigot
   insisted on a more systematic coverage of the options and response
   code.

   Kepeng Li, Linyi Tian, and Barry Leiba wrote up an early version of
   the Size Option, which has informed this draft.  Klaus Hartke wrote
   some of the text describing the interaction of Block2 with Observe.
   Matthias Kovatsch provided a number of significant simplifications of
   the protocol.

9.  References

9.1.  Normative References

   [I-D.ietf-core-observe]
              Hartke, K., "Observing Resources in CoAP", draft-ietf-
              core-observe-14 (work in progress), June 2014.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC7252]  Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
              Application Protocol (CoAP)", RFC 7252, June 2014.

9.2.  Informative References








Bormann & Shelby         Expires January 5, 2015               [Page 30]

Internet-Draft         Blockwise transfers in CoAP             July 2014


   [REST]     Fielding, R., "Architectural Styles and the Design of
              Network-based Software Architectures", Ph.D. Dissertation,
              University of California, Irvine, 2000,
              <http://www.ics.uci.edu/~fielding/pubs/dissertation/
              fielding_dissertation.pdf>.

   [RFC4919]  Kushalnagar, N., Montenegro, G., and C. Schumacher, "IPv6
              over Low-Power Wireless Personal Area Networks (6LoWPANs):
              Overview, Assumptions, Problem Statement, and Goals", RFC
              4919, August 2007.

   [RFC4944]  Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler,
              "Transmission of IPv6 Packets over IEEE 802.15.4
              Networks", RFC 4944, September 2007.

   [RFC6690]  Shelby, Z., "Constrained RESTful Environments (CoRE) Link
              Format", RFC 6690, August 2012.

   [RFC7228]  Bormann, C., Ersue, M., and A. Keranen, "Terminology for
              Constrained-Node Networks", RFC 7228, May 2014.

   [RFC7230]  Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
              (HTTP/1.1): Message Syntax and Routing", RFC 7230, June
              2014.

   [RFC7233]  Fielding, R., Lafon, Y., and J. Reschke, "Hypertext
              Transfer Protocol (HTTP/1.1): Range Requests", RFC 7233,
              June 2014.

Authors' Addresses

   Carsten Bormann
   Universitaet Bremen TZI
   Postfach 330440
   Bremen  D-28359
   Germany

   Phone: +49-421-218-63921
   Email: cabo@tzi.org












Bormann & Shelby         Expires January 5, 2015               [Page 31]

Internet-Draft         Blockwise transfers in CoAP             July 2014


   Zach Shelby (editor)
   ARM
   150 Rose Orchard
   San Jose, CA  95134
   USA

   Phone: +1-408-203-9434
   Email: zach.shelby@arm.com











































Bormann & Shelby         Expires January 5, 2015               [Page 32]

Html markup produced by rfcmarkup 1.118, available from https://tools.ietf.org/tools/rfcmarkup/
================================================ FILE: examples/block1/server.go ================================================ package main import ( "io/ioutil" "log" "github.com/zubairhamed/canopus" ) func main() { server := canopus.NewServer() server.Get("/blockinfo", func(req canopus.Request) canopus.Response { msg := canopus.ContentMessage(req.GetMessage().GetMessageId(), canopus.MessageAcknowledgment) msg.SetStringPayload("Acknowledged: " + req.GetMessage().GetPayload().String()) res := canopus.NewResponse(msg, nil) return res }) server.Post("/blockupload", func(req canopus.Request) canopus.Response { msg := canopus.ContentMessage(req.GetMessage().GetMessageId(), canopus.MessageAcknowledgment) msg.SetStringPayload("Acknowledged: " + req.GetMessage().GetPayload().String()) res := canopus.NewResponse(msg, nil) // Save to file payload := req.GetMessage().GetPayload().GetBytes() log.Println("len", len(payload)) err := ioutil.WriteFile("output.html", payload, 0644) if err != nil { log.Println(err) } return res }) server.OnBlockMessage(func(msg canopus.Message, inbound bool) { // log.Println("Incoming Block Message:") // canopus.PrintMessage(msg) }) server.ListenAndServe(":5683") <-make(chan struct{}) } ================================================ FILE: examples/discovery/main.go ================================================ package main import ( "fmt" "crypto/rand" "github.com/zubairhamed/canopus" ) func main() { fmt.Println("Starting up") server := canopus.NewServer() server.ListenAndServeDTLS(":5682") fmt.Println("New Request..") req := canopus.NewRequest(canopus.MessageConfirmable, canopus.Post, canopus.GenerateMessageID()) // req.SetStringPayload(BuildModelResourceStringPayload(c.enabledObjects)) req.SetRequestURI("/rd") req.SetURIQuery("ep", "name") // session := canopus.NewUDPServerSession("localhost:5684", server.GetConnection(), server) // DTLS Version fmt.Println("Initializing SSL") secret := make([]byte, 32) if n, err := rand.Read(secret); n != 32 || err != nil { panic(err) } server.(*canopus.DefaultCoapServer).SetCookieSecret(secret) server.HandlePSK(func(id string) []byte { return []byte("secretPSK") }) ctx, err := canopus.NewServerDtlsContext() if err != nil { panic(err.Error()) } session := canopus.NewDTLSServerSession("localhost:5684", server.GetConnection(), server, ctx) fmt.Println("Sending Message") resp, err := canopus.SendMessage(req.GetMessage(), session) fmt.Println("Response", resp, err) canopus.PrintMessage(resp.GetMessage()) <-make(chan struct{}) } ================================================ FILE: examples/dtls/simple-psk/client.go ================================================ package main import ( "fmt" "github.com/zubairhamed/canopus" ) func main() { conn, err := canopus.DialDTLS("localhost:5684", "canopus", "secretPSK") if err != nil { panic(err.Error()) } req := canopus.NewRequest(canopus.MessageConfirmable, canopus.Get) req.SetStringPayload("Hello, canopus") req.SetRequestURI("/hello") resp, err := conn.Send(req) if err != nil { panic(err.Error()) } fmt.Println("Got Response:" + resp.GetMessage().GetPayload().String()) } ================================================ FILE: examples/dtls/simple-psk/server.go ================================================ package main import ( "fmt" "github.com/zubairhamed/canopus" ) func main() { server := canopus.NewServer() server.Get("/hello", func(req canopus.Request) canopus.Response { fmt.Println("Hello Called") msg := canopus.ContentMessage(req.GetMessage().GetMessageId(), canopus.MessageAcknowledgment) msg.SetStringPayload("Acknowledged: " + req.GetMessage().GetPayload().String()) res := canopus.NewResponse(msg, nil) return res }) server.HandlePSK(func(id string) []byte { return []byte("secretPSK") }) server.ListenAndServeDTLS(":5684") <-make(chan struct{}) } ================================================ FILE: examples/observe/client.go ================================================ package main import ( "fmt" "github.com/zubairhamed/canopus" ) func main() { conn, err := canopus.Dial("localhost:5683") tok, err := conn.ObserveResource("/watch/this") if err != nil { panic(err.Error()) } obsChannel := make(chan canopus.ObserveMessage) done := make(chan bool) go conn.Observe(obsChannel) notifyCount := 0 go func() { for { select { case obsMsg, open := <-obsChannel: if open { if notifyCount == 5 { fmt.Println("[CLIENT >> ] Canceling observe after 5 notifications..") go conn.CancelObserveResource("watch/this", tok) go conn.StopObserve(obsChannel) done <- true return } else { notifyCount++ // msg := obsMsg.Msg\ resource := obsMsg.GetResource() val := obsMsg.GetValue() fmt.Println("[CLIENT >> ] Got Change Notification for resource and value: ", notifyCount, resource, val) } } else { done <- true return } } } }() <-done fmt.Println("Done") } ================================================ FILE: examples/observe/server.go ================================================ package main import ( "fmt" "math/rand" "strconv" "time" "github.com/zubairhamed/canopus" ) func main() { server := canopus.NewServer() server.Get("/watch/this", func(req canopus.Request) canopus.Response { msg := canopus.NewMessageOfType(canopus.MessageAcknowledgment, req.GetMessage().GetMessageId(), canopus.NewPlainTextPayload("Acknowledged")) res := canopus.NewResponse(msg, nil) return res }) ticker := time.NewTicker(3 * time.Second) go func() { for { select { case <-ticker.C: changeVal := strconv.Itoa(rand.Int()) fmt.Println("[SERVER << ] Change of value -->", changeVal) server.NotifyChange("/watch/this", changeVal, false) } } }() server.OnMessage(func(msg canopus.Message, inbound bool) { canopus.PrintMessage(msg) }) server.OnObserve(func(resource string, msg canopus.Message) { fmt.Println("[SERVER << ] Observe Requested for " + resource) }) server.ListenAndServe(":5683") <-make(chan struct{}) } ================================================ FILE: examples/proxy/coap/client.go ================================================ package main import "github.com/zubairhamed/canopus" func main() { conn, err := canopus.Dial("localhost:5683") if err != nil { panic(err.Error()) } req := canopus.NewRequest(canopus.MessageConfirmable, canopus.Get, canopus.GenerateMessageID()) req.SetProxyURI("coap://localhost:5685/proxycall") canopus.PrintMessage(req.GetMessage()) resp, err := conn.Send(req) if err != nil { println("err", err) } canopus.PrintMessage(resp.GetMessage()) } ================================================ FILE: examples/proxy/coap/proxy.go ================================================ package main import "github.com/zubairhamed/canopus" func main() { server := canopus.NewServer() server.ProxyOverCoap(true) server.Get("/proxycall", func(req canopus.Request) canopus.Response { canopus.PrintMessage(req.GetMessage()) msg := canopus.ContentMessage(req.GetMessage().GetMessageId(), canopus.MessageAcknowledgment) msg.SetStringPayload("Acknowledged: " + req.GetMessage().GetPayload().String()) res := canopus.NewResponse(msg, nil) return res }) server.ListenAndServe(":5683") <-make(chan struct{}) } ================================================ FILE: examples/proxy/coap/server.go ================================================ package main import "github.com/zubairhamed/canopus" func main() { server := canopus.NewServer() server.Get("/proxycall", func(req canopus.Request) canopus.Response { canopus.PrintMessage(req.GetMessage()) msg := canopus.ContentMessage(req.GetMessage().GetMessageId(), canopus.MessageAcknowledgment) msg.SetStringPayload("Data from :5685 -- " + req.GetMessage().GetPayload().String()) res := canopus.NewResponse(msg, nil) return res }) server.ListenAndServe(":5685") <-make(chan struct{}) } ================================================ FILE: examples/proxy/http/client.go ================================================ package main import "github.com/zubairhamed/canopus" func main() { conn, err := canopus.Dial("localhost:5683") if err != nil { panic(err.Error()) } req := canopus.NewRequest(canopus.MessageConfirmable, canopus.Get, canopus.GenerateMessageID()) req.SetProxyURI("https://httpbin.org/get") canopus.PrintMessage(req.GetMessage()) resp, err := conn.Send(req) if err != nil { println("err", err) } canopus.PrintMessage(resp.GetMessage()) } ================================================ FILE: examples/proxy/http/server.go ================================================ package main import "github.com/zubairhamed/canopus" func main() { server := canopus.NewServer() server.ProxyOverHttp(true) server.ListenAndServe(":5683") <-make(chan struct{}) } ================================================ FILE: examples/simple/client.go ================================================ package main import ( "fmt" "github.com/zubairhamed/canopus" ) func main() { fmt.Println("Connecting to CoAP Server") conn, err := canopus.Dial("localhost:5683") if err != nil { panic(err.Error()) } req := canopus.NewRequest(canopus.MessageConfirmable, canopus.Get) req.SetStringPayload("Hello, canopus") req.SetRequestURI("/hello") fmt.Println("Sending request..") resp, err := conn.Send(req) if err != nil { panic(err.Error()) } fmt.Println("Got Response:" + resp.GetMessage().GetPayload().String()) } ================================================ FILE: examples/simple/server.go ================================================ package main import ( "log" "github.com/zubairhamed/canopus" ) func main() { server := canopus.NewServer() server.Get("/hello", func(req canopus.Request) canopus.Response { log.Println("Hello Called") msg := canopus.ContentMessage(req.GetMessage().GetMessageId(), canopus.MessageAcknowledgment) msg.SetStringPayload("Acknowledged with response : " + req.GetMessage().GetPayload().String()) res := canopus.NewResponse(msg, nil) return res }) server.Post("/hello", func(req canopus.Request) canopus.Response { log.Println("Hello Called via POST") msg := canopus.ContentMessage(req.GetMessage().GetMessageId(), canopus.MessageAcknowledgment) msg.SetStringPayload("Acknowledged: " + req.GetMessage().GetPayload().String()) res := canopus.NewResponse(msg, nil) return res }) server.Get("/basic", func(req canopus.Request) canopus.Response { msg := canopus.NewMessageOfType(canopus.MessageAcknowledgment, req.GetMessage().GetMessageId(), canopus.NewPlainTextPayload("Acknowledged")) res := canopus.NewResponse(msg, nil) return res }) server.Get("/basic/json", func(req canopus.Request) canopus.Response { msg := canopus.NewMessageOfType(canopus.MessageAcknowledgment, req.GetMessage().GetMessageId(), nil) res := canopus.NewResponse(msg, nil) return res }) server.Get("/basic/xml", func(req canopus.Request) canopus.Response { msg := canopus.NewMessageOfType(canopus.MessageAcknowledgment, req.GetMessage().GetMessageId(), nil) res := canopus.NewResponse(msg, nil) return res }) server.OnMessage(func(msg canopus.Message, inbound bool) { canopus.PrintMessage(msg) }) server.ListenAndServe(":5683") <-make(chan struct{}) } ================================================ FILE: init.go ================================================ package canopus func init() { } ================================================ FILE: json.go ================================================ package canopus import ( "encoding/json" "log" ) func NewJSONPayload(obj interface{}) MessagePayload { return &JSONPayload{ obj: obj, } } // Represents a message payload containing JSON String type JSONPayload struct { obj interface{} } func (p *JSONPayload) GetBytes() []byte { o, err := json.MarshalIndent(p.obj, "", " ") if err != nil { log.Println(err) return []byte{} } return []byte(string(o)) } func (p *JSONPayload) Length() int { return 0 } func (p *JSONPayload) String() string { o, _ := json.Marshal(p.obj) return string(o) } ================================================ FILE: message.go ================================================ package canopus import ( "bytes" "encoding/binary" "errors" "log" "sort" "strings" ) // Instantiates a new message object // messageType (e.g. Confirm/Non-Confirm) // CoAP code 404 - Not found etc // Message ID uint16 unique id func NewMessage(messageType uint8, code CoapCode, messageID uint16) Message { return &CoapMessage{ MessageType: messageType, MessageID: messageID, Code: code, Token: []byte(GenerateToken(8)), } } // Instantiates an empty message with a given message id func NewEmptyMessage(id uint16) Message { msg := NewMessageOfType(MessageAcknowledgment, id, nil) return msg } // Instantiates an empty message of a specific type and message id func NewMessageOfType(t uint8, id uint16, payload MessagePayload) Message { return &CoapMessage{ MessageType: t, MessageID: id, Payload: payload, } } /* 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |Ver| T | TKL | Code | Message ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Token (if any, TKL bytes) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Options (if any) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |1 1 1 1 1 1 1 1| Payload (if any) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ */ // Converts an array of bytes to a Mesasge object. // An error is returned if a parsing error occurs func BytesToMessage(data []byte) (Message, error) { msg := &CoapMessage{} dataLen := len(data) if dataLen < 4 { return msg, ErrPacketLengthLessThan4 } ver := data[DataHeader] >> 6 if ver != 1 { return nil, ErrInvalidCoapVersion } msg.MessageType = data[DataHeader] >> 4 & 0x03 tokenLength := data[DataHeader] & 0x0f msg.Code = CoapCode(data[DataCode]) msg.MessageID = binary.BigEndian.Uint16(data[DataMsgIDStart:DataMsgIDEnd]) // Token if tokenLength > 0 { msg.Token = make([]byte, tokenLength) token := data[DataTokenStart : DataTokenStart+tokenLength] copy(msg.Token, token) } /* 0 1 2 3 4 5 6 7 +---------------+---------------+ | | | | Option Delta | Option Length | 1 byte | | | +---------------+---------------+ \ \ / Option Delta / 0-2 bytes \ (extended) \ +-------------------------------+ \ \ / Option Length / 0-2 bytes \ (extended) \ +-------------------------------+ \ \ / / \ \ / Option Value / 0 or more bytes \ \ / / \ \ +-------------------------------+ */ tmp := data[DataTokenStart+msg.GetTokenLength():] lastOptionID := uint(0) for len(tmp) > 0 { if tmp[0] == PayloadMarker { tmp = tmp[1:] break } optionDelta := uint(tmp[0] >> 4) optionLength := uint(tmp[0] & 0x0f) tmp = tmp[1:] switch optionDelta { case 13: optionDeltaExtended := uint(tmp[0]) optionDelta += optionDeltaExtended tmp = tmp[1:] break case 14: optionDeltaExtended := uint(decodeInt(tmp[:2])) optionDelta = uint(optionDeltaExtended + 269) tmp = tmp[2:] break case 15: return msg, ErrOptionDeltaUsesValue15 } lastOptionID += optionDelta switch optionLength { case 13: optionLengthExtended := uint(tmp[0]) optionLength += optionLengthExtended tmp = tmp[1:] break case 14: optionLengthExtended := uint(decodeInt(tmp[:1])) optionLength += uint(optionLengthExtended - uint(269)) tmp = tmp[2:] break case 15: return msg, ErrOptionLengthUsesValue15 } optCode := OptionCode(lastOptionID) if optionLength > 0 { optionValue := tmp[:optionLength] switch optCode { case OptionURIPort, OptionContentFormat, OptionMaxAge, OptionAccept, OptionSize1, OptionSize2, OptionBlock1, OptionBlock2: msg.Options = append(msg.Options, NewOption(optCode, decodeInt(optionValue))) break case OptionURIHost, OptionEtag, OptionLocationPath, OptionURIPath, OptionURIQuery, OptionLocationQuery, OptionProxyURI, OptionProxyScheme, OptionObserve: msg.Options = append(msg.Options, NewOption(optCode, string(optionValue))) break default: if lastOptionID&0x01 == 1 { log.Println("Unknown Critical Option id ", lastOptionID) return msg, ErrUnknownCriticalOption } log.Println("Warning: Unknown Option id ", optionDelta) msg.Options = append(msg.Options, NewOption(optCode, optionValue)) break } tmp = tmp[optionLength:] } else { msg.Options = append(msg.Options, NewOption(optCode, nil)) } } msg.Payload = NewBytesPayload(tmp) err := ValidateMessage(msg) return msg, err } // type to sort the coap options list (which is mandatory) prior to transmission type SortOptions []Option func (opts SortOptions) Len() int { return len(opts) } func (opts SortOptions) Swap(i, j int) { opts[i], opts[j] = opts[j], opts[i] } func (opts SortOptions) Less(i, j int) bool { return opts[i].GetCode() < opts[j].GetCode() } // Converts a message object to a byte array. Typically done prior to transmission func MessageToBytes(msg Message) ([]byte, error) { messageID := []byte{0, 0} binary.BigEndian.PutUint16(messageID, msg.GetMessageId()) buf := bytes.Buffer{} buf.Write([]byte{(1 << 6) | (msg.GetMessageType() << 4) | 0x0f&msg.GetTokenLength()}) buf.Write([]byte{byte(msg.GetCode())}) buf.Write([]byte{messageID[0]}) buf.Write([]byte{messageID[1]}) buf.Write(msg.GetToken()) // Sort Options sort.Sort(SortOptions(msg.GetAllOptions())) lastOptionCode := 0 for _, opt := range msg.GetAllOptions() { optCode := int(opt.GetCode()) optDelta := optCode - lastOptionCode optDeltaValue, _ := getOptionHeaderValue(optDelta) byteValue := valueToBytes(opt.GetValue()) valueLength := len(byteValue) optLength := valueLength optLengthValue, _ := getOptionHeaderValue(optLength) buf.Write([]byte{byte(optDeltaValue<<4 | optLengthValue)}) if optDeltaValue == 13 { buf.Write([]byte{byte(optDelta - 13)}) } else if optDeltaValue == 14 { tmpBuf := new(bytes.Buffer) binary.Write(tmpBuf, binary.BigEndian, uint16(optDelta-269)) buf.Write(tmpBuf.Bytes()) } // TODO: If optDeltaValue == 15, throw error if optLengthValue == 13 { buf.Write([]byte{byte(optLength - 13)}) } else if optLengthValue == 14 { tmpBuf := new(bytes.Buffer) binary.Write(tmpBuf, binary.BigEndian, uint16(optLength-269)) buf.Write(tmpBuf.Bytes()) } buf.Write(byteValue) lastOptionCode = int(optCode) } if msg.GetPayload() != nil { if msg.GetPayload().Length() > 0 { buf.Write([]byte{PayloadMarker}) } buf.Write(msg.GetPayload().GetBytes()) } return buf.Bytes(), nil } func getOptionHeaderValue(optValue int) (int, error) { switch true { case optValue <= 12: return optValue, nil case optValue <= 268: return 13, nil case optValue <= 65804: return 14, nil } return 0, errors.New("Invalid Option Delta") } // Validates a message object and returns any error upon validation failure func ValidateMessage(msg Message) error { if msg.GetMessageType() > 3 { return ErrUnknownMessageType } if msg.GetTokenLength() > 8 { return ErrInvalidTokenLength } // Repeated Unrecognized Options for _, opt := range msg.GetAllOptions() { opts := msg.GetOptions(opt.GetCode()) if len(opts) > 1 { if !IsRepeatableOption(opts[0]) { if opts[0].GetCode()&0x01 == 1 { return ErrUnknownCriticalOption } } } } return nil } func NewBlockMessage() BlockMessage { return &CoapBlockMessage{ Sequence: 0, } } type CoapBlockMessage struct { CoapMessage MessageBuf []byte Sequence uint32 } type BySequence []*CoapBlockMessage func (o BySequence) Len() int { return len(o) } func (o BySequence) Swap(i, j int) { o[i], o[j] = o[j], o[i] } func (o BySequence) Less(i, j int) bool { return o[i].Sequence < o[j].Sequence } // A Message object represents a CoAP payload type CoapMessage struct { MessageType uint8 Code CoapCode MessageID uint16 Payload MessagePayload Token []byte Options []Option } func (m *CoapMessage) SetMessageType(t uint8) { m.MessageType = t } func (m *CoapMessage) SetToken(t []byte) { m.Token = t } func (m *CoapMessage) SetPayload(p MessagePayload) { m.Payload = p } func (m *CoapMessage) SetMessageId(id uint16) { m.MessageID = id } func (m *CoapMessage) GetToken() []byte { return m.Token } func (m *CoapMessage) GetPayload() MessagePayload { return m.Payload } func (m *CoapMessage) GetMessageType() uint8 { return m.MessageType } func (m *CoapMessage) GetMessageId() uint16 { return m.MessageID } func (m *CoapMessage) GetCode() CoapCode { return m.Code } func (m *CoapMessage) GetAllOptions() []Option { return m.Options } func (m *CoapMessage) GetAcceptedContent() MediaType { mediaTypeCode := m.GetOption(OptionAccept).IntValue() return MediaType(mediaTypeCode) } func (m *CoapMessage) GetCodeString() string { codeClass := string(m.Code >> 5) codeDetail := string(m.Code & 0x1f) return codeClass + "." + codeDetail } func (m *CoapMessage) GetMethod() uint8 { return (byte(m.Code) & 0x1f) } func (m *CoapMessage) GetTokenLength() uint8 { return uint8(len(m.Token)) } func (m *CoapMessage) GetTokenString() string { return string(m.Token[:len(m.Token)]) } // Returns an array of options given an option code func (m CoapMessage) GetOptions(id OptionCode) []Option { var opts []Option for _, val := range m.Options { if val.GetCode() == id { opts = append(opts, val) } } return opts } // Returns the first option found for a given option code func (m CoapMessage) GetOption(id OptionCode) Option { for _, val := range m.Options { if val.GetCode() == id { return val } } return nil } // Attempts to return the string value of an Option func (m CoapMessage) GetOptionsAsString(id OptionCode) []string { opts := m.GetOptions(id) var str []string for _, o := range opts { if o.GetValue() != nil { str = append(str, o.GetValue().(string)) } } return str } // Returns the string value of the Location Path Options by joining and defining a / separator func (m *CoapMessage) GetLocationPath() string { opts := m.GetOptionsAsString(OptionLocationPath) return strings.Join(opts, "/") } // Returns the string value of the Uri Path Options by joining and defining a / separator func (m CoapMessage) GetURIPath() string { opts := m.GetOptionsAsString(OptionURIPath) return "/" + strings.Join(opts, "/") } // Add an Option to the message. If an option is not repeatable, it will replace // any existing defined Option of the same type func (m *CoapMessage) AddOption(code OptionCode, value interface{}) { opt := NewOption(code, value) if IsRepeatableOption(opt) { m.Options = append(m.Options, opt) } else { m.RemoveOptions(code) m.Options = append(m.Options, opt) } } // Add an array of Options to the message. If an option is not repeatable, it will replace // any existing defined Option of the same type func (m *CoapMessage) AddOptions(opts []Option) { for _, opt := range opts { if IsRepeatableOption(opt) { m.Options = append(m.Options, opt) } else { m.RemoveOptions(opt.GetCode()) m.Options = append(m.Options, opt) } } } func (c *CoapMessage) SetBlock1Option(opt Option) { c.AddOption(OptionBlock1, opt.GetValue()) } // Copies the given list of options from another message to this one func (m *CoapMessage) CloneOptions(cm Message, opts ...OptionCode) { for _, opt := range opts { m.AddOptions(cm.GetOptions(opt)) } } // Replace an Option func (m *CoapMessage) ReplaceOptions(code OptionCode, opts []Option) { m.RemoveOptions(code) m.AddOptions(opts) } // Removes an Option func (m *CoapMessage) RemoveOptions(id OptionCode) { var opts []Option for _, opt := range m.Options { if opt.GetCode() != id { opts = append(opts, opt) } } m.Options = opts } // Adds a string payload func (m *CoapMessage) SetStringPayload(s string) { m.Payload = NewPlainTextPayload(s) } // Determines if a message contains options for proxying (i.e. Proxy-Scheme or Proxy-Uri) func IsProxyRequest(msg Message) bool { if msg.GetOption(OptionProxyScheme) != nil || msg.GetOption(OptionProxyURI) != nil { return true } return false } func valueToBytes(value interface{}) []byte { var v uint32 switch i := value.(type) { case string: return []byte(i) case []byte: return i case MediaType: v = uint32(i) case byte: v = uint32(i) case int: v = uint32(i) case int32: v = uint32(i) case uint: v = uint32(i) case uint32: v = i default: break } return encodeInt(v) } func decodeInt(b []byte) uint32 { tmp := []byte{0, 0, 0, 0} copy(tmp[4-len(b):], b) return binary.BigEndian.Uint32(tmp) } func encodeInt(v uint32) []byte { switch { case v == 0: return nil case v < 256: return []byte{byte(v)} case v < 65536: rv := []byte{0, 0} binary.BigEndian.PutUint16(rv, uint16(v)) return rv case v < 16777216: rv := []byte{0, 0, 0, 0} binary.BigEndian.PutUint32(rv, uint32(v)) return rv[1:] default: rv := []byte{0, 0, 0, 0} binary.BigEndian.PutUint32(rv, uint32(v)) return rv } } // Determines if a message contains URI targeting a CoAP resource func IsCoapURI(uri string) bool { if strings.HasPrefix(uri, "coap") || strings.HasPrefix(uri, "coaps") { return true } return false } // Determines if a message contains URI targeting an HTTP resource func IsHTTPURI(uri string) bool { if strings.HasPrefix(uri, "http") || strings.HasPrefix(uri, "https") { return true } return false } // Gets the string representation of a CoAP Method code (e.g. GET, PUT, DELETE etc) func MethodString(c CoapCode) string { switch c { case Get: return "GET" case Delete: return "DELETE" case Post: return "POST" case Put: return "PUT" } return "" } // Response Code Messages // Creates a Non-Confirmable Empty Message func EmptyMessage(messageID uint16, messageType uint8) Message { return NewMessage(messageType, CoapCodeEmpty, messageID) } // Creates a Non-Confirmable with CoAP Code 201 - Created func CreatedMessage(messageID uint16, messageType uint8) Message { return NewMessage(messageType, CoapCodeCreated, messageID) } // // Creates a Non-Confirmable with CoAP Code 202 - Deleted func DeletedMessage(messageID uint16, messageType uint8) Message { return NewMessage(messageType, CoapCodeDeleted, messageID) } // Creates a Non-Confirmable with CoAP Code 203 - Valid func ValidMessage(messageID uint16, messageType uint8) Message { return NewMessage(messageType, CoapCodeValid, messageID) } // Creates a Non-Confirmable with CoAP Code 204 - Changed func ChangedMessage(messageID uint16, messageType uint8) Message { return NewMessage(messageType, CoapCodeChanged, messageID) } // Creates a Non-Confirmable with CoAP Code 205 - Content func ContentMessage(messageID uint16, messageType uint8) Message { return NewMessage(messageType, CoapCodeContent, messageID) } // Creates a Non-Confirmable with CoAP Code 400 - Bad Request func BadRequestMessage(messageID uint16, messageType uint8) Message { return NewMessage(messageType, CoapCodeBadRequest, messageID) } func ContinueMessage(messageID uint16, messageType uint8) Message { return NewMessage(messageType, CoapCodeContinue, messageID) } // Creates a Non-Confirmable with CoAP Code 401 - Unauthorized func UnauthorizedMessage(messageID uint16, messageType uint8) Message { return NewMessage(messageType, CoapCodeUnauthorized, messageID) } // Creates a Non-Confirmable with CoAP Code 402 - Bad Option func BadOptionMessage(messageID uint16, messageType uint8) Message { return NewMessage(messageType, CoapCodeBadOption, messageID) } // Creates a Non-Confirmable with CoAP Code 403 - Forbidden func ForbiddenMessage(messageID uint16, messageType uint8) Message { return NewMessage(messageType, CoapCodeForbidden, messageID) } // Creates a Non-Confirmable with CoAP Code 404 - Not Found func NotFoundMessage(messageID uint16, messageType uint8, token []byte) (m Message) { m = NewMessage(messageType, CoapCodeNotFound, messageID) m.SetToken(token) return } // Creates a Non-Confirmable with CoAP Code 405 - Method Not Allowed func MethodNotAllowedMessage(messageID uint16, messageType uint8) Message { return NewMessage(messageType, CoapCodeMethodNotAllowed, messageID) } // Creates a Non-Confirmable with CoAP Code 406 - Not Acceptable func NotAcceptableMessage(messageID uint16, messageType uint8) Message { return NewMessage(messageType, CoapCodeNotAcceptable, messageID) } // Creates a Non-Confirmable with CoAP Code 409 - Conflict func ConflictMessage(messageID uint16, messageType uint8) Message { return NewMessage(messageType, CoapCodeConflict, messageID) } // Creates a Non-Confirmable with CoAP Code 412 - Precondition Failed func PreconditionFailedMessage(messageID uint16, messageType uint8) Message { return NewMessage(messageType, CoapCodePreconditionFailed, messageID) } // Creates a Non-Confirmable with CoAP Code 413 - Request Entity Too Large func RequestEntityTooLargeMessage(messageID uint16, messageType uint8) Message { return NewMessage(messageType, CoapCodeRequestEntityTooLarge, messageID) } // Creates a Non-Confirmable with CoAP Code 415 - Unsupported Content Format func UnsupportedContentFormatMessage(messageID uint16, messageType uint8) Message { return NewMessage(messageType, CoapCodeUnsupportedContentFormat, messageID) } // Creates a Non-Confirmable with CoAP Code 500 - Internal Server Error func InternalServerErrorMessage(messageID uint16, messageType uint8) Message { return NewMessage(messageType, CoapCodeInternalServerError, messageID) } // Creates a Non-Confirmable with CoAP Code 501 - Not Implemented func NotImplementedMessage(messageID uint16, messageType uint8) Message { return NewMessage(messageType, CoapCodeNotImplemented, messageID) } // Creates a Non-Confirmable with CoAP Code 502 - Bad Gateway func BadGatewayMessage(messageID uint16, messageType uint8) Message { return NewMessage(messageType, CoapCodeBadGateway, messageID) } // Creates a Non-Confirmable with CoAP Code 503 - Service Unavailable func ServiceUnavailableMessage(messageID uint16, messageType uint8) Message { return NewMessage(messageType, CoapCodeServiceUnavailable, messageID) } // Creates a Non-Confirmable with CoAP Code 504 - Gateway Timeout func GatewayTimeoutMessage(messageID uint16, messageType uint8) Message { return NewMessage(messageType, CoapCodeGatewayTimeout, messageID) } // Creates a Non-Confirmable with CoAP Code 505 - Proxying Not Supported func ProxyingNotSupportedMessage(messageID uint16, messageType uint8) Message { return NewMessage(messageType, CoapCodeProxyingNotSupported, messageID) } ================================================ FILE: message_test.go ================================================ package canopus import ( "bytes" "testing" "github.com/stretchr/testify/assert" ) func TestMessage(t *testing.T) { assert.NotNil(t, NewMessage(MessageConfirmable, Get, 12345)) assert.NotNil(t, NewEmptyMessage(12345)) } func TestInvalidMessage(t *testing.T) { _, err := BytesToMessage(make([]byte, 0)) assert.NotNil(t, err, "Message should be invalid") _, err = BytesToMessage(make([]byte, 4)) assert.NotNil(t, err, "Message should be invalid") } func TestMessagValidation(t *testing.T) { // ValidateMessage() } func TestMessageConversion(t *testing.T) { msg := NewBasicConfirmableMessage() msgId := msg.GetMessageId() // Byte 1 msg.AddOption(OptionContentFormat, MediaTypeApplicationLinkFormat) // Convert Message to BYte b, err := MessageToBytes(msg) // Reconvert Back Bytes to Message newMsg, err := BytesToMessage(b) assert.Nil(t, err, "An error occured converting bytes to message") assert.Equal(t, 0, int(newMsg.GetMessageType())) // 0x0: Type Confirmable assert.Equal(t, "abcd1234", bytes.NewBuffer(newMsg.GetToken()).String(), "Token String not the same after reconversion") assert.Equal(t, int(msgId), int(newMsg.GetMessageId()), "Message ID not the same after reconversion") assert.NotEqual(t, 0, len(newMsg.GetAllOptions()), "Options should not be 0") } func TestMessageBadOptions(t *testing.T) { // testMsg := NewBasicConfirmableMessage() // Unknown Critical Option // unk := OptionCode(99) // testMsg.AddOption(unk, 0) // testMsg.AddOption(OPTION_CONTENT_FORMAT, MEDIATYPE_APPLICATION_LINK_FORMAT) // _, err := MessageToBytes(testMsg) // assert.NotNil(t, err, "Should throw ERR_UNKNOWN_CRITICAL_OPTION") } func TestMessageObject(t *testing.T) { msg := &CoapMessage{} assert.Equal(t, 0, len(msg.Options)) msg.AddOptions(NewPathOptions("/example")) msg.AddOption(OptionAccept, MediaTypeApplicationXML) msg.AddOption(OptionContentFormat, MediaTypeApplicationJSON) assert.Equal(t, 3, len(msg.Options)) opt := msg.GetOption(OptionAccept) assert.NotNil(t, opt) msg.RemoveOptions(OptionURIPath) assert.Equal(t, 2, len(msg.Options)) } func TestOptionConversion(t *testing.T) { preMsg := NewBasicConfirmableMessage() preMsg.AddOption(OptionIfMatch, "") preMsg.AddOptions(NewPathOptions("/test")) preMsg.AddOption(OptionEtag, "1234567890") preMsg.AddOption(OptionIfNoneMatch, nil) preMsg.AddOption(OptionObserve, 0) preMsg.AddOption(OptionURIPort, 1234) preMsg.AddOption(OptionLocationPath, "/aaa") preMsg.AddOption(OptionContentFormat, 1) preMsg.AddOption(OptionMaxAge, 1) preMsg.AddOption(OptionProxyURI, "http://www.google.com") preMsg.AddOption(OptionProxyScheme, "http://proxy.scheme") converted, _ := MessageToBytes(preMsg) postMsg, _ := BytesToMessage(converted) PrintMessage(postMsg) } func TestNewMessageHelpers(t *testing.T) { var messageID uint16 = 12345 testData := []struct { msg Message code CoapCode }{ {EmptyMessage(messageID, MessageAcknowledgment), CoapCodeEmpty}, {CreatedMessage(messageID, MessageAcknowledgment), CoapCodeCreated}, {DeletedMessage(messageID, MessageAcknowledgment), CoapCodeDeleted}, {ValidMessage(messageID, MessageAcknowledgment), CoapCodeValid}, {ChangedMessage(messageID, MessageAcknowledgment), CoapCodeChanged}, {ContentMessage(messageID, MessageAcknowledgment), CoapCodeContent}, {BadRequestMessage(messageID, MessageAcknowledgment), CoapCodeBadRequest}, {UnauthorizedMessage(messageID, MessageAcknowledgment), CoapCodeUnauthorized}, {BadOptionMessage(messageID, MessageAcknowledgment), CoapCodeBadOption}, {ForbiddenMessage(messageID, MessageAcknowledgment), CoapCodeForbidden}, {NotFoundMessage(messageID, MessageAcknowledgment, nil), CoapCodeNotFound}, {MethodNotAllowedMessage(messageID, MessageAcknowledgment), CoapCodeMethodNotAllowed}, {NotAcceptableMessage(messageID, MessageAcknowledgment), CoapCodeNotAcceptable}, {ConflictMessage(messageID, MessageAcknowledgment), CoapCodeConflict}, {PreconditionFailedMessage(messageID, MessageAcknowledgment), CoapCodePreconditionFailed}, {RequestEntityTooLargeMessage(messageID, MessageAcknowledgment), CoapCodeRequestEntityTooLarge}, {UnsupportedContentFormatMessage(messageID, MessageAcknowledgment), CoapCodeUnsupportedContentFormat}, {InternalServerErrorMessage(messageID, MessageAcknowledgment), CoapCodeInternalServerError}, {NotImplementedMessage(messageID, MessageAcknowledgment), CoapCodeNotImplemented}, {BadGatewayMessage(messageID, MessageAcknowledgment), CoapCodeBadGateway}, {ServiceUnavailableMessage(messageID, MessageAcknowledgment), CoapCodeServiceUnavailable}, {GatewayTimeoutMessage(messageID, MessageAcknowledgment), CoapCodeGatewayTimeout}, {ProxyingNotSupportedMessage(messageID, MessageAcknowledgment), CoapCodeProxyingNotSupported}, } for _, td := range testData { assert.NotNil(t, td.msg) assert.Equal(t, td.code, td.msg.GetCode()) } } func NewBasicConfirmableMessage() *CoapMessage { msg := NewMessageOfType(MessageConfirmable, GenerateMessageID(), nil).(*CoapMessage) msg.Code = Get msg.Token = []byte("abcd1234") msg.SetStringPayload("xxxxx") return msg } ================================================ FILE: options.go ================================================ package canopus import ( "math" "strings" ) // Represents an Option for a CoAP Message type CoapOption struct { Code OptionCode Value interface{} } func (o *CoapOption) GetValue() interface{} { return o.Value } func (o *CoapOption) GetCode() OptionCode { return o.Code } func (o *CoapOption) Name() string { return "Name of option" } // Determines if an option is elective func (o *CoapOption) IsElective() bool { if (int(o.Code) % 2) != 0 { return false } return true } // Determines if an option is critical func (o *CoapOption) IsCritical() bool { if (int(o.Code) % 2) != 0 { return true } return false } // Returns the string value of an option func (o *CoapOption) StringValue() string { return o.Value.(string) } func (o *CoapOption) IntValue() int { return o.Value.(int) } // Instantiates a New Option func NewOption(optionNumber OptionCode, optionValue interface{}) *CoapOption { return &CoapOption{ Code: optionNumber, Value: optionValue, } } // Creates an array of options decomposed from a given path func NewPathOptions(path string) []Option { opts := []Option{} ps := strings.Split(path, "/") for _, p := range ps { if p != "" { opt := NewOption(OptionURIPath, p) opts = append(opts, opt) } } return opts } // Checks if an option is repeatable func IsRepeatableOption(opt Option) bool { switch opt.GetCode() { case OptionIfMatch, OptionEtag, OptionURIPort, OptionLocationPath, OptionURIPath, OptionURIQuery, OptionLocationQuery, OptionBlock2, OptionBlock1: return true default: return false } } // Checks if an option/option code is recognizable/valid func IsValidOption(opt Option) bool { switch opt.GetCode() { case OptionIfNoneMatch, OptionURIHost, OptionEtag, OptionIfMatch, OptionObserve, OptionURIPort, OptionLocationPath, OptionURIPath, OptionContentFormat, OptionMaxAge, OptionURIQuery, OptionAccept, OptionLocationQuery, OptionBlock2, OptionBlock1, OptionProxyURI, OptionProxyScheme, OptionSize1: return true default: return false } } // Determines if an option is elective func IsElectiveOption(opt Option) bool { i := int(opt.GetCode()) if (i & 1) == 1 { return false } return true } // Determines if an option is critical func IsCriticalOption(opt Option) bool { return !IsElectiveOption(opt) } func NewBlock1Option(bs BlockSizeType, more bool, seq uint32) *Block1Option { opt := &Block1Option{} opt.Code = OptionBlock1 val := seq val = val << 4 if more { val |= (1 << 3) } val |= (uint32(bs) << 0) opt.Value = val /* BLockSize val := o.Value.(uint) exp := val & 0x07 return math.Exp2(float64(exp + 4)) More val := o.Value.(uint) return ((val >> 3) & 0x01) == 1 */ return opt } func Block1OptionFromOption(opt Option) *Block1Option { blockOpt := &Block1Option{} blockOpt.Value = opt.GetValue() blockOpt.Code = opt.GetCode() return blockOpt } type Block1Option struct { CoapOption } func (o *Block1Option) Sequence() uint32 { val := o.GetValue().(uint32) return val >> 4 } func (o *Block1Option) Exponent() uint32 { val := o.GetValue().(uint32) return val & 0x07 } func (o *Block1Option) BlockSizeLength() uint32 { sz := uint32(o.Size()) + 4 return sz * sz } func (o *Block1Option) Size() BlockSizeType { val := o.GetValue().(uint32) exp := val & 0x07 return BlockSizeType(byte(math.Exp2(float64(exp + 4)))) } func (o *Block1Option) HasMore() bool { val := o.Value.(uint32) return ((val >> 3) & 0x01) == 1 } ================================================ FILE: plaintext.go ================================================ package canopus import "bytes" // Instantiates a new message payload of type string func NewPlainTextPayload(s string) MessagePayload { return &PlainTextPayload{ content: s, } } // Represents a message payload containing string value type PlainTextPayload struct { content string } func (p *PlainTextPayload) GetBytes() []byte { return bytes.NewBufferString(p.content).Bytes() } func (p *PlainTextPayload) Length() int { return len(p.content) } func (p *PlainTextPayload) String() string { return p.content } ================================================ FILE: proxy.go ================================================ package canopus import ( "io/ioutil" "log" "net" "net/http" "net/url" ) func NullProxyFilter(Message, net.Addr) bool { return true } // The default handler when proxying is disabled func NullProxyHandler(c CoapServer, msg Message, session Session) { SendMessage(ProxyingNotSupportedMessage(msg.GetMessageId(), MessageAcknowledgment), session) } func COAPProxyHandler(c CoapServer, msg Message, session Session) { proxyURI := msg.GetOption(OptionProxyURI).StringValue() parsedURL, err := url.Parse(proxyURI) if err != nil { log.Println("Error parsing proxy URI") SendMessage(BadGatewayMessage(msg.GetMessageId(), MessageAcknowledgment), session) return } clientConn, err := Dial(parsedURL.Host) msg.RemoveOptions(OptionProxyURI) req := NewRequestFromMessage(msg).(*CoapRequest) req.SetRequestURI(parsedURL.RequestURI()) response, err := clientConn.Send(req) if err != nil { SendMessage(BadGatewayMessage(msg.GetMessageId(), MessageAcknowledgment), session) clientConn.Close() return } _, err = SendMessage(response.GetMessage(), session) if err != nil { log.Println("Error occured responding to proxy request") clientConn.Close() return } clientConn.Close() } // Handles requests for proxying from CoAP to HTTP func HTTPProxyHandler(c CoapServer, msg Message, session Session) { proxyURI := msg.GetOption(OptionProxyURI).StringValue() requestMethod := msg.GetCode() client := &http.Client{} req, err := http.NewRequest(MethodString(CoapCode(msg.GetMethod())), proxyURI, nil) if err != nil { SendMessage(BadGatewayMessage(msg.GetMessageId(), MessageAcknowledgment), session) return } etag := msg.GetOption(OptionEtag) if etag != nil { req.Header.Add("ETag", etag.StringValue()) } // TODO: Set timeout handler, and on timeout return 5.04 resp, err := client.Do(req) if err != nil { SendMessage(BadGatewayMessage(msg.GetMessageId(), MessageAcknowledgment), session) return } defer resp.Body.Close() contents, _ := ioutil.ReadAll(resp.Body) modifiedMsg := msg.(*CoapMessage) modifiedMsg.SetPayload(NewBytesPayload(contents)) respMsg := NewRequestFromMessage(modifiedMsg) if requestMethod == Get { etag := resp.Header.Get("ETag") if etag != "" { msg.AddOption(OptionEtag, etag) } } // TODO: Check payload length against Size1 options if len(respMsg.GetMessage().GetPayload().String()) > MaxPacketSize { SendMessage(BadGatewayMessage(msg.GetMessageId(), MessageAcknowledgment), session) return } _, err = SendMessage(respMsg.GetMessage(), session) if err != nil { println(err.Error()) } } // Handles requests for proxying from HTTP to CoAP func HTTPCOAPProxyHandler(msg *Message, conn *net.UDPConn, addr net.Addr) { log.Println("HttpCoapProxyHandler Proxy Handler") } ================================================ FILE: request.go ================================================ package canopus import ( "strconv" "strings" ) // Creates a New Request Instance func NewRequest(messageType uint8, messageMethod CoapCode) Request { return NewRequestWithMessageId(messageType, messageMethod, GenerateMessageID()) } func NewRequestWithMessageId(messageType uint8, messageMethod CoapCode, messageID uint16) Request { msg := NewMessage(messageType, messageMethod, messageID) return &CoapRequest{ msg: msg, } } func NewConfirmableGetRequest() Request { return &CoapRequest{ msg: NewMessage(MessageConfirmable, Get, GenerateMessageID()), } } func NewConfirmablePostRequest() Request { return &CoapRequest{ msg: NewMessage(MessageConfirmable, Post, GenerateMessageID()), } } func NewConfirmablePutRequest() Request { return &CoapRequest{ msg: NewMessage(MessageConfirmable, Put, GenerateMessageID()), } } func NewConfirmableDeleteRequest() Request { return &CoapRequest{ msg: NewMessage(MessageConfirmable, Delete, GenerateMessageID()), } } // Creates a new request messages from a CoAP Message func NewRequestFromMessage(msg Message) Request { return &CoapRequest{ msg: msg, } } func NewClientRequestFromMessage(msg Message, attrs map[string]string, session Session) Request { return &CoapRequest{ msg: msg, attrs: attrs, session: session, } } // Wraps a CoAP Message as a Request // Provides various methods which proxies the Message object methods type CoapRequest struct { msg Message attrs map[string]string session Session server *CoapServer } func (c *CoapRequest) SetProxyURI(uri string) { c.msg.AddOption(OptionProxyURI, uri) } func (c *CoapRequest) SetMediaType(mt MediaType) { c.msg.AddOption(OptionContentFormat, mt) } func (c *CoapRequest) GetSession() Session { return c.session } func (c *CoapRequest) GetAttributes() map[string]string { return c.attrs } func (c *CoapRequest) GetAttribute(o string) string { return c.attrs[o] } func (c *CoapRequest) GetAttributeAsInt(o string) int { attr := c.GetAttribute(o) i, _ := strconv.Atoi(attr) return i } func (c *CoapRequest) GetMessage() Message { return c.msg } func (c *CoapRequest) SetStringPayload(s string) { c.msg.(*CoapMessage).SetPayload(NewPlainTextPayload(s)) } func (c *CoapRequest) SetPayload(b []byte) { c.msg.(*CoapMessage).SetPayload(NewBytesPayload(b)) } func (c *CoapRequest) SetRequestURI(uri string) { c.msg.AddOptions(NewPathOptions(uri)) } func (c *CoapRequest) SetConfirmable(con bool) { if con { c.msg.(*CoapMessage).SetMessageType(MessageConfirmable) } else { c.msg.(*CoapMessage).SetMessageType(MessageNonConfirmable) } } func (c *CoapRequest) SetToken(t string) { c.msg.(*CoapMessage).SetToken([]byte(t)) } func (c *CoapRequest) GetURIQuery(q string) string { qs := c.GetMessage().GetOptionsAsString(OptionURIQuery) for _, o := range qs { ps := strings.Split(o, "=") if len(ps) == 2 { if ps[0] == q { return ps[1] } } } return "" } func (c *CoapRequest) SetURIQuery(k string, v string) { c.GetMessage().AddOption(OptionURIQuery, k+"="+v) } ================================================ FILE: request_test.go ================================================ package canopus import ( "testing" "github.com/stretchr/testify/assert" ) func TestRequest(t *testing.T) { var req Request assert.NotNil(t, NewRequest(MessageConfirmable, Get, 12345)) msg := NewMessage(MessageConfirmable, Get, 12345) req = NewRequestFromMessage(msg) assert.NotNil(t, req) assert.Equal(t, Get, req.GetMessage().GetCode()) // &net.UDPConn{}, &net.UDPAddr{} assert.NotNil(t, NewClientRequestFromMessage(msg, make(map[string]string), nil)) req = NewRequest(MessageConfirmable, Get, 12345) assert.Equal(t, uint8(0), req.GetMessage().GetMessageType()) req.SetConfirmable(false) assert.Equal(t, uint8(1), req.GetMessage().GetMessageType()) } ================================================ FILE: response.go ================================================ package canopus import ( "strings" ) func NoResponse() Response { return NilResponse{} } type NilResponse struct { } func (c NilResponse) GetMessage() Message { return nil } func (c NilResponse) GetError() error { return nil } func (c NilResponse) GetPayload() []byte { return nil } func (c NilResponse) GetURIQuery(q string) string { return "" } // Creates a new Response object with a Message object and any error messages func NewResponse(msg Message, err error) Response { resp := &DefaultResponse{ msg: msg, err: err, } return resp } // Creates a new response object with a Message object func NewResponseWithMessage(msg Message) Response { resp := &DefaultResponse{ msg: msg, } return resp } type DefaultResponse struct { msg Message err error } func (c *DefaultResponse) GetMessage() Message { return c.msg } func (c *DefaultResponse) GetError() error { return c.err } func (c *DefaultResponse) GetPayload() []byte { return c.GetMessage().GetPayload().GetBytes() } func (c *DefaultResponse) GetURIQuery(q string) string { qs := c.GetMessage().GetOptionsAsString(OptionURIQuery) for _, o := range qs { ps := strings.Split(o, "=") if len(ps) == 2 { if ps[0] == q { return ps[1] } } } return "" } ================================================ FILE: response_test.go ================================================ package canopus import ( "testing" "github.com/stretchr/testify/assert" ) func TestResponse(t *testing.T) { msg := NewEmptyMessage(12345) msg.SetStringPayload("hello canopus") assert.NotNil(t, NewResponseWithMessage(msg)) response := NewResponse(msg, ErrUnknownCriticalOption) assert.NotNil(t, response) assert.Equal(t, uint16(12345), response.GetMessage().GetMessageId()) assert.Equal(t, ErrUnknownCriticalOption, response.GetError()) } ================================================ FILE: routes.go ================================================ package canopus import ( "fmt" "regexp" ) // CreateNewRoute creates a new Route object func CreateNewRegExRoute(path string, method string, fn RouteHandler) Route { var re *regexp.Regexp regexpString := path // Dots re = regexp.MustCompile(`([^\\])\.`) regexpString = re.ReplaceAllStringFunc(regexpString, func(m string) string { return fmt.Sprintf(`%s\.`, string(m[0])) }) // Wildcard names re = regexp.MustCompile(`:[^/#?()\.\\]+\*`) regexpString = re.ReplaceAllStringFunc(regexpString, func(m string) string { return fmt.Sprintf("(?P<%s>.+)", m[1:len(m)-1]) }) re = regexp.MustCompile(`:[^/#?()\.\\]+`) regexpString = re.ReplaceAllStringFunc(regexpString, func(m string) string { return fmt.Sprintf(`(?P<%s>[^/#?]+)`, m[1:len(m)]) }) s := fmt.Sprintf(`\A%s\z`, regexpString) return &RegExRoute{ AutoAck: false, Path: path, Method: method, Handler: fn, RegEx: regexp.MustCompile(s), } } // Route represents a CoAP Route/Resource type RegExRoute struct { Path string Method string Handler RouteHandler RegEx *regexp.Regexp AutoAck bool MediaTypes []MediaType } func (r *RegExRoute) Matches(path string) (bool, map[string]string) { re := r.RegEx matches := re.FindAllStringSubmatch(path, -1) attrs := make(map[string]string) if len(matches) > 0 { subExp := re.SubexpNames() for idx, exp := range subExp { attrs[exp] = matches[0][idx] } return true, attrs } return false, attrs } func (r *RegExRoute) GetMethod() string { return r.Method } func (r *RegExRoute) GetMediaTypes() []MediaType { return r.MediaTypes } func (r *RegExRoute) GetConfiguredPath() string { return r.Path } func (r *RegExRoute) AutoAcknowledge() bool { return r.AutoAck } func (r *RegExRoute) Handle(req Request) Response { return r.Handler(req) } // MatchingRoute checks if a given path matches any defined routes/resources func MatchingRoute(path string, method string, cf interface{}, routes []Route) (Route, map[string]string, error) { for _, route := range routes { if method == route.GetMethod() { match, attrs := route.Matches(path) if match { if len(route.GetMediaTypes()) > 0 { if cf == nil { return route, attrs, ErrUnsupportedContentFormat } foundMediaType := false for _, o := range route.GetMediaTypes() { if uint32(o) == cf { foundMediaType = true break } } if !foundMediaType { return route, attrs, ErrUnsupportedContentFormat } } return route, attrs, nil } } } return nil, nil, ErrNoMatchingRoute } ================================================ FILE: routes_test.go ================================================ package canopus import ( "testing" "github.com/stretchr/testify/assert" ) func TestRoutes(t *testing.T) { var route Route var matches bool route = CreateNewRegExRoute("/", "GET", nil) matches, _ = route.Matches("/") assert.True(t, matches) route = CreateNewRegExRoute("/test", "GET", nil) matches, _ = route.Matches("/") assert.False(t, matches) matches, _ = route.Matches("/test") assert.True(t, matches) route = CreateNewRegExRoute("/test/:var", "GET", nil) matches, _ = route.Matches("/test/abc") assert.True(t, matches) matches, _ = route.Matches("/test/abc/def") assert.False(t, matches) route = CreateNewRegExRoute("/test/:var/foo", "GET", nil) matches, _ = route.Matches("/test/abc/foo") assert.True(t, matches) matches, _ = route.Matches("/test/abc") assert.False(t, matches) matches, _ = route.Matches("/test/abc/def") assert.False(t, matches) matches, _ = route.Matches("/test//foo") assert.False(t, matches) matches, _ = route.Matches("/test/foo") assert.False(t, matches) route = CreateNewRegExRoute("/test.abc/:var", "GET", nil) matches, _ = route.Matches("/test.abc/abc") assert.True(t, matches) matches, _ = route.Matches("/test.abc/abc/def") assert.False(t, matches) } ================================================ FILE: server.go ================================================ package canopus import ( "bytes" "crypto/rand" "log" "net" "strconv" "strings" "time" ) var DTLS_SERVER_SESSIONS = make(map[int32]*DTLSServerSession) var NEXT_SESSION_ID int32 = 0 var DTLS_CLIENT_CONNECTIONS = make(map[int32]*DTLSConnection) type ServerConfiguration struct { EnableResourceDiscovery bool } func NewServer() CoapServer { return createServer() } func createServer() CoapServer { return &DefaultCoapServer{ events: NewEvents(), observations: make(map[string][]*Observation), fnHandleCOAPProxy: NullProxyHandler, fnHandleHTTPProxy: NullProxyHandler, fnProxyFilter: NullProxyFilter, stopChannel: make(chan int), coapResponseChannelsMap: make(map[uint16]chan *CoapResponseChannel), messageIds: make(map[uint16]time.Time), incomingBlockMessages: make(map[string]Message), outgoingBlockMessages: make(map[string]Message), sessions: make(map[string]Session), createdSession: make(chan Session), } } type DefaultCoapServer struct { messageIds map[uint16]time.Time incomingBlockMessages map[string]Message outgoingBlockMessages map[string]Message routes []Route events Events observations map[string][]*Observation fnHandleHTTPProxy ProxyHandler fnHandleCOAPProxy ProxyHandler fnProxyFilter ProxyFilter stopChannel chan int coapResponseChannelsMap map[uint16]chan *CoapResponseChannel sessions map[string]Session createdSession chan Session serverConfig *ServerConfiguration cookieSecret []byte fnPskHandler func(id string) []byte } func (s *DefaultCoapServer) DeleteSession(ssn Session) { s.closeSession(ssn) } func (s *DefaultCoapServer) HandlePSK(fn func(id string) []byte) { s.fnPskHandler = fn } func (s *DefaultCoapServer) handleRequest(msg Message, session Session) { if msg.GetMessageType() != MessageReset { // Unsupported Method if msg.GetCode() != Get && msg.GetCode() != Post && msg.GetCode() != Put && msg.GetCode() != Delete { s.handleReqUnsupportedMethodRequest(msg, session) return } // Proxy if IsProxyRequest(msg) { s.handleReqProxyRequest(msg, session) } else { route, attrs, err := MatchingRoute(msg.GetURIPath(), MethodString(msg.GetCode()), msg.GetOptions(OptionContentFormat), s.GetRoutes()) if err != nil { s.GetEvents().Error(err) if err == ErrNoMatchingRoute { s.handleReqNoMatchingRoute(msg, session) return } if err == ErrNoMatchingMethod { s.handleReqNoMatchingMethod(msg, session) return } if err == ErrUnsupportedContentFormat { s.handleReqUnsupportedContentFormat(msg, session) return } log.Println("Error occured parsing inbound message") return } // Duplicate Message ID Check if s.isDuplicateMessage(msg) { PrintMessage(msg) if msg.GetMessageType() == MessageConfirmable { log.Println("Duplicate Message ID ", msg.GetMessageId()) s.handleReqDuplicateMessageID(msg, session) } return } s.updateMessageTS(msg) // Auto acknowledge // TODO: Necessary? if msg.GetMessageType() == MessageConfirmable && route.AutoAcknowledge() { s.handleRequestAcknowledge(msg, session) } req := NewClientRequestFromMessage(msg, attrs, session) if msg.GetMessageType() == MessageConfirmable { // Observation Request obsOpt := msg.GetOption(OptionObserve) if obsOpt != nil { s.handleReqObserve(req, msg, session) } } opt := req.GetMessage().GetOption(OptionBlock1) if opt != nil { blockOpt := Block1OptionFromOption(opt) // 0000 1 010 /* [NUM][M][SZX] 2 ^ (2 + 4) 2 ^ 6 = 32 Size = 2 ^ (SZX + 4) The value 7 for SZX (which would indicate a block size of 2048) is reserved, i.e. MUST NOT be sent and MUST lead to a 4.00 Bad Request response code upon reception in a request. */ if blockOpt.Value != nil { if blockOpt.Code == OptionBlock1 { exp := blockOpt.Exponent() if exp == 7 { s.handleReqBadRequest(msg, session) return } // szx := blockOpt.Size() hasMore := blockOpt.HasMore() seqNum := blockOpt.Sequence() // fmt.Println("Out Values == ", blockOpt.Value, exp, szx, 2, hasMore, seqNum) s.GetEvents().BlockMessage(msg, true) s.updateBlockMessageFragment(session.GetAddress().String(), msg, seqNum) if hasMore { s.handleReqContinue(msg, session) // Auto Respond to client } else { // TODO: Check if message is too large msg = NewMessage(msg.GetMessageType(), msg.GetCode(), msg.GetMessageId()) msg.SetPayload(s.flushBlockMessagePayload(session.GetAddress().String())) req = NewClientRequestFromMessage(msg, attrs, session) } } else if blockOpt.Code == OptionBlock2 { } else { // TOOO: Invalid Block option Code } } } resp := route.Handle(req) _, nilresponse := resp.(NilResponse) if !nilresponse { respMsg := resp.GetMessage().(*CoapMessage) respMsg.SetToken(req.GetMessage().GetToken()) // TODO: Validate Message before sending (e.g missing messageId) err := ValidateMessage(respMsg) if err == nil { s.GetEvents().Message(respMsg, false) SendMessage(respMsg, session) } } } } } func (s *DefaultCoapServer) handleReqObserve(req Request, msg Message, session Session) { // TODO: if server doesn't allow observing, return error addr := session.GetAddress() // TODO: Check if observation has been registered, if yes, remove it (observation == cancel) resource := msg.GetURIPath() if s.HasObservation(resource, addr) { // Remove observation of client s.RemoveObservation(resource, addr) // Observe Cancel Request & Fire OnObserveCancel Event s.GetEvents().ObserveCancelled(resource, msg) } else { // Register observation of client s.AddObservation(msg.GetURIPath(), string(msg.GetToken()), session) // Observe Request & Fire OnObserve Event s.GetEvents().Observe(resource, msg) } req.GetMessage().AddOption(OptionObserve, 1) } func (s *DefaultCoapServer) handleResponse(msg Message, session Session) { defer s.closeSession(session) if msg.GetOption(OptionObserve) != nil { s.handleAcknowledgeObserveRequest(msg) return } ch := GetResponseChannel(s, msg.GetMessageId()) if ch != nil { resp := &CoapResponseChannel{ Response: NewResponse(msg, nil), } ch <- resp DeleteResponseChannel(s, msg.GetMessageId()) } } func (s *DefaultCoapServer) GetEvents() Events { return s.events } func (s *DefaultCoapServer) addDiscoveryRoute() { var discoveryRoute RouteHandler = func(req Request) Response { msg := req.GetMessage() var buf bytes.Buffer for _, r := range s.routes { if r.GetConfiguredPath() != ".well-known/core" { buf.WriteString("") // Media Types lenMt := len(r.GetMediaTypes()) if lenMt > 0 { buf.WriteString(";ct=") for idx, mt := range r.GetMediaTypes() { buf.WriteString(strconv.Itoa(int(mt))) if idx+1 < lenMt { buf.WriteString(" ") } } } buf.WriteString(",") } } ack := ContentMessage(msg.GetMessageId(), MessageAcknowledgment) ack.SetToken(msg.GetToken()) ack.SetPayload(NewPlainTextPayload(buf.String())) ack.AddOption(OptionContentFormat, MediaTypeApplicationLinkFormat) resp := NewResponseWithMessage(ack) return resp } s.NewRoute("/.well-known/core", Get, discoveryRoute) } func (s *DefaultCoapServer) ListenAndServeDTLS(addr string) { s.addDiscoveryRoute() conn := s.createConn(addr) ctx, err := NewServerDtlsContext() if err != nil { panic("Unable to create SSL Context:" + err.Error()) } if conn == nil { log.Fatal("An error occured starting up CoAPS Server") } else { secret := make([]byte, 32) if n, err := rand.Read(secret); n != 32 || err != nil { panic(err) } s.cookieSecret = secret log.Println("Started CoAPS Server ", conn.LocalAddr()) go s.handleIncomingDTLSData(conn, ctx) go s.events.Started(s) go s.handleMessageIDPurge() } } func (s *DefaultCoapServer) ListenAndServe(addr string) { s.addDiscoveryRoute() conn := s.createConn(addr) if conn == nil { log.Fatal("An error occured starting up CoAP Server") } else { log.Println("Started CoAP Server ", conn.LocalAddr()) go s.handleIncomingData(conn) go s.events.Started(s) go s.handleMessageIDPurge() } } func (s *DefaultCoapServer) createConn(addr string) ServerConnection { localHost := addr if !strings.Contains(localHost, ":") { localHost = ":" + localHost } localAddr, err := net.ResolveUDPAddr("udp6", localHost) if err != nil { panic(err.Error()) } conn, err := net.ListenUDP(UDP, localAddr) if err != nil { panic(err.Error()) } return &UDPServerConnection{ conn: conn, } } func (s *DefaultCoapServer) handleIncomingDTLSData(conn ServerConnection, ctx *ServerDtlsContext) { readBuf := make([]byte, MaxPacketSize) go func() { for { select { case <-s.stopChannel: return default: // continue } len, addr, err := conn.ReadFrom(readBuf) if err == nil { msgBuf := make([]byte, len) copy(msgBuf, readBuf[:len]) ssn := s.sessions[addr.String()] if ssn == nil { ssn = &DTLSServerSession{ UDPServerSession: UDPServerSession{ addr: addr, conn: conn, server: s, buf: []byte{}, rcvd: make(chan []byte, 1), }, } err := newSslSession(ssn.(*DTLSServerSession), ctx, s.fnPskHandler) if err != nil { panic(err.Error()) } s.sessions[addr.String()] = ssn s.createdSession <- ssn } ssn.(*DTLSServerSession).rcvd <- msgBuf } else { logMsg("Error occured reading UDP", err) } } }() go func() { for { ssn := <-s.createdSession go s.handleSession(ssn) } }() } func (s *DefaultCoapServer) handleIncomingData(conn ServerConnection) { readBuf := make([]byte, MaxPacketSize) go func() { for { select { case <-s.stopChannel: return default: // continue } len, addr, err := conn.ReadFrom(readBuf) if err == nil { msgBuf := make([]byte, len) copy(msgBuf, readBuf[:len]) ssn := s.sessions[addr.String()] if ssn == nil { ssn = &UDPServerSession{ addr: addr, conn: conn, server: s, rcvd: make(chan []byte), } if err != nil { panic(err.Error()) } s.sessions[addr.String()] = ssn } go func() { ssn.(*UDPServerSession).rcvd <- msgBuf }() go s.handleSession(ssn) } else { logMsg("Error occured reading UDP", err) } } }() } func (s *DefaultCoapServer) GetSession(addr string) Session { return s.sessions[addr] } func (s *DefaultCoapServer) Stop() { close(s.stopChannel) } func (s *DefaultCoapServer) updateBlockMessageFragment(client string, msg Message, seq uint32) { msgs := s.incomingBlockMessages[client] if msgs == nil { msgs = &CoapBlockMessage{ Sequence: 0, MessageBuf: []byte{}, } } blockMsgs := msgs.(*CoapBlockMessage) blockMsgs.Sequence = seq blockMsgs.MessageBuf = append(blockMsgs.MessageBuf, msg.GetPayload().GetBytes()...) s.incomingBlockMessages[client] = msgs } func (s *DefaultCoapServer) flushBlockMessagePayload(origin string) MessagePayload { msgs := s.incomingBlockMessages[origin] blockMsg := msgs.(*CoapBlockMessage) payload := blockMsg.MessageBuf return NewBytesPayload(payload) } func (s *DefaultCoapServer) handleMessageIDPurge() { // Routine for clearing up message IDs which has expired ticker := time.NewTicker(MessageIDPurgeDuration * time.Second) go func() { for { select { case <-ticker.C: for k, v := range s.messageIds { elapsed := time.Since(v) if elapsed > MessageIDPurgeDuration { delete(s.messageIds, k) } } } } }() } func (s *DefaultCoapServer) SetProxyFilter(fn ProxyFilter) { s.fnProxyFilter = fn } func (s *DefaultCoapServer) GetCookieSecret() []byte { return s.cookieSecret } func (s *DefaultCoapServer) handleSession(session Session) { msgBuf := make([]byte, 1500) n, _ := session.Read(msgBuf) msg, err := BytesToMessage(msgBuf[:n]) if err != nil { logMsg(err.Error()) s.handleReqBadRequest(msg, session) } if msg.GetMessageType() == MessageAcknowledgment { s.handleResponse(msg, session) } else { s.handleRequest(msg, session) } } func (s *DefaultCoapServer) closeSession(ssn Session) { delete(s.sessions, ssn.GetAddress().String()) } func (s *DefaultCoapServer) Get(path string, fn RouteHandler) Route { return s.add(MethodGet, path, fn) } func (s *DefaultCoapServer) Delete(path string, fn RouteHandler) Route { return s.add(MethodDelete, path, fn) } func (s *DefaultCoapServer) Put(path string, fn RouteHandler) Route { return s.add(MethodPut, path, fn) } func (s *DefaultCoapServer) Post(path string, fn RouteHandler) Route { return s.add(MethodPost, path, fn) } func (s *DefaultCoapServer) Options(path string, fn RouteHandler) Route { return s.add(MethodOptions, path, fn) } func (s *DefaultCoapServer) Patch(path string, fn RouteHandler) Route { return s.add(MethodPatch, path, fn) } func (s *DefaultCoapServer) add(method string, path string, fn RouteHandler) Route { route := CreateNewRegExRoute(path, method, fn) s.routes = append(s.routes, route) return route } func (s *DefaultCoapServer) NewRoute(path string, method CoapCode, fn RouteHandler) Route { route := CreateNewRegExRoute(path, MethodString(method), fn) s.routes = append(s.routes, route) return route } func (s *DefaultCoapServer) storeNewOutgoingBlockMessage(client string, payload []byte) { bm := NewBlockMessage().(*CoapBlockMessage) bm.MessageBuf = payload s.outgoingBlockMessages[client] = bm } func (s *DefaultCoapServer) NotifyChange(resource, value string, confirm bool) { t := s.observations[resource] if t != nil { var req Request if confirm { req = NewRequest(MessageConfirmable, CoapCodeContent) } else { req = NewRequest(MessageAcknowledgment, CoapCodeContent) } for _, r := range t { req.SetToken(r.Token) req.SetStringPayload(value) req.SetRequestURI(r.Resource) r.NotifyCount++ req.GetMessage().AddOption(OptionObserve, r.NotifyCount) go SendMessage(req.GetMessage(), r.Session) } } } func (s *DefaultCoapServer) AddObservation(resource, token string, session Session) { s.observations[resource] = append(s.observations[resource], NewObservation(session, token, resource)) } func (s *DefaultCoapServer) HasObservation(resource string, addr net.Addr) bool { obs := s.observations[resource] if obs == nil { return false } for _, o := range obs { if o.Session.GetAddress().String() == addr.String() { return true } } return false } func (s *DefaultCoapServer) RemoveObservation(resource string, addr net.Addr) { obs := s.observations[resource] if obs == nil { return } for idx, o := range obs { if o.Session.GetAddress().String() == addr.String() { s.observations[resource] = append(obs[:idx], obs[idx+1:]...) return } } } func (s *DefaultCoapServer) OnNotify(fn FnEventNotify) { s.events.OnNotify(fn) } func (s *DefaultCoapServer) OnStart(fn FnEventStart) { s.events.OnStart(fn) } func (s *DefaultCoapServer) OnClose(fn FnEventClose) { s.events.OnClose(fn) } func (s *DefaultCoapServer) OnDiscover(fn FnEventDiscover) { s.events.OnDiscover(fn) } func (s *DefaultCoapServer) OnError(fn FnEventError) { s.events.OnError(fn) } func (s *DefaultCoapServer) OnObserve(fn FnEventObserve) { s.events.OnObserve(fn) } func (s *DefaultCoapServer) OnObserveCancel(fn FnEventObserveCancel) { s.events.OnObserveCancel(fn) } func (s *DefaultCoapServer) OnMessage(fn FnEventMessage) { s.events.OnMessage(fn) } func (s *DefaultCoapServer) OnBlockMessage(fn FnEventBlockMessage) { s.events.OnBlockMessage(fn) } func (s *DefaultCoapServer) ProxyOverHttp(enabled bool) { if enabled { s.fnHandleHTTPProxy = HTTPProxyHandler } else { s.fnHandleHTTPProxy = NullProxyHandler } } func (s *DefaultCoapServer) ProxyOverCoap(enabled bool) { if enabled { s.fnHandleCOAPProxy = COAPProxyHandler } else { s.fnHandleCOAPProxy = NullProxyHandler } } func (s *DefaultCoapServer) AllowProxyForwarding(msg Message, addr net.Addr) bool { return s.fnProxyFilter(msg, addr) } func (s *DefaultCoapServer) ForwardCoap(msg Message, session Session) { s.fnHandleCOAPProxy(s, msg, session) } func (s *DefaultCoapServer) ForwardHTTP(msg Message, session Session) { s.fnHandleHTTPProxy(s, msg, session) } func (s *DefaultCoapServer) GetRoutes() []Route { return s.routes } func (s *DefaultCoapServer) isDuplicateMessage(msg Message) bool { _, ok := s.messageIds[msg.GetMessageId()] return ok } func (s *DefaultCoapServer) updateMessageTS(msg Message) { s.messageIds[msg.GetMessageId()] = time.Now() } func (s *DefaultCoapServer) handleReqUnknownCriticalOption(msg Message, session Session) { if msg.GetMessageType() == MessageConfirmable { SendMessage(BadOptionMessage(msg.GetMessageId(), MessageAcknowledgment), session) } return } func (s *DefaultCoapServer) handleReqBadRequest(msg Message, session Session) { if msg.GetMessageType() == MessageConfirmable { SendMessage(BadRequestMessage(msg.GetMessageId(), msg.GetMessageType()), session) } return } func (s *DefaultCoapServer) handleReqContinue(msg Message, session Session) { if msg.GetMessageType() == MessageConfirmable { SendMessage(ContinueMessage(msg.GetMessageId(), msg.GetMessageType()), session) } return } func (s *DefaultCoapServer) handleReqUnsupportedMethodRequest(msg Message, session Session) { ret := NotImplementedMessage(msg.GetMessageId(), MessageAcknowledgment) ret.CloneOptions(msg, OptionURIPath, OptionContentFormat) // c.GetEvents().Message(ret, false) SendMessage(ret, session) } func (s *DefaultCoapServer) handleReqProxyRequest(msg Message, session Session) { if !s.AllowProxyForwarding(msg, session.GetAddress()) { SendMessage(ForbiddenMessage(msg.GetMessageId(), MessageAcknowledgment), session) } proxyURI := msg.GetOption(OptionProxyURI).StringValue() if IsCoapURI(proxyURI) { s.ForwardCoap(msg, session) } else if IsHTTPURI(proxyURI) { s.ForwardHTTP(msg, session) } else { // } } func (s *DefaultCoapServer) handleReqNoMatchingRoute(msg Message, session Session) { ret := NotFoundMessage(msg.GetMessageId(), MessageAcknowledgment, msg.GetToken()) ret.CloneOptions(msg, OptionURIPath, OptionContentFormat) SendMessage(ret, session) } func (s *DefaultCoapServer) handleReqNoMatchingMethod(msg Message, session Session) { ret := MethodNotAllowedMessage(msg.GetMessageId(), MessageAcknowledgment) ret.CloneOptions(msg, OptionURIPath, OptionContentFormat) SendMessage(ret, session) } func (s *DefaultCoapServer) handleReqUnsupportedContentFormat(msg Message, session Session) { ret := UnsupportedContentFormatMessage(msg.GetMessageId(), MessageAcknowledgment) ret.CloneOptions(msg, OptionURIPath, OptionContentFormat) // s.GetEvents().Message(ret, false) SendMessage(ret, session) } func (s *DefaultCoapServer) handleReqDuplicateMessageID(msg Message, session Session) { ret := EmptyMessage(msg.GetMessageId(), MessageReset) ret.CloneOptions(msg, OptionURIPath, OptionContentFormat) SendMessage(ret, session) } func (s *DefaultCoapServer) handleRequestAcknowledge(msg Message, session Session) { ack := NewMessageOfType(MessageAcknowledgment, msg.GetMessageId(), nil) SendMessage(ack, session) } func (s *DefaultCoapServer) handleAcknowledgeObserveRequest(msg Message) { s.GetEvents().Notify(msg.GetURIPath(), msg.GetPayload(), msg) } func (s *DefaultCoapServer) handleAcknowledgeObserveRequestGetSession(addr string) Session { return s.sessions[addr] } func NewResponseChannel() (ch chan *CoapResponseChannel) { ch = make(chan *CoapResponseChannel) return } func AddResponseChannel(c CoapServer, msgId uint16, ch chan *CoapResponseChannel) { s := c.(*DefaultCoapServer) s.coapResponseChannelsMap[msgId] = ch } func DeleteResponseChannel(c CoapServer, msgId uint16) { s := c.(*DefaultCoapServer) delete(s.coapResponseChannelsMap, msgId) } func GetResponseChannel(c CoapServer, msgId uint16) (ch chan *CoapResponseChannel) { s := c.(*DefaultCoapServer) ch = s.coapResponseChannelsMap[msgId] return } func NewObservation(session Session, token string, resource string) *Observation { return &Observation{ Session: session, Token: token, Resource: resource, NotifyCount: 0, } } type Observation struct { Session Session Token string Resource string NotifyCount int } func _doSendMessage(msg Message, session Session, ch chan *CoapResponseChannel) { resp := &CoapResponseChannel{} b, err := MessageToBytes(msg) if err != nil { resp.Error = err ch <- resp } _, err = session.Write(b) if err != nil { resp.Error = err ch <- resp } if msg.GetMessageType() == MessageNonConfirmable { resp.Response = NewResponse(NewEmptyMessage(msg.GetMessageId()), nil) ch <- resp } AddResponseChannel(session.GetServer(), msg.GetMessageId(), ch) } func SendMessage(msg Message, session Session) (Response, error) { if session.GetConnection() == nil { return nil, ErrNilConn } if msg == nil { return nil, ErrNilMessage } if session.GetAddress() == nil { return nil, ErrNilAddr } ch := NewResponseChannel() go _doSendMessage(msg, session, ch) session.GetServer().DeleteSession(session) respCh := <-ch return respCh.Response, respCh.Error } type CoapResponseChannel struct { Response Response Error error } ================================================ FILE: server_test.go ================================================ package canopus import "testing" // TODO Redo this entire test suite func TestServerInstantiate(t *testing.T) { //var s CoapServer //s = NewServer() //assert.NotNil(t, s) //assert.Equal(t, 1000, s.GetLocalAddress().Port) //assert.Equal(t, "udp", s.GetLocalAddress().Network()) // //s = NewLocalServer("TestServer") //assert.NotNil(t, s) //assert.Equal(t, 5683, s.GetLocalAddress().Port) //assert.Equal(t, "udp", s.GetLocalAddress().Network()) } //func TestDiscoveryService(t *testing.T) { // server := NewCoapServer(":5684") // assert.NotNil(t, server) // assert.Equal(t, 5684, server.localAddr.Port) // assert.Equal(t, "udp", server.localAddr.Network()) // // go server.Start() // client := NewCoapClient() // client.OnStart(func(server *CoapServer) { // tok := "abc123" // client.Dial("localhost:5684") // // req := NewRequest(TYPE_CONFIRMABLE, GET, GenerateMessageId()) // req.SetToken(tok) // req.SetRequestURI(".well-known/core") // resp, err := client.Send(req) // assert.Nil(t, err) // // assert.Equal(t, tok, resp.GetMessage().GetTokenString()) // client.Stop() // }) // client.Start() //} //func TestClientServerRequestResponse(t *testing.T) { // server := NewLocalServer() // // server.Get("/ep", func (req CoapRequest) CoapResponse { // msg := ContentMessage(req.GetMessage().MessageId, TYPE_ACKNOWLEDGEMENT) // msg.SetStringPayload("ACK GET") // res := NewResponse(msg, nil) // // return res // }) // // server.Post("/ep", func (req CoapRequest) CoapResponse { // msg := ContentMessage(req.GetMessage().MessageId, TYPE_ACKNOWLEDGEMENT) // msg.SetStringPayload("ACK POST") // res := NewResponse(msg, nil) // // return res // }) // // server.Put("/ep", func (req CoapRequest) CoapResponse { // msg := ContentMessage(req.GetMessage().MessageId, TYPE_ACKNOWLEDGEMENT) // msg.SetStringPayload("ACK PUT") // res := NewResponse(msg, nil) // // return res // }) // // server.Delete("/ep", func (req CoapRequest) CoapResponse { // msg := ContentMessage(req.GetMessage().MessageId, TYPE_ACKNOWLEDGEMENT) // msg.SetStringPayload("ACK DELETE") // res := NewResponse(msg, nil) // // return res // }) // // go server.Start() // // client := NewCoapClient() // // client.OnStart(func(server *CoapServer) { // client.Dial("localhost:5683") // token := "tok1234" // // var req CoapRequest // var resp CoapResponse // var err error // // // 404 Test // req = NewConfirmableGetRequest() // req.SetToken(token) // req.SetRequestURI("ep-404") // resp, err = client.Send(req) // assert.Equal(t, COAPCODE_404_NOT_FOUND, resp.GetMessage().Code) // // // GET // req = NewConfirmableGetRequest() // req.SetToken(token) // req.SetRequestURI("ep") // resp, err = client.Send(req) // // assert.Nil(t, err) // assert.Equal(t, "ACK GET", resp.GetMessage().Payload.String()) // assert.Equal(t, token, resp.GetMessage().GetTokenString()) // // // POST // req = NewConfirmablePostRequest() // req.SetToken(token) // req.SetRequestURI("ep") // resp, err = client.Send(req) // // assert.Nil(t, err) // assert.Equal(t, "ACK POST", resp.GetMessage().Payload.String()) // assert.Equal(t, token, resp.GetMessage().GetTokenString()) // // // PUT // req = NewConfirmablePutRequest() // req.SetToken(token) // req.SetRequestURI("ep") // resp, err = client.Send(req) // // assert.Nil(t, err) // assert.Equal(t, "ACK PUT", resp.GetMessage().Payload.String()) // assert.Equal(t, token, resp.GetMessage().GetTokenString()) // // // DELETE // req = NewConfirmableDeleteRequest() // req.SetToken(token) // req.SetRequestURI("ep") // resp, err = client.Send(req) // // assert.Nil(t, err) // assert.Equal(t, "ACK DELETE", resp.GetMessage().Payload.String()) // assert.Equal(t, token, resp.GetMessage().GetTokenString()) // // // Test default token set // req = NewConfirmableGetRequest() // req.SetRequestURI("ep") // resp, err = client.Send(req) // // assert.Nil(t, err) // assert.Equal(t, "ACK GET", resp.GetMessage().Payload.String()) // assert.NotEmpty(t, resp.GetMessage().GetTokenString()) // // client.Stop() // }) // client.Start() //} ================================================ FILE: serverconn.go ================================================ package canopus import ( "net" "time" ) type UDPServerConnection struct { conn net.PacketConn } func (uc *UDPServerConnection) ReadFrom(b []byte) (n int, addr net.Addr, err error) { return uc.conn.ReadFrom(b) } func (uc *UDPServerConnection) WriteTo(b []byte, addr net.Addr) (n int, err error) { return uc.conn.WriteTo(b, addr) } func (uc *UDPServerConnection) Close() error { return uc.conn.Close() } func (uc *UDPServerConnection) LocalAddr() net.Addr { return uc.conn.LocalAddr() } func (uc *UDPServerConnection) SetDeadline(t time.Time) error { return uc.conn.SetDeadline(t) } func (uc *UDPServerConnection) SetReadDeadline(t time.Time) error { return uc.conn.SetReadDeadline(t) } func (uc *UDPServerConnection) SetWriteDeadline(t time.Time) error { return uc.conn.SetWriteDeadline(t) } ================================================ FILE: session.go ================================================ package canopus import "net" type UDPServerSession struct { addr net.Addr conn ServerConnection server CoapServer rcvd chan []byte buf []byte } func (s *UDPServerSession) GetConnection() ServerConnection { return s.conn } func (s *UDPServerSession) GetAddress() net.Addr { return s.addr } func (s *UDPServerSession) WriteBuffer(b []byte) (n int) { l := len(b) s.buf = append(s.buf, b...) return l } func (s *UDPServerSession) Write(b []byte) (n int, err error) { n, err = s.conn.WriteTo(b, s.GetAddress()) return } func (s *UDPServerSession) Read(b []byte) (n int, err error) { data := <-s.rcvd copy(b, data) return len(data), nil } func (s *UDPServerSession) GetServer() CoapServer { return s.server } ================================================ FILE: test-coverage.sh ================================================ #!/bin/bash echo "mode: set" > acc.out fail=0 # Standard go tooling behavior is to ignore dirs with leading underscors for dir in $(find . -maxdepth 10 -not -path './.git*' -not -path '*/_*' -type d); do if ls $dir/*.go &> /dev/null; then go test -coverprofile=profile.out $dir || fail=1 if [ -f profile.out ] then cat profile.out | grep -v "mode: set" >> acc.out rm profile.out fi fi done # Failures have incomplete results, so don't send if [ -n "$COVERALLS" ] && [ "$fail" -eq 0 ] then goveralls -v -coverprofile=acc.out $COVERALLS fi rm -f acc.out exit $fail ================================================ FILE: types.go ================================================ package canopus type CoreAttributes []*CoreAttribute type CoreResource struct { Target string Attributes CoreAttributes } type CoreAttribute struct { Key string Value interface{} } // Adds an attribute (key/value) for a given core resource func (c *CoreResource) AddAttribute(key string, value interface{}) { c.Attributes = append(c.Attributes, NewCoreAttribute(key, value)) } // Gets an attribute for a core resource func (c *CoreResource) GetAttribute(key string) *CoreAttribute { for _, attr := range c.Attributes { if attr.Key == key { return attr } } return nil } ================================================ FILE: utilconn_test.go ================================================ package canopus import "testing" func TestSendMessages(t *testing.T) { //var conn Connection //var s CoapServer //_, err := SendMessageTo(s, nil, conn, nil) //assert.NotNil(t, err) //assert.Equal(t, ErrNilConn, err) // //conn = NewUDPConnection(nil) //SendMessageTo(s, nil, conn, nil) //_, err = SendMessageTo(s, nil, conn, nil) //assert.NotNil(t, err) //assert.Equal(t, ErrNilMessage, err) // //_, err = SendMessageTo(s, NewEmptyMessage(12345), conn, nil) //assert.NotNil(t, err) //assert.Equal(t, ErrNilAddr, err) // //addr := &net.UDPAddr{} //conn = NewMockCanopusUDPConnection(CoapCodeCreated, false, false) //msg := NewBasicConfirmableMessage() //_, err = SendMessageTo(s, msg, conn, addr) //assert.Nil(t, err) // //msg.MessageType = MessageNonConfirmable //_, err = SendMessageTo(s, msg, conn, addr) //assert.Nil(t, err) // //conn = NewMockCanopusUDPConnection(CoapCodeCreated, false, true) //msg.MessageType = MessageConfirmable //_, err = SendMessageTo(s, msg, conn, addr) //assert.NotNil(t, err) } ================================================ FILE: utildebug.go ================================================ package canopus // PrintOptions pretty prints out a given Message's options func PrintOptions(msg Message) { opts := msg.GetAllOptions() logMsg(" - - - OPTIONS - - - ") if len(opts) > 0 { for _, opts := range msg.GetAllOptions() { logMsg("Code/Number: ", opts.GetCode(), ", Name: ", OptionNumberToString(opts.GetCode()), ", Value: ", opts.GetValue()) } } else { logMsg("None") } } // PrintMessage pretty prints out a given Message func PrintMessage(msg Message) { logMsg("= = = = = = = = = = = = = = = = ") logMsg("Code: ", msg.GetCode()) logMsg("Code String: ", CoapCodeToString(msg.GetCode())) logMsg("MessageId: ", msg.GetMessageId()) logMsg("MessageType: ", msg.GetMessageType()) logMsg("Token: ", string(msg.GetToken())) logMsg("Token Length: ", msg.GetTokenLength()) logMsg("Payload: ", PayloadAsString(msg.GetPayload())) PrintOptions(msg) logMsg("= = = = = = = = = = = = = = = = ") } // OptionNumberToString returns the string representation of a given Option Code func OptionNumberToString(o OptionCode) string { switch o { case OptionIfMatch: return "If-Match" case OptionURIHost: return "Uri-Host" case OptionEtag: return "ETag" case OptionIfNoneMatch: return "If-None-Match" case OptionURIPort: return "Uri-Port" case OptionLocationPath: return "Location-Path" case OptionURIPath: return "Uri-Path" case OptionContentFormat: return "Content-Format" case OptionMaxAge: return "Max-Age" case OptionURIQuery: return "Uri-Query" case OptionAccept: return "Accept" case OptionLocationQuery: return "Location-Query" case OptionBlock2: return "Block2" case OptionBlock1: return "Block1" case OptionProxyURI: return "Proxy-Uri" case OptionProxyScheme: return "Proxy-Scheme" case OptionSize1: return "Size1" case OptionSize2: return "Size2" default: return "" } } ================================================ FILE: utils.go ================================================ package canopus import ( "fmt" "math/rand" "regexp" "strings" "time" ) // Returns the string value for a Message Payload func PayloadAsString(p MessagePayload) string { if p == nil { return "" } return p.String() } // GenerateMessageId generate a uint16 Message ID func GenerateMessageID() uint16 { MESSAGEID_MUTEX.Lock() if CurrentMessageID != 65535 { CurrentMessageID++ } else { CurrentMessageID = 1 } MESSAGEID_MUTEX.Unlock() return uint16(CurrentMessageID) } var genChars = []rune("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890") // GenerateToken generates a random token by a given length func GenerateToken(l int) string { rand.Seed(time.Now().UTC().UnixNano()) token := make([]rune, l) for i := range token { token[i] = genChars[rand.Intn(len(genChars))] } return string(token) } // CoreResourcesFromString Converts to CoRE Resources Object from a CoRE String func CoreResourcesFromString(str string) []*CoreResource { var re = regexp.MustCompile(`(<[^>]+>\s*(;\s*\w+\s*(=\s*(\w+|"([^"\\]*(\\.[^"\\]*)*)")\s*)?)*)`) var elemRe = regexp.MustCompile(`<[^>]*>`) var resources []*CoreResource m := re.FindAllString(str, -1) for _, match := range m { elemMatch := elemRe.FindString(match) target := elemMatch[1 : len(elemMatch)-1] resource := NewCoreResource() resource.Target = target if len(match) > len(elemMatch) { attrs := strings.Split(match[len(elemMatch)+1:], ";") for _, attr := range attrs { pair := strings.Split(attr, "=") resource.AddAttribute(pair[0], strings.Replace(pair[1], "\"", "", -1)) } } resources = append(resources, resource) } return resources } // CoapCodeToString returns the string representation of a CoapCode func CoapCodeToString(code CoapCode) string { switch code { case Get: return "GET" case Post: return "POST" case Put: return "PUT" case Delete: return "DELETE" case CoapCodeEmpty: return "0 Empty" case CoapCodeCreated: return "201 Created" case CoapCodeDeleted: return "202 Deleted" case CoapCodeValid: return "203 Valid" case CoapCodeChanged: return "204 Changed" case CoapCodeContent: return "205 Content" case CoapCodeBadRequest: return "400 Bad Request" case CoapCodeUnauthorized: return "401 Unauthorized" case CoapCodeBadOption: return "402 Bad Option" case CoapCodeForbidden: return "403 Forbidden" case CoapCodeNotFound: return "404 Not Found" case CoapCodeMethodNotAllowed: return "405 Method Not Allowed" case CoapCodeNotAcceptable: return "406 Not Acceptable" case CoapCodePreconditionFailed: return "412 Precondition Failed" case CoapCodeRequestEntityTooLarge: return "413 Request Entity Too Large" case CoapCodeUnsupportedContentFormat: return "415 Unsupported Content Format" case CoapCodeInternalServerError: return "500 Internal Server Error" case CoapCodeNotImplemented: return "501 Not Implemented" case CoapCodeBadGateway: return "502 Bad Gateway" case CoapCodeServiceUnavailable: return "503 Service Unavailable" case CoapCodeGatewayTimeout: return "504 Gateway Timeout" case CoapCodeProxyingNotSupported: return "505 Proxying Not Supported" default: return "Unknown" } } // ValidCoapMediaTypeCode Checks if a MediaType is of a valid code func ValidCoapMediaTypeCode(mt MediaType) bool { switch mt { case MediaTypeTextPlain, MediaTypeTextXML, MediaTypeTextCsv, MediaTypeTextHTML, MediaTypeImageGif, MediaTypeImageJpeg, MediaTypeImagePng, MediaTypeImageTiff, MediaTypeAudioRaw, MediaTypeVideoRaw, MediaTypeApplicationLinkFormat, MediaTypeApplicationXML, MediaTypeApplicationOctetStream, MediaTypeApplicationRdfXML, MediaTypeApplicationSoapXML, MediaTypeApplicationAtomXML, MediaTypeApplicationXmppXML, MediaTypeApplicationExi, MediaTypeApplicationFastInfoSet, MediaTypeApplicationSoapFastInfoSet, MediaTypeApplicationJSON, MediaTypeApplicationXObitBinary, MediaTypeTextPlainVndOmaLwm2m, MediaTypeTlvVndOmaLwm2m, MediaTypeJSONVndOmaLwm2m, MediaTypeOpaqueVndOmaLwm2m: return true } return false } func logMsg(a ...interface{}) (n int, err error) { return fmt.Println(a) } ================================================ FILE: utils_test.go ================================================ package canopus import ( "testing" "github.com/stretchr/testify/assert" ) func TestGenerateMessageId(t *testing.T) { var id, id2 uint16 id = GenerateMessageID() for i := 0; i < 100; i++ { id2 = id + 1 id = GenerateMessageID() assert.NotEqual(t, 65535, id) assert.Equal(t, id2, id) } CurrentMessageID = 65535 id = GenerateMessageID() assert.Equal(t, uint16(1), id) } func TestGenerateToken(t *testing.T) { assert.Equal(t, "", GenerateToken(0)) for i := 1; i < 10; i++ { tok := GenerateToken(i) assert.NotEqual(t, "", tok) assert.Equal(t, i, len(tok)) } } func TestCoreResourceUtil(t *testing.T) { var resources []*CoreResource resources = CoreResourcesFromString("") assert.Equal(t, 0, len(resources)) resources = CoreResourcesFromString(";ct=41;rt=\"temperature-c\";if=\"sensor\", ;ct=41;rt=\"light-lux\";if=\"sensor\"") assert.Equal(t, 2, len(resources)) resource1 := resources[0] assert.Equal(t, "/sensors/temp", resource1.Target) assert.Equal(t, 3, len(resource1.Attributes)) assert.Nil(t, resource1.GetAttribute("invalid_attr")) assert.NotNil(t, resource1.GetAttribute("ct")) assert.Equal(t, "ct", resource1.GetAttribute("ct").Key) assert.Equal(t, "41", resource1.GetAttribute("ct").Value) assert.NotNil(t, resource1.GetAttribute("rt")) assert.Equal(t, "rt", resource1.GetAttribute("rt").Key) assert.Equal(t, "temperature-c", resource1.GetAttribute("rt").Value) assert.NotNil(t, resource1.GetAttribute("if")) assert.Equal(t, "if", resource1.GetAttribute("if").Key) assert.Equal(t, "sensor", resource1.GetAttribute("if").Value) resource2 := resources[1] assert.Equal(t, "/sensors/light", resource2.Target) assert.Equal(t, 3, len(resource2.Attributes)) assert.NotNil(t, resource2.GetAttribute("ct")) assert.Equal(t, "ct", resource2.GetAttribute("ct").Key) assert.Equal(t, "41", resource2.GetAttribute("ct").Value) assert.NotNil(t, resource2.GetAttribute("rt")) assert.Equal(t, "rt", resource2.GetAttribute("rt").Key) assert.Equal(t, "light-lux", resource2.GetAttribute("rt").Value) assert.NotNil(t, resource2.GetAttribute("if")) assert.Equal(t, "if", resource2.GetAttribute("if").Key) assert.Equal(t, "sensor", resource2.GetAttribute("if").Value) } func TestCoapCodeToString(t *testing.T) { testData := []struct { coapCode CoapCode codeString string }{ {Get, "GET"}, {Post, "POST"}, {Put, "PUT"}, {Delete, "DELETE"}, {CoapCodeEmpty, "0 Empty"}, {CoapCodeCreated, "201 Created"}, {CoapCodeDeleted, "202 Deleted"}, {CoapCodeValid, "203 Valid"}, {CoapCodeChanged, "204 Changed"}, {CoapCodeContent, "205 Content"}, {CoapCodeBadRequest, "400 Bad Request"}, {CoapCodeUnauthorized, "401 Unauthorized"}, {CoapCodeBadOption, "402 Bad Option"}, {CoapCodeForbidden, "403 Forbidden"}, {CoapCodeNotFound, "404 Not Found"}, {CoapCodeMethodNotAllowed, "405 Method Not Allowed"}, {CoapCodeNotAcceptable, "406 Not Acceptable"}, {CoapCodePreconditionFailed, "412 Precondition Failed"}, {CoapCodeRequestEntityTooLarge, "413 Request Entity Too Large"}, {CoapCodeUnsupportedContentFormat, "415 Unsupported Content Format"}, {CoapCodeInternalServerError, "500 Internal Server Error"}, {CoapCodeNotImplemented, "501 Not Implemented"}, {CoapCodeBadGateway, "502 Bad Gateway"}, {CoapCodeServiceUnavailable, "503 Service Unavailable"}, {CoapCodeGatewayTimeout, "504 Gateway Timeout"}, {CoapCodeProxyingNotSupported, "505 Proxying Not Supported"}, {CoapCode(255), "Unknown"}, } for _, td := range testData { assert.Equal(t, td.codeString, CoapCodeToString(td.coapCode)) } } func TestRouteMatching(t *testing.T) { } func TestMediaTypeUtils(t *testing.T) { assert.True(t, ValidCoapMediaTypeCode(MediaTypeTextPlain)) assert.True(t, ValidCoapMediaTypeCode(MediaTypeOpaqueVndOmaLwm2m)) assert.False(t, ValidCoapMediaTypeCode(MediaType(9999))) } ================================================ FILE: xml.go ================================================ package canopus // Represents a message payload containing XML String type XMLPayload struct { }