Andy Balaam from Andy Balaam's Blog
SMPP is a binary protocol used by phone companies to send text messages, otherwise known as SMS messages.
It can work over TCP, so we can use netcat on the command line to send messages.
Setting up
[Note: the netcat I am using is Ncat 7.70 on Linux.]
The server that receives messages is called an SMSC. You may have your own one, but if not, you can use the CloudHopper one like this:
sudo apt install make maven # (or similar on non-Debian-derived distros)
git clone https://github.com/fizzed/cloudhopper-smpp.git
cd cloudhopper-smpp
If you are a little slow, like me, I’d suggest making it wait a bit longer for bind requests before giving up on you. To do that, edit the main() method of src/test/java/com/cloudhopper/smpp/demo/ServerMain.java to add a line like this: configuration.setBindTimeout(500000); on about line 80, near the other similar lines. This will make it wait 500 seconds for you to send a BIND_TRANSCEIVER, instead of giving up after just 5 seconds.
Once you’ve made that change, you can run:
make server
Now you have an SMSC running!
Leave that open, and go into another terminal, and type:
mkfifo tmpfifo
nc 0.0.0.0 2776 < tmpfifo | xxd
The mkfifp part creates a “fifo” – a named pipe through which we will send our SMPP commands.
The nc part starts Ncat, connecting to the SMSC we started.
The xxd part will take any binary data coming out of Ncat and display it in a more human-readable way.
Leave that open too, and in a third terminal type:
exec 3> tmpfifo
This makes everything we send to file descriptor 3 go into the fifo, and therefore into Ncat.
Now we have a way of sending binary data to Ncat, which will send it on to the SMSC and print out any responses.
Note: we will be using SMPP version 3.4 since it is in the widest use, even though it is not the newest.
Terminology
“SMPP” is the protocol we are speaking, which we are using over TCP/IP.
An SMSC is a server (which receives messages intended for phones and sends back responses and receipts).
We will be acting as an ESME or client (which sends messages intended for phones and receives responses and receipts).
The units of information that are passed back and forth in SMPP are called “PDUs” (Protocol Data Units) – these are just bits of binary data that flow over the TCP connection between two computers.
The spec talks about “octets” – this means 8-bit bytes.
ENQUIRE_LINK
First, we’ll check the SMSC is responding, by sending an ENQUIRE_LINK, which is used to ask the SMSC whether it’s there and working.
Go back to the third terminal (where we ran exec) and type this:
LEN16='\x00\x00\x00\x10'
ENQUIRE_LINK='\x00\x00\x00\x15'
NULL='\x00\x00\x00\x00'
SEQ1='\x00\x00\x00\x01'
echo -n -e "${LEN16}${ENQUIRE_LINK}${NULL}${SEQ1}" >&3
Explanation: an ENQUIRE_LINK PDU consists of:
- 4 bytes to say the length of the whole PDU in bytes. ENQUIRE_LINK PDUs are always 16 bytes, “00000010” in hex. I called this LEN.
- 4 bytes to say what type of PDU this is. ENQUIRE_LINK is “00000015” in hex. I called this ENQUIRE_LINK.
- 4 bytes that are always zero in ENQUIRE_LINK. I called this NULL.
- 4 bytes that identify this request, called a sequence number. The response from the server will include this so we can match responses to requests. I called this SEQ.
Check back in the second terminal (where you ran nc). If everything worked, you should see something like this:
00000000: 0000 0010 8000 0015 0000 0000 0000 0001 ................
Ignoring the first and last parts (which are how xxd formats its output), the response we receive is four 4-byte parts, very similar to what we sent:
- 4 bytes to say the length of the whole PDU in bytes. Here it is “00000010” hex, or 16 decimal.
- 4 bytes to say what type of PDU this is. Here is is ENQUIRE_LINK is “80000015” in hex, which is the code for ENQUIRE_LINK_RESP.
- 4 bytes for the success status of the ENQUIRE_LINK_RESP. This is always “00000000”, which means success and is called ESME_ROK in the spec.
- 4 bytes that match the sequence number we sent. This is “00000001”, as we expected.
BIND_TRANSCEIVER
Now we can see that the SMSC is working, let’s “bind” to it. That means something like logging in: we convince the SMSC that we are a legitimate client, and tell it what type of connection we want, and, assuming it agrees, it will hold the connection open for us for as long as we need.
We are going to bind as a transceiver, which means both a transmitter and receiver, so we can both send messages and receive responses.
Send the bind request like this:
LEN32='\x00\x00\x00\x20'
BIND_TRANSCEIVER='\x00\x00\x00\x09'
NULL='\x00\x00\x00\x00'
SEQ2='\x00\x00\x00\x02'
SYSTEM_ID="sys\x00"
PASSWORD="pas\x00"
SYSTEM_TYPE='typ\x00'
SYSTEM_ID='sys\x00'
PASSWORD='pas\x00'
INTERFACE_VERSION='\x01'
INTERFACE_VERSION='\x34'
ADDR_TON='\x00'
ADDR_NPI='\x00'
ADDRESS_RANGE='\x00'
echo -n -e "${LEN32}${BIND_TRANSCEIVER}${NULL}${SEQ2}${SYSTEM_ID}${PASSWORD}${SYSTEM_TYPE}${INTERFACE_VERSION}${ADDR_TON}${ADDR_NPI}${ADDRESS_RANGE}" >&3
Explanation: this PDU is 32 bytes long, so the first thing we send is “00000020” hex, which is 32.
Then we send “00000009” for the type: BIND_TRANSCEIVER, 4 bytes of zeros, and a sequence number – this time I used 2.
That was the header. Now the body of the PDU starts with a system id (basically a username), a password, and a system type (extra info about who you are). These are all variable-length null-terminated strings, so I ended each one with \x00.
The rest of the body is some options about the types of phone number we will be sending from and sending to – I made them all “00” hex, which means “we don’t know”.
If it worked, you should see this in the nc output:
00000000: 0000 0021 8000 0009 0000 0000 0000 0002 ...!............
00000010: 636c 6f75 6468 6f70 7065 7200 0210 0001 cloudhopper.....
As before, the first 4 bytes are for how long the PDU is – 33 bytes – and the next 4 bytes are for what type of PDU this is – “80000009” is for BIND_TRANSCEIVER_RESP which is the response to a BIND_TRANSCEIVER.
The next 4 bytes are for the status – these are zeroes which indicates success (ESME_ROK) again. After that is our sequence number (2).
The next 15 bytes are the characters of the word “cloudhopper” followed by a zero – this is the system id of the SMSC.
The next byte (“01”) – the last one we can see – is the beginning of a “TLV”, or optional part of the response. xxd actually delayed the last byte of the output, so we can’t see it yet, but it is “34”. Together, “0134” means “the interface version we support is SMPP 3.4”.
SUBMIT_SM
The reason why we’re here is to send a message. To do that, we use a SUBMIT_SM:
LEN61='\x00\x00\x00\x3d'
SUBMIT_SM='\x00\x00\x00\x04'
SEQ3='\x00\x00\x00\x03'
SERVICE_TYPE='\x00'
SOURCE_ADDR_TON='\x00'
SOURCE_ADDR_NPI='\x00'
SOURCE_ADDR='447000123123\x00'
DEST_ADDR_TON='\x00'
DEST_ADDR_NPI='\x00'
DESTINATION_ADDR='447111222222\x00'
ESM_CLASS='\x00'
PROTOCOL_ID='\x01'
PRIORITY_FLAG='\x01'
SCHEDULE_DELIVERY_TIME='\x00'
VALIDITY_PERIOD='\x00'
REGISTERED_DELIVERY='\x01'
REPLACE_IF_PRESENT_FLAG='\x00'
DATA_CODING='\x03'
SM_DEFAULT_MSG_ID='\x00'
SM_LENGTH='\x04'
SHORT_MESSAGE='hihi'
echo -n -e "${LEN61}${SUBMIT_SM}${NULL}${SEQ3}${SERVICE_TYPE}${SOURCE_ADDR_TON}${SOURCE_ADDR_NPI}${SOURCE_ADDR}${DEST_ADDR_TON}${DEST_ADDR_NPI}${DESTINATION_ADDR}${ESM_CLASS}${PROTOCOL_ID}${PRIORITY_FLAG}${SCHEDULE_DELIVERY_TIME}${VALIDITY_PERIOD}${REGISTERED_DELIVERY}${REPLACE_IF_PRESENT_FLAG}${DATA_CODING}${SM_DEFAULT_MSG_ID}${SM_LENGTH}${SHORT_MESSAGE}" >&3
LEN61 is the length in bytes of the PDU, SUBMIT_SM is the type of PDU, and SEQ3 is a sequence number, as before.
SOURCE_ADDR is a null-terminated (i.e. it ends with a zero byte) string of ASCII characters saying who the message is from. This can be a phone number, or a name (but the rules about what names are allowed are complicated and region-specific). SOURCE_ADDR_TON and SOURCE_ADDR_NPI give information about what type of address we are providing – we set them to zero to mean “we don’t know”.
DESTINATION_ADDR, DEST_ADDR_TON and DEST_ADDR_NPI describe the phone number we are sending to.
ESM_CLASS tells the SMSC how to treat your message – we use “store and forward” mode, which means keep it and send it when you can.
PROTOCOL_ID tells it what to do if it finds duplicate messages – we use “Replace Short Message Type 1”, which I guess means use the latest version you received.
PRIORITY_FLAG means how important the message is – we used “interactive”.
SCHEDULE_DELIVERY_TIME is when to send – we say “immediate”.
VALIDITY_PERIOD means how long should this message live before we give up trying to send it (e.g. if the user’s phone is off). We use “default” so the SMSC will do something sensible.
REGISTERED_DELIVERY gives information about whether we want a receipt saying the message arrived on the phone. We say “yes please”.
REPLACE_IF_PRESENT_FLAG is also about duplicate messages (I’m not sure how it interacts with PROTOCOL_ID) – the value we used means “don’t replace”.
DATA_CODING states what character encoding you are using to send the message text – we used “Latin 1”, which means ISO-8859-1.
SM_DEFAULT_MSG_ID allows us to use one of a handful of hard-coded standard messages – we say “no, use a custom one”.
SM_LENGTH is the length in bytes of the “short message” – the actual text that the user will see on the phone screen.
SHORT_MESSAGE is the short message itself – our message is all ASCII characters, but we could use any bytes and they will be interpreted as characters in ISO-8859-1 encoding.
You should see a response in the other terminal like this:
00000020: 3400 0000 1180 0000 0400 0000 0000 0000 4...............
The initial “34” is the left-over byte from the previous message as mentioned above. After that, we have:
“00000011” for the length of this PDU (11 bytes).
“80000004” for the type – SUBMIT_SM_RESP which tells us whether the message was accepted (but not whether it was received).
“00000000” for the status – zero means “OK”.
The last two bytes are chopped off again, but what we actually get back is:
“00000003”, which is the sequence number, and then:
“00” which is a null-terminated ASCII message ID: in this case the SMSC is saying that the ID it has given this message is “”, which is probably not very helpful! If this ID were not empty, it would help us later if we receive a delivery receipt, or if we want to ask about the message, or change or cancel it.
DELIVER_SM
If you stop the SMSC process (the one we started with make server) by pressing Ctrl-C, and start a different one with make server-echo, and then repeat the other commands (note you need to be quick because you only get 5 seconds to bind before it gives up on you – make similar changes to what we did in ServerMain to ServerEchoMain if this causes problems), you will receive a delivery receipt from the server, which looks like this:
“0000003d” for the length of this PDU (59 bytes).
“00000005” for the type (DELIVER_SM).
“00000000” for the unused command status.
“00000001” as a sequence number. Note, this is unrelated the sequence number of the original message: to match with the original message, we must use the message ID provided in the SUBMIT_SM_RESP.
“0000003400” to mean we are using SMPP 3.4. (This is a null-terminated string of bytes.)
“00” and “00” for the TON and NPI of the source address, followed by the source address itself, which is a null-terminated ASCII string: “34343731313132323232323200”. This translates to “447111222222”, which was the destination address of our original message. Note: some SMSCs switch the source and destination addresses like this in their delivery receipts, and some don’t, which makes life interesting.
“00” and “00” for the TOM and NPI of the destination address, followed by “34343730303031323331323300” for the address itself, which translates to “447000123123”, as expected.
The DELIVER_SM PDU continues with much of the information repeated from the original message, and the SMSC is allowed to providing a short message as part of the receipt – in our example the cloudhopper SMSC repeats the original message. Some SMSCs use the short message to provide information such as the message ID and the delivery time, but there is no formal standard for how to provide it. Other SMSCs use a TLV to provide the message ID instead.
In order to complete the conversation, you should provide a DELIVER_SM_RESP, and then an UNBIND, but hopefully based on what we’ve done and the SMPP 3.4 standard, you should be able to figure it out.
You did it
SMPP is a binary protocol layered directly on top of TCP, which makes it slightly harder to work with by hand than the HTTP protocols with which many of us are more familiar, but I hope I’ve convinced you it’s possible to understand what’s going on without resorting to some kind of heavyweight debugging tool or library.
Happy texting!
