\chapter{Using the H\_IN: an example}\label{chap:h-in-example}

\begin{quote}

  Nihil nobis metuendum est, pr{\ae}ter metum ipsum.\\

  -- Julius Caesar

\end{quote}

In chapter~\ref{chap:h-in}, we discussed the {\tt h\_in}-API and in

chapter~\ref{chap:messages} we went through the message syntax. 

In this chapter we combine and apply that knowledge in a

simple\footnote{simple in concept, not so much in implementation} example. We

hope that this clarifies the material shown before, and also answers some of

the greater questions of where this all leads to.

{\bf Caveat lector:} this chapter discusses the details of programming NoTA

using the {\tt H\_IN}-API directly. This is good for understanding the

backgrounds, but you may not need all of that. You can use the {\bf stub

  generator} (discussed in chapter~\ref{chap:stubgen}) instead, which hides

many of the low-level details

The previous chapters are a prerequisite for understanding this chapter; you

might also find it useful to have the {\tt h\_in}-man pages available. The

man-pages are part of your NoTA-installation; see

appendix~\ref{chap:installation} for details.

\section{Caesar cypher}\index{Caesar cypher}

To gain some good understanding of the {\tt h\_in} \index{high-level

interconnect}, simple examples work best. So, we hope that you can forgive

us that the example is rather useless as a real-world use case. And, already

in the simple example, the implementation gets rather complicated.

For the example in this chapter, we will use a service node (SN) that

