Softcam and CAS API

Softcams and CAS entries are the two conditional access lists of the configuration. A softcam (softcam in the configuration) is a newcamd server Astra connects to for descrambling an input; a stream references it with cam=<softcam id> in the options of its input address, for example udp://239.0.0.1:1234#cam=a003. A CAS entry (cas in the configuration) holds the ECMG and EMMG parameters of a Simulcrypt system used to scramble an output; a stream references it with cas_id in its cas_list. Every entry has a unique string id.

All three methods are served on the command entry point only (POST /control/) and only by users of type 1 (control); an observer receives 404. The handlers do not validate the request: a body without the softcam, cas or config object, or a softcam configuration without a required field, raises an error inside the handler and terminates the Astra process - the client gets no reply (the connection is closed) and the log ends with [main] error in call to Lua API. api:<line>: <Lua error> (for example attempt to index field 'softcam' (a nil value)) followed by [main] abort execution. A client has to send complete requests.

Set softcam

Adds, replaces or removes a softcam entry.

Request: POST /control/. Control only.

{
    "cmd": "set-softcam",
    "id": "a003",
    "gid": 466563,
    "softcam": {
        "id": "a003",
        "name": "Softcam Name",
        "type": "newcamd",
        "host": "cam.example.com",
        "port": 34000,
        "user": "login",
        "pass": "password"
    }
}

• id - string, optional: the id of the entry to replace or remove. Without it the softcam object is added as a new entry.
• gid - number, optional: the id generator counter. When present it is stored as gid in the configuration. The built-in web interface increments it for every new entry and uses its base-36 form as the new id (466561 is a001).
• softcam - object, required: the entry exactly as it is stored in the configuration, or {"remove": true} to remove the entry named by id.

Softcam entry fields:

• id - string, required: the unique softcam id; input addresses reference it as cam=<id>.
• name - string, required: shown in the interface and in log lines.
• type - string, required: the softcam protocol; newcamd is the only value.
• host - string, required: newcamd server address, a host name or an IP address.
• port - number, required: newcamd server port.
• user - string, required: newcamd login.
• pass - string, required: newcamd password.
• key - string, optional: the DES key, 28 hex characters. Default 0102030405060708091011121314; a value of another length or with non-hex characters falls back to the default.
• caid - string, optional: 4 hex characters, replaces the CAID reported by the server card.
• timeout - number, optional: connection and response timeout in seconds; default 8.
• disable_emm - boolean, optional: true never forwards EMM to the server. Otherwise EMM are forwarded when the server card allows it.
• split_cam - boolean, optional: true opens a separate connection to the server for every stream that uses the softcam.
• shift - number, optional: input buffer in milliseconds for the descrambling delay, applied to streams that do not set their own shift.
• skip_ecm - number, optional: the number of ECM packets ignored at the start of every stream using the softcam.

Any other field is stored unchanged.

Response:

{ "set-softcam": "ok" }

This is the only reply of the method. An id that matches no entry removes nothing, and remove without id changes nothing; the reply is ok in both cases.

Side effects, in this order:

1. With id: every stream whose input address carries cam=<id> is updated - the option is stripped from the address when the entry is removed, rewritten to the new id when softcam.id differs from id, kept when the id is unchanged. Enabled streams among them are stopped. The running connection of the old entry is closed and the entry is removed from the configuration; a set-softcam message with {"id": "<id>", "remove": true, "up": <boolean>} is pushed to the WebSocket clients, up being true when a replacement follows.
2. Unless softcam.remove is set: the object is appended to the softcam list, a set-softcam message with the object is pushed (gid is the stored counter, absent when the configuration holds none), and the connection to the server is opened.
3. The streams of step 1 that are enabled are started again; those whose input address was rewritten are pushed as set-stream messages.
4. The configuration is saved.

See set-softcam and set-stream for the message shapes. The connection state of a softcam is pushed as softcam_event messages: once per second while it is connected, once per failed attempt.

With the API access log enabled the call is logged as set softcam id:<id> or remove softcam id:<id>, with null when id is absent.

Test softcam

Connects to a newcamd server with the given configuration and reports the card data. Nothing is stored.

Request: POST /control/. Control only.

{
    "cmd": "test-softcam",
    "config": {
        "name": "Softcam Name",
        "type": "newcamd",
        "host": "cam.example.com",
        "port": 34000,
        "user": "login",
        "pass": "password"
    }
}

