Merge branch 'lorenzodonini:master' into master

Author: andig

.github/workflows/docker-publish.yml

@@ -1,6 +1,8 @@
 name: Publish examples
 on:
   push:
+    paths-ignore:
+      - "**.md"
     branches:
       - master
 jobs:

.github/workflows/test.yaml

@@ -1,5 +1,17 @@
 name: Test
-on: [ push, pull_request, workflow_dispatch ]
+on:
+  push:
+    paths-ignore:
+      - "**.md"
+      - LICENSE
+
+  pull_request:
+    paths-ignore:
+      - "**.md"
+      - LICENSE
+
+  workflow_dispatch:
+
 jobs:
   unit:
     runs-on: ubuntu-latest

README.md

@@ -1,6 +1,6 @@
 # ocpp-go
 
-[![Build Status](https://travis-ci.org/lorenzodonini/ocpp-go.svg?branch=master)](https://travis-ci.org/lorenzodonini/ocpp-go)
+[![Build Status](https://github.com/lorenzodonini/ocpp-go/actions/workflows/test.yaml/badge.svg)](https://github.com/lorenzodonini/ocpp-go/actions/workflows/test.yaml)
 [![GoDoc](https://img.shields.io/badge/godoc-reference-5272B4)](https://godoc.org/github.com/lorenzodonini/ocpp-go)
 [![Coverage Status](https://coveralls.io/repos/github/lorenzodonini/ocpp-go/badge.svg?branch=master)](https://coveralls.io/github/lorenzodonini/ocpp-go?branch=master)
 [![Go report](https://goreportcard.com/badge/github.com/lorenzodonini/ocpp-go)](https://goreportcard.com/report/github.com/lorenzodonini/ocpp-go)
@@ -20,6 +20,7 @@ but naming changed.**
 Planned milestones and features:
 
 -   [x] OCPP 1.6
+-   [x] OCPP 1.6 Security extension (experimental)
 -   [x] OCPP 2.0.1 (examples working, but will need more real-world testing)
 -   [ ] Dedicated package for configuration management
 
@@ -346,6 +347,102 @@ Then run the following:
 docker-compose -f example/1.6/docker-compose.tls.yml up charge-point
 ```
 
+## OCPP 1.6 Security extension
+
+The library supports the OCPP 1.6 Security extension, which adds support for additional messages that aren't a part of
+original OCPP 1.6 specification. The security extension is optional, but recommended to implement.
+
+There aren't any clear examples how to determine if a charge point supports security extensions via `SupportedProfiles`
+configuration key or which profiles are required to be implemented in order to support the security extension.
+As of now, the security extension is split into multiple profiles/functional blocks:
+
+- `ExtendedTriggerMessage`
+- `Certificates` (certificate management)
+- `Security` (event notifications, certificate signing)
+- `SecureFirmware` (secure firmware update)
+- `Logging`
+
+### HTTP Basic Auth
+
+The security extension specifies how to secure the communication between charge points and central systems
+using HTTP Basic Auth and/or certificates. These are already provided in the websocket server/client
+implementation.
+
+Example charge point:
+
+```go
+wsClient := ws.NewClient()
+wsClient.SetBasicAuth("foo", "bar")
+cp := ocpp16.NewChargePoint(chargePointID, nil, wsClient)
+```
+
+Example central system:
+
+```go
+server := ws.NewServer()
+server.SetBasicAuthHandler(func (username string, password string) bool {
+// todo Handle basic auth
+return true
+})
+cs := ocpp16.NewCentralSystem(nil, server)
+```
+
+### Certificate-based authentication (mTLS)
+
+The security extension specifies how to secure the communication between charge points and central systems
+using mTLS (client certificates). The library provides the necessary functionality to configure TLS,
+but mTLS itself is not in scope and should be handled by the user.
+
+### Additional configuration keys
+
+The OCPP 1.6 security extension introduces additional configuration keys.
+These are not a part of the standard library, but they impact how the charge point should behave.
+
+The charge point websocket client should be restarted when the `AuthorizationKey` configuration changes.
+
+### Central System
+
+To add support for security extension in the central system, you have the following handlers:
+
+```go
+// Support callbacks for all OCPP 1.6 profiles
+handler := &CentralSystemHandler{chargePoints: map[string]*ChargePointState{}}
+centralSystem.SetCoreHandler(handler)
+centralSystem.SetLocalAuthListHandler(handler)
+centralSystem.SetFirmwareManagementHandler(handler)
+centralSystem.SetReservationHandler(handler)
+centralSystem.SetRemoteTriggerHandler(handler)
+centralSystem.SetSmartChargingHandler(handler)
+
+// Add callbacks for OCPP 1.6 security profiles
+centralSystem.SetSecurityHandler(handler)
+centralSystem.SetSecureFirmwareHandler(handler)
+centralSystem.SetLogHandler(handler)
+
+```
+
+### Charge Point
+
+To add support for security extension in the charge point, you have the following handlers:
+
+```go
+handler := &ChargePointHandler{}
+// Support callbacks for all OCPP 1.6 profiles
+chargePoint.SetCoreHandler(handler)
+chargePoint.SetFirmwareManagementHandler(handler)
+chargePoint.SetLocalAuthListHandler(handler)
+chargePoint.SetReservationHandler(handler)
+chargePoint.SetRemoteTriggerHandler(handler)
+chargePoint.SetSmartChargingHandler(handler)
+// OCPP 1.6j Security extension
+chargePoint.SetCertificateHandler(handler)
+chargePoint.SetLogHandler(handler)
+chargePoint.SetSecureFirmwareHandler(handler)
+chargePoint.SetExtendedTriggerMessageHandler(handler)
+chargePoint.SetSecurityHandler(handler)
+
+```
+
 ## Advanced Features
 
 The library offers several advanced features, especially at websocket and ocpp-j level.
@@ -389,18 +486,27 @@ own logging system.
 
 ### Websocket ping-pong
 
-The websocket package currently supports client-initiated pings only.
+The websocket package supports configuring ping pong for both endpoints.
 
-If your setup requires the server to be the initiator of a ping-pong (e.g. for web-based charge points),
-you may disable ping-pong entirely and just rely on the heartbeat mechanism:
+By default, the client sends a ping every 54 seconds and waits for a pong for 60 seconds, before timing out.
+The values can be configured as follows:
+```go
+cfg := ws.NewClientTimeoutConfig()
+cfg.PingPeriod = 10 * time.Second
+cfg.PongWait = 20 * time.Second
+websocketClient.SetTimeoutConfig(cfg)
+```
 
+By default, the server does not send out any pings and waits for a ping from the client for 60 seconds, before timing out.
+To configure the server to send out pings, the `PingPeriod` and `PongWait` must be set to a value greater than 0:
 ```go
 cfg := ws.NewServerTimeoutConfig()
-cfg.PingWait = 0 // this instructs the server to wait forever
+cfg.PingPeriod = 10 * time.Second
+cfg.PongWait = 20 * time.Second
 websocketServer.SetTimeoutConfig(cfg)
 ```
 
-> A server-initiated ping may be supported in a future release.
+To disable sending ping messages, set the `PingPeriod` value to `0`.
 
 ## OCPP 2.0.1 Usage
 

example/1.6/cp/charge_point_sim.go

@@ -64,10 +64,10 @@ func setupTlsChargePoint(chargePointID string) ocpp16.ChargePoint {
 		}
 	}
 	// Create client with TLS config
-	client := ws.NewTLSClient(&tls.Config{
+	client := ws.NewClient(ws.WithClientTLSConfig(&tls.Config{
 		RootCAs:      certPool,
 		Certificates: clientCertificates,
-	})
+	}))
 	return ocpp16.NewChargePoint(chargePointID, nil, client)
 }
 

example/1.6/cs/central_system_sim.go

@@ -67,10 +67,10 @@ func setupTlsCentralSystem() ocpp16.CentralSystem {
 	if !ok {
 		log.Fatalf("no required %v found", envVarServerCertificateKey)
 	}
-	server := ws.NewTLSServer(certificate, key, &tls.Config{
+	server := ws.NewServer(ws.WithServerTLSConfig(certificate, key, &tls.Config{
 		ClientAuth: tls.RequireAndVerifyClientCert,
 		ClientCAs:  certPool,
-	})
+	}))
 	return ocpp16.NewCentralSystem(nil, server)
 }
 

example/2.0.1/chargingstation/charging_station_sim.go

@@ -66,10 +66,10 @@ func setupTlsChargingStation(chargingStationID string) ocpp2.ChargingStation {
 		}
 	}
 	// Create client with TLS config
-	client := ws.NewTLSClient(&tls.Config{
+	client := ws.NewClient(ws.WithClientTLSConfig(&tls.Config{
 		RootCAs:      certPool,
 		Certificates: clientCertificates,
-	})
+	}))
 	return ocpp2.NewChargingStation(chargingStationID, nil, client)
 }
 

example/2.0.1/csms/csms_sim.go

@@ -70,10 +70,10 @@ func setupTlsCentralSystem() ocpp2.CSMS {
 	if !ok {
 		log.Fatalf("no required %v found", envVarServerCertificateKey)
 	}
-	server := ws.NewTLSServer(certificate, key, &tls.Config{
+	server := ws.NewServer(ws.WithServerTLSConfig(certificate, key, &tls.Config{
 		ClientAuth: tls.RequireAndVerifyClientCert,
 		ClientCAs:  certPool,
-	})
+	}))
 	return ocpp2.NewCSMS(nil, server)
 }
 

ocpp1.6/v16.go

@@ -153,13 +153,13 @@ type ChargePoint interface {
 //	if !ok {
 //		log.Fatal("couldn't parse PEM certificate")
 //	}
-//	cp := NewClient("someUniqueId", nil, ws.NewTLSClient(&tls.Config{
+//	cp := NewClient("someUniqueId", nil, ws.NewClient(ws.WithClientTLSConfig(&tls.Config{
 //		RootCAs: certPool,
-//	})
+//	}))
 //
 // For more advanced options, or if a customer networking/occpj layer is required,
-// please refer to ocppj.Client and ws.WsClient.
-func NewChargePoint(id string, endpoint *ocppj.Client, client ws.WsClient) ChargePoint {
+// please refer to ocppj.Client and ws.Client.
+func NewChargePoint(id string, endpoint *ocppj.Client, client ws.Client) ChargePoint {
 	if client == nil {
 		client = ws.NewClient()
 	}
@@ -338,8 +338,8 @@ type CentralSystem interface {
 //
 // If you need a TLS server, you may use the following:
 //
-//	cs := NewServer(nil, ws.NewTLSServer("certificatePath", "privateKeyPath"))
-func NewCentralSystem(endpoint *ocppj.Server, server ws.WsServer) CentralSystem {
+//	cs := NewServer(nil, ws.NewServer(ws.WithServerTLSConfig("certificatePath", "privateKeyPath", nil)))
+func NewCentralSystem(endpoint *ocppj.Server, server ws.Server) CentralSystem {
 	if server == nil {
 		server = ws.NewServer()
 	}

ocpp1.6_test/ocpp16_test.go

@@ -4,7 +4,6 @@ import (
 	"crypto/tls"
 	"fmt"
 	"net"
-	"net/http"
 	"reflect"
 	"testing"
 	"time"
@@ -50,14 +49,18 @@ func (websocket MockWebSocket) TLSConnectionState() *tls.ConnectionState {
 	return nil
 }
 
+func (websocket MockWebSocket) IsConnected() bool {
+	return true
+}
+
 func NewMockWebSocket(id string) MockWebSocket {
 	return MockWebSocket{id: id}
 }
 
 // ---------------------- MOCK WEBSOCKET SERVER ----------------------
 type MockWebsocketServer struct {
 	mock.Mock
-	ws.WsServer
+	ws.Server
 	MessageHandler            func(ws ws.Channel, data []byte) error
 	NewClientHandler          func(ws ws.Channel)
 	CheckClientHandler        ws.CheckClientHandler
@@ -77,11 +80,11 @@ func (websocketServer *MockWebsocketServer) Write(webSocketId string, data []byt
 	return args.Error(0)
 }
 
-func (websocketServer *MockWebsocketServer) SetMessageHandler(handler func(ws ws.Channel, data []byte) error) {
+func (websocketServer *MockWebsocketServer) SetMessageHandler(handler ws.MessageHandler) {
 	websocketServer.MessageHandler = handler
 }
 
-func (websocketServer *MockWebsocketServer) SetNewClientHandler(handler func(ws ws.Channel)) {
+func (websocketServer *MockWebsocketServer) SetNewClientHandler(handler ws.ConnectedHandler) {
 	websocketServer.NewClientHandler = handler
 }
 
@@ -96,14 +99,14 @@ func (websocketServer *MockWebsocketServer) NewClient(websocketId string, client
 	websocketServer.MethodCalled("NewClient", websocketId, client)
 }
 
-func (websocketServer *MockWebsocketServer) SetCheckClientHandler(handler func(id string, r *http.Request) bool) {
+func (websocketServer *MockWebsocketServer) SetCheckClientHandler(handler ws.CheckClientHandler) {
 	websocketServer.CheckClientHandler = handler
 }
 
 // ---------------------- MOCK WEBSOCKET CLIENT ----------------------
 type MockWebsocketClient struct {
 	mock.Mock
-	ws.WsClient
+	ws.Client
 	MessageHandler      func(data []byte) error
 	ReconnectedHandler  func()
 	DisconnectedHandler func(err error)
@@ -445,41 +448,6 @@ func (smartChargingListener *MockChargePointSmartChargingListener) OnGetComposit
 }
 
 // ---------------------- COMMON UTILITY METHODS ----------------------
-func NewWebsocketServer(t *testing.T, onMessage func(data []byte) ([]byte, error)) *ws.Server {
-	wsServer := ws.Server{}
-	wsServer.SetMessageHandler(func(ws ws.Channel, data []byte) error {
-		assert.NotNil(t, ws)
-		assert.NotNil(t, data)
-		if onMessage != nil {
-			response, err := onMessage(data)
-			assert.Nil(t, err)
-			if response != nil {
-				err = wsServer.Write(ws.ID(), data)
-				assert.Nil(t, err)
-			}
-		}
-		return nil
-	})
-	return &wsServer
-}
-
-func NewWebsocketClient(t *testing.T, onMessage func(data []byte) ([]byte, error)) *ws.Client {
-	wsClient := ws.Client{}
-	wsClient.SetMessageHandler(func(data []byte) error {
-		assert.NotNil(t, data)
-		if onMessage != nil {
-			response, err := onMessage(data)
-			assert.Nil(t, err)
-			if response != nil {
-				err = wsClient.Write(data)
-				assert.Nil(t, err)
-			}
-		}
-		return nil
-	})
-	return &wsClient
-}
-
 type expectedCentralSystemOptions struct {
 	clientId              string
 	rawWrittenMessage     []byte

ocpp2.0.1/v2.go

@@ -202,13 +202,13 @@ type ChargingStation interface {
 //	if !ok {
 //		log.Fatal("couldn't parse PEM certificate")
 //	}
-//	cs := NewChargingStation("someUniqueId", nil, ws.NewTLSClient(&tls.Config{
+//	cs := NewChargingStation("someUniqueId", nil, ws.NewClient(ws.WithClientTLSConfig(&tls.Config{
 //		RootCAs: certPool,
-//	})
+//	}))
 //
 // For more advanced options, or if a custom networking/occpj layer is required,
-// please refer to ocppj.Client and ws.WsClient.
-func NewChargingStation(id string, endpoint *ocppj.Client, client ws.WsClient) ChargingStation {
+// please refer to ocppj.Client and ws.Client.
+func NewChargingStation(id string, endpoint *ocppj.Client, client ws.Client) ChargingStation {
 	if client == nil {
 		client = ws.NewClient()
 	}
@@ -414,8 +414,8 @@ type CSMS interface {
 //
 // If you need a TLS server, you may use the following:
 //
-//	csms := NewCSMS(nil, ws.NewTLSServer("certificatePath", "privateKeyPath"))
-func NewCSMS(endpoint *ocppj.Server, server ws.WsServer) CSMS {
+//	csms := NewCSMS(nil, ws.NewServer(ws.WithServerTLSConfig("certificatePath", "privateKeyPath", nil)))
+func NewCSMS(endpoint *ocppj.Server, server ws.Server) CSMS {
 	if server == nil {
 		server = ws.NewServer()
 	}