• Stars
    star
    620
  • Rank 72,387 (Top 2 %)
  • Language
    Java
  • Created about 9 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

CoAP/DTLS Java Implementation

Californium logo

Californium (Cf) - CoAP for Java

Eclipse Californium is a Java implementation of RFC7252 - Constrained Application Protocol for IoT Cloud services. Thus, the focus is on scalability and usability instead of resource-efficiency like for embedded devices. Yet Californium is also suitable for embedded JVMs.

More information can be found at http://eclipse.dev/californium/ and http://coap.technology/.

Like to help improving Californium? Then consider to contribute.

Build using Maven

You need to have a working maven installation to build Californium. Then simply run the following from the project's root directory:

$ mvn clean install

Executable JARs of the examples with all dependencies can be found in the demo-apps/run folder.

The build-process in branch main is tested for jdk 7, jdk 8, jdk 11 and jdk 17. For jdk 7 the revapi maven-plugin is disabled, it requires at least java 8.

Note: the build **has been" tested long ago. In the meantime too much has changed. Please focus on using jdk 17 to build it.

To generate the javadocs, add "-DcreateJavadoc=true" to the command line and set the JAVA_HOME.

$ mvn clean install -DcreateJavadoc=true

Build jdk7 compliant

In the meantime, JDK 7 is pretty deprecated! The next major version (4) will not longer support it! It hopefully comes this year (2024).

Californium 2.x and newer can be used with java 7 or newer. In order to use plugins, which are only supported for newer jdks, the --release option is used (requires java 9 or newer to build it).

If you want to build it with a jdk 7, the toolchain plugin could be used, but requires manually remove the maven.compiler.release property in the pom.xml. That requires also a toolchains configuration in "toolchains.xml" in your maven ".m2" folder

<?xml version="1.0" encoding="UTF8"?>
<toolchains>
	<!-- JDK toolchains -->
	<toolchain>
		<type>jdk</type>
		<provides>
			<version>1.7</version>
		</provides>
		<configuration>
			<jdkHome>path..to..jdk7...home</jdkHome>
		</configuration>
	</toolchain>
</toolchains>

To use the jdk7 toolchain, add "-DuseToolchain=true" to the command line.

$ mvn clean install -DuseToolchain=true

To use the jdk7 toolchain and create javadocs, add "-DuseToolchainJavadoc=true" to the command line (JAVA_HOME is not required).

$ mvn clean install -DuseToolchainJavadoc=true

Build with jdk11 and EdDSA support

To support EdDSA, either java 17 or java 11 with ed25519-java is required at runtime. Using java 17 (or newer) to build Californium, leaves out ed25519-java, using java 11 for building, includes ed25519-java by default. If ed25519-java should NOT be included into the californium's jars, add -Dno.net.i2p.crypto.eddsa=true to maven's arguments.

$ mvn clean install -Dno.net.i2p.crypto.eddsa=true

Note: if "-DuseToolchain=true" is used and the actual jdk to build is java 11, you must disable the i2p eddsa support as well.

# java 11 with java 7 toolchain
$ mvn clean install -DuseToolchain=true -Dno.net.i2p.crypto.eddsa=true

In that case, it's still possible to use ed25519-java, if the eddsa-0.3.0.jar is provided to the classpath separately.

Note: using the oracle build 28 of openjdk 11 uncovers, that calling EdDSAEngine.engineSetParameter(null) fails with ǸullPointerException instead of InvalidAlgorithmParameterException. That causes to fail the verification of the signature at all. Using the aptopen build seems not to call EdDSAEngine.engineSetParameter(null) and therefore works.

ed25519-java seems to be not longer maintained. It's therefore recommended to update to newer jdks (e.g. 17) or to use Bouncy Castle (see next section, even if the Bouncy Castle support is experimental).

Run unit tests using Bouncy Castle as alternative JCE provider

With 3.0 a first, experimental support for using Bouncy Castle (version 1.69, bcprov-jdk15on, bcpkix-jdk15on, and, for tls, bctls-jdk15on) is implemented. With 3.3 the tests are using the updated version 1.70 (for tls also bcutil-jdk15on is used additionally), with 3.8 version 1.72, with 3.9 version 1.74, and with 3.10 to version 1.77.