• config - object, required: a softcam entry with the fields of set-softcam. type must be newcamd. A timeout value is ignored: the connection uses the default of 8 seconds, and the whole test is bounded at 10 seconds.

The connection is opened after a random delay of 20 milliseconds to 2 seconds. The reply is sent once the login is complete and the card data has arrived, or on the first error, or after 10 seconds. The HTTP client needs a read timeout above 10 seconds. The test connection is closed when the reply is sent.

Response on success:

{
    "status": 3,
    "caid": 2352,
    "ecm_rate": 0,
    "emm_rate": 0,
    "info": {
        "caid": 2352,
        "au": true,
        "ua": "0000000000000000",
        "idents": [
            { "id": "000000", "sa": "0000000000000000" }
        ]
    }
}

• status - number, always 3: connected and logged in.
• caid - number: the CAID of the server card (the caid option replaces it).
• ecm_rate, emm_rate - number: ECM and EMM sent to the server in the last 60 seconds; 0 in a test, no stream is attached.
• info.caid - number: the same CAID.
• info.au - boolean: the server card accepts EMM.
• info.ua - string: 16 hex characters, the unique address of the card.
• info.idents - array of the providers of the card: id - 6 hex characters, the provider ident; sa - 16 hex characters, the shared address.

Response on error, also 200:

{ "error": "login failed", "status": 0 }

• error - string: connection timeout (also for a host name that does not resolve), connection failed, response timeout, failed to parse response or login failed, reported by the newcamd connection together with status: 0; timeout when no result arrived within 10 seconds, without status; failed to initialize softcam when config.type is not newcamd, without status.

The method does not change the configuration, pushes no WebSocket message and is not written to the API access log.

Set CAS

Adds, replaces or removes a CAS entry.

Request: POST /control/. Control only.

{
    "cmd": "set-cas",
    "id": "a004",
    "gid": 466564,
    "cas": {
        "id": "a004",
        "name": "CAS Name",
        "super_cas_id": "4AE10000",
        "ecmg_channel_id": 1,
        "ecmg_host": "ecmg.example.com",
        "ecmg_port": 4000,
        "ecmg_cp": 10,
        "emmg_port": 4001,
        "emm_pid": 1000
    }
}

• id - string, optional: the id of the entry to replace or remove. Without it the cas object is added as a new entry.
• gid - number, optional: the id generator counter, as for set-softcam.
• cas - object, required: the entry exactly as it is stored in the configuration, or {"remove": true} to remove the entry named by id.

CAS entry fields, as read by the Simulcrypt module:

• id - string, required: the unique CAS id; streams reference it as cas_id in their cas_list.
• name - string: shown in the interface and in log lines.
• super_cas_id - string: 8 hex characters, the Super CAS ID (CA system id followed by the CA subsystem id). A value of another length is ignored.
• first_stream_id - when the field is present with any value, false included, ECM stream ids start at 1 instead of 0. Always the case for CAID 0x4AB0 to 0x4ABF (DGCrypt).
• ecmg_channel_id - number, required: the ECM channel id.
• ecmg_host - string, required: ECMG address.
• ecmg_port - number, required: ECMG port.
• ecmg_cp - number: crypto period in seconds; default 10.
• emmg_protocol - string: udp for EMM over UDP; any other value means TCP.
• emmg_port - number: EMMG port.
• emm_pid - number: PID of the EMM stream in the output; 0 or absent puts the EMM on PID 8191.
• emm_data - string: hex, private data appended to the CA descriptor in the CAT.
• emm_clone - boolean: true duplicates EMM packets to all streams.

A missing ecmg_channel_id, ecmg_host or ecmg_port is a configuration error of the CAS channel, logged as [CAS <id>] configuration error. Any other field is stored unchanged.

Response:

{ "set-cas": "ok" }

This is the only reply of the method; an id that matches no entry removes nothing.

Side effects, in this order:

1. With id: the entry is removed from the configuration and a set-cas message with {"id": "<id>", "remove": true, "up": <boolean>} is pushed, up being true when a replacement follows.
2. Unless cas.remove is set: the object is appended to the cas list and a set-cas message with the object is pushed (gid as for set-softcam).
3. The configuration is saved.

See set-cas for the message shape. Running streams are not restarted: the Simulcrypt module reads the entry when the first stream referencing its id starts, and every further stream with the same cas_id shares that channel until the last of them stops. A changed entry takes effect once all streams that use it have been restarted.

With the API access log enabled the call is logged as set cas id:<id> or remove cas id:<id>, with null when id is absent.