implements a {\em Caesar cypher}\footnote{for some background, see: {\tt

http://en.wikipedia.org/wiki/Caesar\_cipher}}\index{Caesar cypher} - a simple

encryption technique where the characters in a string (circularly) shifted

over some fixed number of positions up or down the alphabet.

Now, suppose we want to implement a server that can handle the encryption

operation. It should handle messages\index{message} of the form:

\begin{verbatim}

     caesar_crypt_req (bdat1 text, int8 shift);

\end{verbatim}

Some notes:

\begin{itemize}

\item it would be natural to think of this as a {\em function}, but for our

  purposes, it's better to think of as a {\em message}. For example, it does

  not have a return value;

\item we call the function {\tt caesar\_crypt\_{\bf req}} to emphasize that it

  is a {\bf request}; note that it can be used for both encryption and

  decryption;

\item we only support the 26 lower-case characters in the English

  alphabet, so {\tt shift} parameter has an effective range of [-25, 25].

\end{itemize}

Now, after the service node has received such a {\tt

caesar\_crypt\_req}-message and all the parameters are correct, it can execute

the operation and respond with a message:

\begin{verbatim}

    caesar_crypt_rsp (bdat1 text);

\end{verbatim}

Of course, it could be that we received {\em incorrect} parameters. For

example, the text should not contain a characters outside the {\tt

  [a-z]}-range, and the shift parameter should be in range as well. In case of

such a problem, we can respond with an error notification:

\begin{verbatim}

    caesar_crypt_error_rsp (uint8 code);

\end{verbatim}

Summarizing, there are three messages: two to be handled by the server (SN),

one by the client. 

\section{Implementation}

Now, let's look at implementing an AN and an SN for this, to show how it all

works. For our implementation, we use plain C, and we're assuming a

UNIX/Linux-like environment. We need to do the following:

\begin{itemize}

    \item write the common definitions;

    \item write the service node;

    \item write the client node.

\end{itemize}

You could choose a different order, of course.

\subsection{Common definitions}

The first thing we should do is to identify the common things that are needed

for both AN and SN, put those in a common header file  {\tt caesar-common.h}.

The first thing we need to do, is to define an address\footnote{In a more

realistic case, you could get the address from the resource manager (discussed

in chapter~\ref{chap:rm})} for the SN -- a {\tt nota\_addr\_t} that the AN can

use to find it, similar to having a IP-number in a network.

For this example, we simply hard-code it. As we saw in in the previous

chapter, a NoTA-address is defined as an array of two numbers. So, we define

our service address (arbitrarily):

\begin{lstlisting}

        #define CAESAR_SN_ADDRESS   {1,1}

\end{lstlisting}

The other common definitions are the signal-id's for the three messages we

need:

\begin{lstlisting}

/* signal id's: */

/* (1) implemented by the SN */

#define	CAESAR_CRYPT_REQ_SIGID        0x0001

/* (2) implemented by the AN */

#define	CAESAR_CRYPT_RSP_SIGID        0x0002  

#define	CAESAR_CRYPT_ERROR_RSP_SIGID  0x0003

\end{lstlisting}

We also declare the \texttt{caesar\_handle\_message}-function, which we can

reuse in both AN and SN.

That's all for {\tt caesar-common.h}.

\subsection{Writing a service node}

\subsubsection{Service node socket handling}

Now, let's see how we can write a service node\index{service node}. If you

have ever written servers using BSD-sockets, this will all look very

familiar. If you are not familiar with BSD-sockets, see

\cite{Beej2009}\footnote{direct URL: http://www.beej.us/guide/bgnet/} for a

gentle introduction.

In the following, we'll go through this implementation. The full source code

is available in appendix~\ref{chap:example}; here we show a slightly shorter

version -- without error checking. The example {\bf has} error-checking

though, as it is very important, especially since examples are sometimes

copy-pasted for use in 'real' programs...

The first thing is {\em not} in BSD though --  we start by getting a NoTA

instance pointer:

\begin{lstlisting}

    h_in_t *inst;

    inst = Hgetinstance ();

\end{lstlisting}

Easy. If that went well, we can ask NoTA to give us a a socket.

\begin{lstlisting}

    int sock;

    sock = Hsocket (inst, AF_NOTA, SOCK_SEQPACKET, 0);

\end{lstlisting}

Note that we are using {\tt SOCK\_SEQPACKET} here; as explained in the

previous chapter, this is the best choice when a socket is meant for messages

as in this case, as the system guarantees that we get the {\bf whole message

in one go}.

The alternative, {\tt SOCK\_STREAM}, is more efficient for sending bulk data,

such as files and multimedia content.

Now we have our socket, and like to {\em bind} it to some address - we're

telling the system that this sockets has some particular address. For that,

there is the {\tt Hbind}-function:

\begin{lstlisting} 

  nota_addr_t addr = CAESAR_SN_ADDRESS;

  Hbind (inst, sock, (struct sockaddr*)&addr, sizeof(addr));

\end{lstlisting}

This will bind our socket to {\tt CAESAR\_SN\_ADDRESS}, so the AN can find it.

Before that, we have to put the socket in {\em listening mode}, using {\tt

  Hlisten}:

\begin{lstlisting}

   Hlisten (inst, sock, 1);

\end{lstlisting}

We set the last {\em backlog} parameter to 1, but it's not really important

in this simple example.

Now, we have done all the preparatory things, and we can start listening on

the socket for incoming messages. We use the simplest possible way of doing

that: using {\tt Haccept}:

\begin{lstlisting}

   int peersock;

   peersock = Haccept (inst, sock, NULL, NULL);

\end{lstlisting}

This function will {\bf block} (i.e., wait) for an incoming connection. When

there is an incoming connection, it will return a socket in {\tt peersock},

which is the socket over which the communication with the other side (the

peer) can take place.

Note that the last two parameters are {\tt NULL}, as they are ignored in NoTA

(not in BSD) - see the previous chapter for the details.

After we accepted a connection (with {\tt Haccept}), we need to decode the

bytes we get and figure out what to do with them. This is discussed in the

next paragraph; here, we continue with the discussion of the socket handling.

Finally, when we are done with our with our SN, we can close the socket with

{\tt Hclose}: 

\begin{lstlisting}

  Hclose (inst, sock);

\end{lstlisting} 

In this example, we never really reach that code, as the SN will only be

terminated by manual interaction (e.g.., {\tt Ctrl-C}), and all it's sockets

will be closed then. 

\subsubsection{Service node message handling}\label{subsubsec:snmsghandling}

So, we accepted a connection from 'the other side'. We'd now like to read the

bytes available, and decode that into a message (if needed, consult

chapter~\ref{chap:messages} for the details on coding/decoding).

In both the service node and the application node, we will need message

handling, so we define a function \texttt{caesar\_get\_message} in

\texttt{caesar-common.h}; see the appendix for the actual code, but you will

probably agree that it requires some careful coding to read NoTA-messages.

\texttt{caesar\_get\_message} returns us the signal-id for the received

message; we then need to write the code for the various message handling

functions to extract the parameters from the data. This is rather tedious, as

we have to be check at each step; we can never assume that the data is

correct. For example, BDAT-values have their length embedded --if we blindly

accept that value, it would easily lead to buffer overflows\index{buffer

overflow}.

We defined only one possible message for the service node: 

\begin{verbatim}

  caesar_crypt_req (bdat1 text, int8 shift);

\end{verbatim}

What would the corresponding bytes look like? Well:

\begin{itemize}

  \item the message should start with the typecode for a signal-id, followed

    by the signal-id itself. As we've seen, the typecode for a two-byte signal

    id is {\tt 0xa2}. And we defined the signal id as {\tt

      CAESAR\_CRYPT\_REQ\_SIGID} (value: {\tt 0x0001});

  \item then follows the {\tt text} parameter, the string in a {\tt BDAT1}; this will

    be encoded as {\tt 0x41} followed by one byte for the {\em length}, and

    then the bytes for the string itself;

  \item finally, there is the {\tt shift} parameter, which is in {\tt INT8};

    this will be encoded as {\tt 0x21} followed by one byte for the value.

\end{itemize}

To put it all together:

\begin{tabular} {| l | l | l |}

  \hline

  {\tt 0xa2} {\tt 0x0001} & {\tt 0x41} {\em n} {\em $bytes_{1\dots n}$} & {\tt

    0x21} {\em byte} \\

  \hline

\end{tabular}

Using this information, we can read the bytes from the socket using {\tt

Hrecv}. This is rather tedious, as we must verify that we get what we are

supposed to get. The Service Node cannot make any assumptions on the validity

of the data.

\subsubsection{{\tt caesar-sn.c}}

Now, we have discussed all the relevant details for writing the Caesar service

node; see {\tt caesar-sn.c} in appendix~\ref{chap:example}. Additionally,

appendix~\ref{chap:building} has information on how to build the examples,

link with the NoTA-libraries and so on.

\subsection{Writing an application node}\label{subsec:appnode}

We have seen how we can write the service node for our Caesar example. We now

continue with the application node\index{application node}. As before, we go

through the relevant details here, and then refer to

appendix~\ref{chap:example} for the actual source code. And as before, the

code is bit tedious because of the manual processing of the bytes in the

message.

We go through the code once more. We omit the error handling here, but there

{\bf is} error handling in the example code. The first implementation steps

for the AN are the same as those for the SN: we need to get an instance

pointer\index{instance pointer} and a socket\index{socket}:

\begin{lstlisting}

 h_in_t *inst;

 int sock;

 inst = Hgetinstance ();

 sock = Hsocket (inst, AF_NOTA, SOCK_SEQPACKET, 0);

\end{lstlisting}

Again, we are using {\tt SOCK\_SEQPACKET}, which is the best choice for NoTA

messages.

For an application node, we usually don't care about its (source) port;

therefore it is {\em not necessary} to call {\tt Hbind} to connect it to a

particular port. We'll happily leave that to NoTA. Also, we don't need to call

{\tt Hlisten} to put our socket in {\em listening mode}, because the AN

initiates the connection.

We can now connect to the Service Node using {\tt Hconnect}:

\begin{lstlisting}

  nota_addr_t addr = CAESAR_SN_ADDRESS;

  Hconnect (inst, sock, (struct sockaddr*)&addr, sizeof(addr));

\end{lstlisting}

When {\tt Hconnect} has succeeded, we are ready to send our messages to the

SN. We have already seen how to {\em de}code a message in the discussion about

the service node; now we need to {\em en}code such a message.     

\subsubsection{Sending requests to the service node}

Remember, the message for the service node looks like the following: 

\begin{verbatim}

  caesar_crypt_req (bdat1 text, int8 shift);

\end{verbatim}

Obviously, the message we sent should have the same format as the one the SN

is to receive; have a look at the details in

paragraph~\ref{subsubsec:snmsghandling}. As we have seen, the final result

looks like this:

\begin{tabular} {| l | l | l |}

  \hline

  {\tt 0xa2} {\tt 0x0001} & {\tt 0x41} {\em n} {\em $bytes_{1\dots n}$} & {\tt

    0x21} {\em byte} \\

  \hline

\end{tabular}

We can send these bytes to the SN using {\tt Hsend}. Refer to

appendix~\ref{chap:example} for the source code.

\subsubsection{Handling responses from the service node}

\section{Compiling and running the example}

Now, let's see how we can run the Caesar cypher example.

\subsection{Compilation}

The first step is to {\em compile} the example. Please refer to

appendix\ref{chap:building} for general information about compiling NoTA-based

software, and see appendix~\ref{chap:example} for a {\tt Makefile} for the

Caesar cypher example. 

\subsection{Running}

TODO

\section{Questions}

To test your understanding of this chapter, you could try to answer some of

these questions. You can find the answers to these question in

appendix~\ref{chap:answers}.

\begin{enumerate}

    \item In the examples, we read from the socket using {\tt MSG\_WAITALL};

  however, we can be sure that it won't block in all but the first {\tt

  Hrecv}. Why can we be sure? (Hint: think about the kind of socket this is).

\item NoTA nodes (ANs and SNs) can communicate fully asynchronously; so how

  can the AN know which of the {\tt caesar\_crypt\_rsp} (or {\tt

    caesar\_crypt\_error\_rsp}) is a response to which {\tt

    caesar\_crypt\_rsp}?  (Hint: this is a trick question)

    \item Suppose that someone complains that our Caesar cypher is not secure

  enough. For extra security, we'd like to add the functionality to {\em

  revert} a text too. Adapt the Service Node such that it accepts a second

  message

\begin{verbatim}

    caesar_revert_req (bdat1 text);

\end{verbatim}

  which will cause the text to be reverted (for the signal id, you can use

  {\tt 0x0004}). Also, update the AN to send this message.

\item (Bonus question) The Caesar cypher with a shift parameter of 13 is

  better known as {\tt ROT-13}. What's the longest word you can find that has

  the property that its ROT-13 encoding is equal to the {\em reverse} of the

  word?

\end{enumerate}