Authentication Guide

Enable Authentication using HTTPS at the backend CSE and gateway CSE

To enable authentication the following parameters need to be changed in the configuration files of the backend CSE and gateway CSE named config-backend.json and config-gateway.json. The configuration files are located in the openmtc-open-source/openmtc-gevent directory.

In the plugins section of each configuration file the HTTPTransportPlugin needs to be enabled. Therefore, make sure the disabled option of the plugin is set to false. Set the option enable_https to true in the config of the HTTPTransportPlugin to enable HTTPS. If the option require_cert is set to true, the client that requests the gateway must provide a certificate.

Example of the gateway CSE configuration:

"plugins": {
        "openmtc_cse": [
            {
                "name": "HTTPTransportPlugin",
                "package": "openmtc_cse.plugins.transport_gevent_http",
                "disabled": false,
                "config": {
                    "enable_https": true,
                    "interface": "::",
                    "port": 8000,
                    "require_cert": true
                }
            },

The necessary SSL parameters used for the HTTPS/SSL connection must be specified in the ssl_certs option in the onem2m section of the corresponding configuration file. This option includes the private key (key), the certificate (crt) and the certificate chain (ca). Pre-shipped keys, certificates and a chain file which can be used at the gateway CSE and the backend CSE are located in the openmtc-open-source/openmtc-gevent/certs directory.

Example of the SSL parameters configured at the gateway CSE:

"onem2m": {
        "accept_insecure_certs": false,
        "cse_base": "onem2m",
        "cse_id": "mn-cse-1",
        "cse_type": "MN-CSE",
        "overwrite_originator": {
            "enabled": false,
            "originator": "/openmtc.org/mn-cse-1"
        },
        "sp_id": "openmtc.org",
        "ssl_certs": {
            "ca": "certs/ca-chain.cert.pem",
            "crt": "certs/mn-cse-1-client-server.cert.pem",
            "key": "certs/mn-cse-1-client-server.key.pem"
        }
    },

Registering the gateway CSE to the backend CSE using HTTPS

The RegistrationHandler plugin is responsible to register the gateway CSE to the backend CSE. Therefore, the plugin needs to be enabled by setting the disabled option to false. Furthermore, when HTTPS is enabled at both CSEs the options poa and own_poa needs to be changed to https://... in the config section of the RegistrationHandler plugin.

{
                "name": "RegistrationHandler",
                "package": "openmtc_cse.plugins.registration_handler",
                "disabled": false,
                "config": {
                    "interval": 3600,
                    "labels": [
                        "openmtc"
                    ],
                    "offset": 3600,
                    "remote_cses": [
                        {
                            "cse_base": "onem2m",
                            "cse_id": "in-cse-1",
                            "cse_type": "IN_CSE",
                            ,
                            "own_poa": [
                                "https://localhost:8000"
                            ],
                            "poa": [
                                "https://localhost:18000"
                            ]
                        }
                    ]
                }
            },

Authentication of AEs/IPEs

When HTTPS is enabled in the configuration of the CSEs the AEs/IPEs must provide SSL information as well to perform requests to the CSEs.

Using the OpenMTC application framework AEs and IPEs derive from the provided base class openmtc_app.onem2m.XAE.

When creating an instance of the AE/IPE the following additional SSL parameter can be specified:

ca_certs: the certificate chain file
cert_file: the certificate file
key_file: the private key file
originator_pre: the originator which needs to match the subjectAltName value in the certificate

If all SSL parameters are specified, the AE/IPE is started by the application framework using an HTTPS client.

Example from the onem2m-gui-sensors-actuators-final.py training IPE:

host = 'https://localhost:8000'
    app = TestIPE(
        poas=['https://localhost:21346'],          # adds poas in order to receive notifications
        # SSL options
        originator_pre='//openmtc.org/mn-cse-1',  # originator_pre, needs to match value in cert
        ca_certs='../../openmtc-gevent/certs/ca-chain.cert.pem',
        cert_file='certs/test-ipe.cert.pem',      # cert file, pre-shipped and should match name
        key_file='certs/test-ipe.key.pem'
    )

Request information using curl when HTTPS is enabled

In general requests are performed just the same as presented in the REST API Guide. But, when HTTPS is enabled additional SSL options need to be provided by the client to the CSE.

When using curl as client add the following options:

--cert: the client certificate
--key: the private client key
--cacert: the certificate chain
-H: set Header Fields, used to set the X-M2M-Origin header mapped as the originator

Example curl request

curl https://localhost:8000/onem2m -v --cert test-ae.cert.pem --key test-ae.key.pem --cacert ca-chain.cert.pem -H "X-M2M-Origin: //openmtc.org/mn-cse-1/CTest-AE"

Notes

If the option require_cert in the HTTPTransportPlugin config is set to false, the client does not need to present a certificate. Therefore, the curl option --cert and --key are not needed when sending a request to the CSE.

Example:

curl https://localhost:8000/onem2m -v --cacert ca-chain.cert.pem -H "X-M2M-Origin: //openmtc.org/mn-cse-1/CTest-AE"

curl performs SSL certificate verification by default, using a "bundle" of Certificate Authority (CA) public keys (CA certs). Using the --cacert option the "bundle" file which is used for verification can by specified. In the above example this option is used and the certificate presented by the server to the curl client is verified. Nevertheless, curl's verification of the server certificate can be turned off, using the -k (or --insecure) option.