Incoming https connector (ssl, utf-8 and json)

The below sample setup requires EMG 7.1.5 or later.

Background

EMG 7.1 offers an improved HTTP API supporting UTF-8 and JSON responses.

The general configuration keyword DEFAULT_CHARCODE_TEXT specifies which encoding will be used within EMG for plain text (not unicode or binary) messages.

The connector configuration keyword DEFAULT_CHARCODE_TEXT specifies the default encoding for text messages when a CHARCODE parameter is not present.

In addition, if the default uri for the EMG http api “/bin/send” is changed to “/bin/send.json”, the response will be json encoded. Uri “/bin/send.xml” is supported for xml responses.

About SSL

SSL can be used for encryption and authentication. For public services you normally do not authenticate the client via a client certificate but rather negotiate an encrypted communication where the client trusts the service certificate if it is valid.

A self-signed certificate on the server (EMG) side can be used but the client may not want to trust it since it has not been issued by a commercial certificate authority (CA).

In that case it may be necessary to purchase a commercially signed certificate which is part of a commercial trust chain.

Please note that in order to successfully use SSL in a http request the server address should not be an ip address but a valid DNS host name which matches the “Common Name” in the certificate, i.e. a url like “https://sms.example.com:8443/bin/send“.

Configuration

In server.cfg (or equivalent in EMG Portal):

CONNECTOR https-in1 <
INHERIT=in-tmpl
ADDRESS=0.0.0.0:8443
PROTOCOL=HTTP
SSL
# If no CHARCODE present in incoming request, assume text is utf-8
DEFAULT_CHARCODE_TEXT=UTF8
INSTANCES=10
USERDB=emg
>

Sample EMG Portal configuration:

emgportal-connector-https

SSL certificate

You also need a certificate file. This is set with the SSL_KEYFILE connector option, and the value is the name of the file (an absolute path, or relative to $EMGDIR).

Self-signed

For testing purposes you can use a self-signed certificate.

openssl genrsa -out key.pem 2048
openssl req -new -key key.pem -out csr.pem
[ ... Fill out certificate information ... ]
openssl req -x509 -days 365 -key key.pem -in csr.pem -out cert.pem
cat key.pem cert.pem >emg.pem

Commercially signed certificate

In production environments used by clients you may need to use a commercially signed certificate to avoid client trust issues. The first two steps above for generating a CSR are the same, but then the CSR is submitted to the vendor of the certificate. Once the certificate has been issued you should be able to create a combined pem-file as above.

Sample request

Sending the text message “hello world å” (it is a swedish character as utf-8 at the end).

wget -q -O - "https://sms.example.com:8443/bin/send.json?USERNAME=user1&PASSWORD=secret1&DESTADDR=46123456&MESSAGE=hello+world+%C3%A5"
{
"results": [{"status": "0","msgid": "25593581","statustext": "OK"}],
"balance": "-818.5710"
}