To demonstrate the basic functions, run the unit-tests using the profile bc-tests

$ mvn clean install -Pbc-tests

Supporting Bouncy Castle for the unit test uncovers a couple of differences, which required to adapt the implementation. It is assumed, that more will be found and more adaption will be required. If you find some, don't hesitate to report issues, perhaps research and analysis, and fixes. On the other hand, the project Californium will for now not be able to provide support for Bouncy Castle questions with or without relation to Californium. You may create issues, but it may be not possible for us to answer them.

On issue seems to be the SecureRandom generator of BC. Dependent on the runtime environment, that is based on SecureRandom.getInstanceStrong(), which has blocking behaviour by default. If the platform your application runs on, has not enough entropy to start the SecureRandom, BC waits until that gets available. In common cases, that starts quite fast, but in some cases, that takes up to 60s (and more).

One option to overcome that on some linux variants is using rng-tools. That may help to provide more entropy.

A second option o overcome that is to setup CALIFORNIUM_JCE_PROVIDER using the value BC_NON_BLOCKING_RANDOM instead of BC. The JceProviderUtil then adapts SecureRandom to use a, maybe weaker, non-blocking SecureRandom. If that works, depends unfortunately on your platform, so especially for Android, that may not work. In that cases, please use BC as CALIFORNIUM_JCE_PROVIDER and configure "securerandom.strongAlgorithms" ahead with

Security.setProperty("securerandom.strongAlgorithms", "<your-android-algorithm>");

according your android variant. That may require some analysis by you.

With that, it gets very time consuming to test all combinations. Therefore, if you need a specific one, please test it on your own. If you consider, that some adaption is required, let us know by creating an issue or PR.

Using Californium in Maven Projects

We are publishing Californium's artifacts for milestones and releases to Maven Central. To use the latest released version as a library in your projects, add the following dependency to your pom.xml (without the dots ...):

  <dependencies>
    ...
    <dependency>
            <groupId>org.eclipse.californium</groupId>
            <artifactId>californium-core</artifactId>
            <version>3.11.0</version>
    </dependency>
    ...
  </dependencies>
  ...
Current Builds

You can also be bold and try out the most recent build from main. However, we are not publishing those to Maven Central but to Californium's project repository at Eclipse only. You will therefore need to add the Eclipse Repository to your pom.xml first:

  <repositories>
    ...
    <repository>
      <id>repo.eclipse.org</id>
      <name>Californium Repository</name>
      <url>https://repo.eclipse.org/content/repositories/californium/</url>
    </repository>
    ...
  </repositories>

You can then simply depend on 3.12.0-SNAPSHOT.

Eclipse

The project can be easily imported into a recent version of the Eclipse IDE. Make sure to have the following before importing the Californium (Cf) projects:

  • Eclipse EGit (should be the case with every recent Eclipse version)
  • m2e - Maven Integration for Eclipse (should be the case with every recent Eclipse version)
  • UTF-8 workspace text file encoding (Preferences » General » Workspace)

Then choose [Import... » Maven » Existing Maven Projects] to import californium - parent together with all sub-modules into Eclipse.

IntelliJ

The project can also be imported to IntelliJ as follows:

In IntelliJ, choose [File.. » Open] then select the location of the cloned repository in your filesystem. IntelliJ will then automatically import all projects and resolve required Maven dependencies.

Interop Server

A test server is running at coap://californium.eclipseprojects.io:5683/

It is an instance of the cf-plugtest-server from the demo-apps. The root resource responds with its current version.

For a preview to the Return Routability Check for DTLS 1.2 and DTLS 1.3 experimental support, please read feature/rrc - branch.

Please note: The server is intended to test the interoperability of CoAP and DTLS 1.2. Data sent to that server is typically "Hello world". The data is public visible to all other users and is removed on any restart. Please don't send data, which requires "data privacy", the sandbox server is not intended for such usage.

More information can be found at http://www.eclipse.org/californium and technical details at https://projects.eclipse.org/projects/iot.californium.

