DOCSEARCHbyAlgolia
Submit Docs

Eclipse Californium Documentation

repository·main·Indexed 20 days ago

https://github.com/eclipse-californium/californium

A Java implementation of the Constrained Application Protocol (CoAP) as defined in RFC7252. Designed for IoT Cloud services and embedded JVMs, it provides APIs for implementing CoAP clients and servers, support for secure CoAP (CoAPS) over DTLS, and proxying capabilities including CoAP-to-HTTP and HTTP-to-CoAP cross-protocol translation.

Tokens
55.7K
Snippets
136
Records
218
Agent score
68%

What's inside Eclipse Californium

  1. What is Scandium (Sc)?

    main

    Scandium (Sc) is a sub-module of Californium that provides security implementations for CoAP applications. It implements DTLS 1.2 to secure communications using Elliptic Curve Cryptography (ECC) with the following authentication methods:

    • Pre-shared keys (PSK)
    • Certificates
    • Raw public keys

    Scandium includes various DTLS extensions, such as the DTLS 1.2 Connection ID (RFC 9146), making it a mature security solution designed for Internet of Things (IoT) environments.

  2. Overview of Californium Cloud CoAP-S3-Proxy Server

    main

    The Californium (Cf) Cloud CoAP-S3-Proxy Server acts as a bridge between CoAP/DTLS 1.2 devices and the cloud. It is designed for SCADA (Supervisory Control And Data Acquisition) applications requiring reliable, efficient, and encrypted communication.

    Key Features:

    • DTLS 1.2 CID Support: Uses Connection ID (CID) for efficient communication.
    • Authentication Methods: Supports PreSharedKey (PSK), RawPublicKey, and x509 certificate authentication.
    • Data Persistence: Forwards received data to a Simple Storage Service (S3) for persistence.
    • Visualization: Includes a simple Web-Browser Single Page Application (SPA) to visualize device data via charts and manage device configurations.

  3. Overview of Californium Cloud Demo Server

    main

    The Californium (Cf) Cloud Demo Server is a simple server designed for device communication using CoAP and DTLS 1.2 CID. It is built on the Eclipse Californium library and supports multiple authentication methods for device communication:

    • PreSharedKey (PSK): Similar to a username/password.
    • RawPublicKey: Uses a public key as a certificate without additional metadata (subject, validity, etc.).
    • x509 Certificates: Standard certificate-based authentication.

    The server provides a devices resource for managing device data and includes an optional HTTPS server to view the last CoAP POSTs via a web browser. It also features an optional diagnose resource to monitor message counts and failures.

  4. What is Californium (Cf) Core?

    main

    Californium (Cf) Core is a central framework providing a CoAP (Constrained Application Protocol) implementation for building Internet of Things (IoT) applications in Java. It is designed to be highly interoperable and compliant with key CoAP standards, including:

    • RFC 7252: The core CoAP protocol.
    • RFC 7641: CoAP Observe option.
    • RFC 7959: CoAP Content-Format for media types.

    Californium is dual-licensed under EPL and EDL (a BSD-like license), allowing the framework to be used alongside proprietary code in commercial IoT products.

  5. Use the (s)NAT / LoadBalancer Simulator

    main

    The cf-nat module provides a simulator for (s)NAT and load-balancers. It can be used as a UDP load-balancer or an IPv6 gateway for cloud components that do not natively support UDP or IPv6.

    When a single destination is provided, it acts as a (s)NAT. When multiple destinations are provided, it activates load-balancer mode, randomly selecting a destination for incoming UDP messages and performing source-NAT.

    java -jar cf-nat-<version>.jar :5684 node1.coap.cluster:5684 node2.coap.cluster:5684

  7. Use the CoAP PubSub library for topic management and messaging

    main

    The cf-pubsub library implements the IETF CoAP publish-subscribe RFC and is designed to be used alongside the Californium library. It provides an API for interacting with a CoAP broker to manage topics and exchange data.

    Core Functionality

    • Discover: Find available topics on the broker. Providing the query rt=core.ps allows you to verify if the broker supports CoAP Publish-Subscribe.
    • Create: Create a new topic on the broker specifying a URI, name, and content type.
    • Publish: Send content to a specific topic URI.
    • Read: Retrieve the current content of a topic URI.
    • Remove: Delete a topic from the broker.
    • Subscription: Subscribe to or unsubscribe from a topic URI using a CoapHandler to receive updates.

    Helper Classes

    • Converter: Provides utility methods for processing responses.
    • Topic: Provides utility methods for managing topic data structures.
    // Basic initialization