Another interop server with a different implementation can be found at coap://coap.me:5683/. More information can be found at http://coap.me/.

Interop Server - (D)TLS Support

The server uses the x509 Demo Certificates, which are usually recreated and replaced once a year. And the PSK credentials:

Identity Secret Remark
"Client_identity" "secretPSK" openssl defaults
"password" "sesame" ETSI Plugtest test spec
Regex "cali\..*" ".fornium" Wildcard Identity for plugtest
Regex "^[^@]{8,}@.{8,}$" "secret" Wildcard Identity for hono-identites

Note: TLS supports only the x509 Demo Certificates.

Interop Server - OSCORE Support

The server has a resource only accessible using OSCORE under "/oscore". It is configured with the following security material (client side):

Master Secret: 0x0102030405060708090a0b0c0d0e0f10 (16 bytes)
Master Salt:   0x9e7ca92223786340 (8 bytes)
Sender ID:     0x01 (1 byte)
Recipient ID:  0x02 (1 byte)
ID Context:    0x37cbf3210017a2d3 (8 bytes)
(See up to date parameters in "/oscoreInfo" resource)

Note that the server supports running the Appendix B.2 context rederivation procedure. This is necessary as requests from new clients would otherwise be considered replays (as the server's replay window is filled up from earlier clients). To access this resource without using the Appendix B.2 procedure, an appropriate Sender Sequence Number to use and the current ID Context can be retrieved from the resource "/oscoreInfo" using plain CoAP.

Currently Californium's OSCORE supports following algorithms:

OSCORE Encryption:

  • AES_CCM_16_64_128, id 10
  • AES_CCM_64_64_128, id 12
  • AES_CCM_16_128_128, id 30
  • AES_CCM_64_128_128, id 32

OSCORE Key Rederivation:

  • HKDF_HMAC_SHA_256, id -10
  • HKDF_HMAC_SHA_512, id -11

Adapter Selection

For some systems (particularly when multicasting), it may be necessary to specify/restrict californium to a particular network interface, or interfaces. This can be achieved by setting the COAP_NETWORK_INTERFACES JVM parameter to a suitable regex, for example:

java -DCOAP_NETWORK_INTERFACES='.*wpan0' -jar target/cf-helloworld-server-3.10.0.jar MulticastTestServer

Contact

A bug, an idea, an issue? Join the Mailing list or create an issue here on GitHub.

Contributing

Please check out our contribution guidelines

There are a couple of enhancement issues, which have been closed for longer inactivity. Maybe, if you like to help and spend some time, you will be welcome.

More Repositories

1

mosquitto

Eclipse Mosquitto - An open source MQTT broker
C
7,649
star
2

che

Kubernetes based Cloud Development Environments for Enterprise Teams
TypeScript
6,868
star
3

jetty.project

Eclipse Jetty® - Web Container & Clients - supports HTTP/2, HTTP/1.1, HTTP/1.0, websocket, servlets, and more
Java
3,655
star
4

paho.mqtt.android

MQTT Android
Java
2,708
star
5

paho.mqtt.golang

Go
2,381
star
6

eclipse-collections

Eclipse Collections is a collections framework for Java with optimized data structures and a rich, functional and fluent API.
Java
2,283
star
7

paho.mqtt.java

Eclipse Paho Java MQTT client library. Paho is an Eclipse IoT project.
Java
2,095
star
8

paho.mqtt.python

paho.mqtt.python
Python
1,946
star
9

sumo

Eclipse SUMO is an open source, highly portable, microscopic and continuous traffic simulation package designed to handle large networks. It allows for intermodal simulation including pedestrians and comes with a large set of tools for scenario creation.
1,902
star
10

paho.mqtt.c

An Eclipse Paho C client library for MQTT for Windows, Linux and MacOS. API documentation: https://eclipse.github.io/paho.mqtt.c/
C
1,736
star
11

eclipse.jdt.ls

Java language server
Java
1,410
star
12

mraa

Linux Library for low speed IO Communication in C with bindings for C++, Python, Node.js & Java. Supports generic io platforms, as well as Intel Edison, Intel Joule, Raspberry Pi and many more.
C
1,349
star
13

paho.mqtt.embedded-c

Paho MQTT C client library for embedded systems. Paho is an Eclipse IoT project (https://iot.eclipse.org/)
C
1,307
star
14

openvsx

An open-source registry for VS Code extensions
Java
1,181
star
15

paho.mqtt.javascript

paho.mqtt.javascript
JavaScript
1,145
star
16

paho.mqtt.cpp

C++
976
star
17

milo

Eclipse Miloâ„¢ - an open source implementation of OPC UA (IEC 62541).
Java
976
star
18

omr

Eclipse OMRâ„¢ Cross platform components for building reliable, high performance language runtimes
C++
917
star
19

xtext

Eclipse Xtextâ„¢ is a language development framework
Java
715
star
20

upm

UPM is a high level repository that provides software drivers for a wide variety of commonly used sensors and actuators. These software drivers interact with the underlying hardware platform through calls to MRAA APIs.
C++
651
star
21

microprofile

Repository for important documentation - the index to the project / community
Java
635
star
22

leshan

Java Library for LWM2M
Java
614
star
23

paho.mqtt-spy

mqtt-spy is an open source desktop & command line utility intended to help you with monitoring activity on MQTT topics
Java
605
star
24

steady

Analyses your Java applications for open-source dependencies with known vulnerabilities, using both static analysis and testing to determine code context and usage for greater accuracy. https://eclipse.github.io/steady/
Java
518
star
25

sprotty

A diagramming framework for the web
TypeScript
514
star
26

paho.mqtt.m2mqtt

C#
513
star
27

jifa

🔬 Online Heap Dump, GC Log, Thread Dump & JFR File Analyzer.
Java
509
star
28

buildship

The Eclipse Plug-ins for Gradle project.
Java
507
star
29

lsp4j

A Java implementation of the language server protocol intended to be consumed by tools and language servers implemented in Java.
Java
473
star
30

kura

Eclipse Kuraâ„¢ project
Java
469
star
31

wakaama

Eclipse Wakaama is a C implementation of the Open Mobile Alliance's LightWeight M2M protocol (LWM2M).
C
465
star
32

streamsheets

An open-source tool for processing stream data using a spreadsheet-like interface.
JavaScript
449
star
33

paho.mqtt.rust

paho.mqtt.rust
Rust
422
star
34

hawkbit

Eclipse hawkBitâ„¢
Java
416
star
35

eclipse-collections-kata

Eclipse Collections Katas
Java
411
star
36

hono

Eclipse Honoâ„¢ Project
Java
378
star
37

repairnator

Software development bots for Github. Join the bot revolution! 🌟🤖🌟💞
Java
370
star
38

ponte

Ponte Project
JavaScript
360
star
39

birt

Eclipse BIRTâ„¢ The open source reporting and data visualization project.
Java
355
star
40

paho.golang

Go libraries
Go
324
star
41

rdf4j

Eclipse RDF4J: scalable RDF for Java
Java
323
star
42

paho.mqtt-sn.embedded-c

Paho C MQTT-SN gateway and libraries for embedded systems. Paho is an Eclipse IoT project.
C++
313
star
43

lemminx

XML Language Server
Java
255
star
44

vorto

Vorto Project
Java
221
star
45

tahu

Eclipse Tahu addresses the existence of legacy SCADA/DCS/ICS protocols and infrastructures and provides a much-needed definition of how best to apply MQTT into these existing industrial operational environments.
Java
220
star
46

kapua

Java
218
star
47

elk

Eclipse Layout Kernel - Automatic layout for Java applications.
Java
211
star
48

jnosql

Eclipse JNoSQL is a framework which has the goal to help Java developers to create Jakarta EE applications with NoSQL.
Java
210
star
49

corrosion

Eclipse Corrosion - Rust edition in Eclipse IDE
Java
199
star
50

capella

Open Source Solution for Model-Based Systems Engineering
Java
197
star
51

dirigible

Eclipse Dirigibleâ„¢ Project
JavaScript
196
star
52

microprofile-config

MicroProfile Configuration Feature
Java
182
star
53

wildwebdeveloper

Simple and productive Web Development Tools in the Eclipse IDE
Java
181
star
54

pdt

PHP Development Tools project (PDT)
PHP
178
star
55

org.aspectj

Java
172
star
56

xacc

XACC - eXtreme-scale Accelerator programming framework
C++
137
star
57

thingweb.node-wot

thingweb.node-wot
TypeScript
130
star
58

microprofile-rest-client

MicroProfile Rest Client
Java
124
star
59

tycho

Tycho project repository (tycho)
Java
119
star
60

microprofile-conference

Microprofile.io Demo Code - Web Services Conference Application
Java
117
star
61

microprofile-fault-tolerance

microprofile fault tolerance
Java
115
star
62

microprofile-samples

Micro Profile Samples
Java
115
star
63

xtext-core

xtext-core
Java
114
star
64

microprofile-open-api

Microprofile open api
Java
112
star
65

jbom

Java
111
star
66

gef

Eclipse GEFâ„¢
Java
111
star
67

transformer

Eclipse Transformer provides tools and runtime components that transform Java binaries, such as individual class files and complete JARs and WARs, mapping changes to Java packages, type names, and related resource names.
Java
108
star
68

paho.mqtt.testing

An Eclipse Paho project - a Python broker for testing
Python
104
star
69

tinydtls

Eclipse tinydtls
C
102
star
70

xtext-xtend

xtext-xtend
Java
100
star
71

microprofile-graphql

microprofile-graphql
Java
98
star
72

microprofile-lra

microprofile-lra
Java
97
star
73

microprofile-health

microprofile-health
Java
95
star
74

microprofile-metrics

microprofile-metrics
Java
94
star
75

kuksa.val

kuksa.val
C++
93
star
76

sw360

SW360 project
Java
92
star
77

microprofile-jwt-auth

Java
92
star
78

mosaic

Eclipse MOSAIC is a Multi-Domain and Multi-Scale Simulation Framework for Automated and Connected Mobility Scenarios.
Java
88
star
79

nebula

Nebula Project
Java
84
star
80

microprofile-reactive-streams-operators

Microprofile project
Java
79
star
81

mosquitto.rsmb

Mosquitto rsmb
C
75
star
82

microprofile-starter

MicroProfile project generator source code
Java
69
star
83

aCute

Eclipse aCute - C# edition in Eclipse IDE
Java
65
star
84

ditto-examples

Eclipse Dittoâ„¢: Digital Twin framework - Examples
Java
63
star
85

epsilon

Epsilon is a family of Java-based scripting languages for automating common model-based software engineering tasks, such as code generation, model-to-model transformation and model validation, that work out of the box with EMF (including Xtext and Sirius), UML (including Cameo/MagicDraw), Simulink, XML and other types of models.
Java
61
star
86

lsp4e

Language Server Protocol support in Eclipse IDE
Java
60
star
87

tm4e

TextMate support in Eclipse IDE
Java
60
star
88

californium.tools

Californium project
Java
59
star
89

microprofile-reactive-messaging

Java
59
star
90

microprofile-opentracing

microprofile-opentracing
Java
57
star
91

eclemma

🌘 Java Code Coverage for Eclipse IDE
Java
57
star
92

texlipse

Eclipse Texlipse
Java
56
star
93

mita

mita
Xtend
55
star
94

dartboard

Dart Plugin for Eclipse
Java
55
star
95

jnosql-databases

This project contains Eclipse JNoSQL databases
Java
54
star
96

windowbuilder

Eclipse Windowbuilder
Java
54
star
97

xtext-eclipse

xtext-eclipse
Java
49
star
98

adore

Eclipse ADORe is a ROS based modular software library and toolkit for decision making, planning, control and simulation of automated vehicles supporting CARLA and SUMO.
Makefile
48
star
99

packages

IoT Packages project
Smarty
46
star
100

amlen

Message Broker for IoT/Mobile/Web. Mainly uses MQTT v3.x and v5. Aims to be easy to use, scalable and reliable
C
46
star