PubSub pubsub = new PubSub("127.0.0.1"); 
// Or with custom port and timeout
PubSub pubsub = new PubSub("127.0.0.1", 5683, 5000);

  9. Use the Californium CLI for CoAP and CoAPS

    main

    The cf-cli module provides a common command line interface for various Californium clients. It handles argument application and the configuration of connectors and endpoints.

    By default, this module supports:

    • coap (plain UDP)
    • coaps (over DTLS)

    If you require TCP support, you must use the cf-cli-tcp-netty module in conjunction with cf-cli.

  10. What is element-connector?

    main

    The element-connector is a Java socket abstraction layer for various transports including UDP, DTLS, and TCP. It serves as a modular foundation for Californium (Cf) to support different transport protocols independently (e.g., TCP, SMS, or optimized VM sockets).

    It also acts as a shared utility module containing:

    • Configuration: The Configuration class (moved here in version 3) used by scandium and other modules.
    • Security Utilities: SslContextUtil for certificate loading and Asn1DerDecoder for decoding (D)TLS binary representations.
    • Data Utilities: StringUtil for byte/hex/base64 conversions and Statistic/TimeStatistic for high-volume sample tracking.

  11. Understand COSE implementation in Californium

    main

    To support Java 1.7, Californium includes a modified version of COSE-JAVA (0.9.7) within the org.eclipse.californium.cose package.

    • Unmodified files: AlgorithmID.java, Attribute.java, CoseException.java, HeaderKeys.java, and MessageTag.java are used without modification (except for updated license headers).
    • Modified files: EncryptCommon.java, Encrypt0Message.java, and Message.java have been modified for compatibility/integration.

  12. Configure Certificate-based (RPK/X509) authentication

    main

    For certificate-based security, you must provide a CertificateProvider to supply your credentials and a CertificateVerifier to verify the peer's certificates.

    Key Components:

    • CertificateProvider: Use SingleCertificateProvider for simple setups or KeyManagerCertificateProvider to support multiple certificates (e.g., for SNI or different algorithms).
    • CertificateVerifier: Use StaticCertificateVerifier for basic verification.
    • SslContextUtil: A utility to help load credentials from files or key-stores.

    Anonymous Clients (Californium 4.0+): In version 4.0+, a server can authenticate itself via certificate while the client remains anonymous in the DTLS handshake. In this case, the application must authorize the client using an ApplicationAuthorizer (available via CoapEndpoint or Exchange).

    // Load credentials using SslContextUtil
Credentials serverCredentials = SslContextUtil.loadCredentials(...);
Credentials serverTrusts = SslContextUtil.loadCredentials(...);

DtlsConnectorConfig.Builder builder = DtlsConnectorConfig.builder(configuration);
builder.setAddress(new InetSocketAddress(5684));

// Set up the identity provider
SingleCertificateProvider certificate = new SingleCertificateProvider(
    serverCredentials.getPrivateKey(), 
    serverCredentials.getCertificateChain()
);
builder.setCertificateIdentityProvider(certificate);

// Set up the verifier
CertificateVerifier trust = StaticCertificateVerifier.builder()
   .setTrustedCertificates(serverTrusts.getTrustedCertificates)
   .build();
builder.setCertificateVerifier(trust);

DTLSConnector connector = new DTLSConnector(builder.build());