What Is a Service

In the context of software, service is a computer message invocation that is sent over a telecommunications networking protocol connection (e.g., TCP/IP or UDP/IP socket) to a remote computer. This message invocation has the intent of stimulating an application or multiple applications that are sitting on remote machines to perform some operation. That is, the remote application, upon receipt of the requested message, is expected to parse and process the message accordingly. And then it may either simply process the message and return no response, it could return a response message to the invoker.  Sometimes, the application may even forward that message to another systems for processing.

Based on the above definition of a service, we may have several different communication protocols that could used for the transfer of the request and response service messages between the remote computing ends.  Below are some common communication protocols that have been used in more recent computing:

• REST over HTTP
• SOAP over HTTP
• CORBA
• Some private messaging protocol over HTTP
• Some private messaging protocol over TCP/IP socket
• HL7 used in the healthcare arena
• SNMP used in the network management arena

CRUD

The essence of any service is based on the CRUD terminology. CRUD stands for Create, Read, Update and Delete. Most of the service APIs fall into one of the CRUD categories. For example:

• Create: AddAccount, CreateAccount
• Read: GetAccount, ReadAccount, RetrieveAccount
• Update: SaveAccount, UpdateAccount, ModifyAccount
• Delete: DeleteAccount, RemoveAccount

As we can see from the CRUD message APIs above, there are many different ways that the same service message can be named. The service API designer should therefore be careful to follow a consistent approach when naming the APIs. Otherwise, we may end up with several different names that mean the same thing (e.g. Create/Add or Get/Read or Delete/Remove).

Service Semantics and Behavior

A service should be well defined and understood, which means that its semantics and behavior should be clearly stated.

• Semantics: It consists of the all the wording that is used to define a service. For example, the service message name, message attributes names and types, and any type of errors (or exceptions) that might be incurred as a result of invoking that service. For example, when creating a customer login, the semantics might be defined as follows "createCustomerLogin(username, password, email), where the username, password and email are all text data defined by certain constraints; e.g., number of characters and character encoding scheme.

Notice, that in the above semantics we are not concerned about the underlying technical implementation of that service. In the "service contract" document, we would then add a section that provides specifics of the semantics implementation. In that case, we would define request/response messages using a WSDL language (SOAP), or use the IDL language for a CORBA service. For RESTFul, we would implement the service semantics in terms of its URI with HTTP header/POST body (request) and corresponding HTTP headers/body (response) along with the media type (e.g., JSON or XML).

• Behavior: It consists of the expected actions that might occur as a result of invoking a given service message. In this case, we want to elaborate on what activities might occur as the outcome of invoking the service. For example, in the case of creating a customer login, we would elaborate that an account with a unique user name is created on a given computer system. Or in multiple computer systems, depending on the business case being solved.

Characteristics of Good Services

A service should, foremost, address a specific business need. A service is therefore a means to an end; that is, it should address and solve a business requirement. Throughout the design and implementation of a service, the implementer should keep in mind the business audience who will consume that service, and aim the naming of the service API to that business audience.  That is, service request/response messages, attributes, and resources should have names that are meaningful and aimed at the business audience who will be consuming that service API.  Furthermore, the service API should be, whenever possible, validated with the business parties; that is, the programmers or business analysts  who will be ultimately using that service API.  The goal here is to ensure that the service API is not only well aligned with the business needs, but that it is easy to use and be programmed with.    The service API designer or implementer should refrain from trying to map a backend application API to a service API.

A side effect of using service enabler infrastructure computing (e.g., ESB, enterprise service buses) is  the use of what is called "technical services".  These type of services are used to collect technical information, such as performance analytic, logs, errors and other troubleshooting information from the underlying service enabler infrastructure.

Service Patterns

By service patterns, it is meant good practices and tips that are followed in the market to name a few of the service messages APIs and protocols.

Resource API Pattern

The Resource API Pattern is implemented by RESTFul web services. That is, the API is operating on a given resource (e.g. Account, User, Report, and so on). And the CRUD behaviour is leveraged by the underlying HTTP Protocol. That is, for HTTP the CRUD is as follows:

• Create: Post
• Read: Get
• Update: Put
• Delete: Delete

RPC API Pattern

The RPC (Remote Procedure Call) ..

Rubens Gomes

How to Set Up RESTClient for SSL Connections

The WizTools.org RESTClient 2.3.3 is a GUI application written in Java that helps with the testing of HTTP RESTful services.

Installation of RESTClient

Prerequisites

Prior to installing RESTClient, you should have the latest version of Java 6 JRE (or Java 7) installed on your computer. I recommend to install the java 6 JRE on the following folder "c:\java\jre6" (Windows) or "${HOME}/java/jre6" (UNIX). Ensure you have the latest version of java installed by running the following
comand from the system prompt. In my case, I verified below that my PC has a current version of Java 6 by entering the following command in my cygwin (Linux-Like) shell:

$ java -version
java version "1.6.0_30"
Java(TM) SE Runtime Environment (build 1.6.0_30-b12)
Java HotSpot(TM) 64-Bit Server VM (build 20.5-b03, mixed mode)

Installing RESTClient

In order to use the RESTClient GUI application you should first download the file "restclient-ui-2.3.3-jar-with-dependencies.jar" from the following page. I recommend you place the restclient jar file in a folder named "java\restclient" (Windows) or "java/restclient" (UNIX). For instance, "C:\java\restclient" (PC) or "${HOME}/java/restclient" (UNIX).

http://code.google.com/p/rest-client/downloads/list

Once you have the above jar file downloaded and saved in the above directory, you can run the RESTClient GUI by going into that folder, and running the command "java -jar restclient-ui-2.3.3-jar-with-dependencies.jar". For example, in my PC windows cygwin (Linux-like) shell, I run the following commands:

$ cd c:/java/restclient

$ pwd; ls -l
/cygdrive/c/java/restclient
total 8736
-rwx------+ 1 Administrators Domain Users 8944764 Jan 13 17:29 restclient-ui-2.3.3-jar-with-dependencies.jar

$ java -jar restclient-ui-2.3.3-jar-with-dependencies.jar

Importing SSL Certificate into a Local Keystore

Prior to being able to establish an SSL connection to your HTTP server from RESTClient, you must first have the server certificate exported from your browser to a local folder in your PC. Then, you need to import that certificate to a local SSL store file. After that, you will point the RESTClient to that SSL store file in order to be able to establish an SSL connection.

In the steps below, I am explaining how I exported and imported the server public certificate using Firefox version 3.6.3. I have only tested this procedure from Firefox.

Exporting an SSL certificate file from FireFox

First, you should hit the application server using an HTTPS scheme to upload and save the certificate in the browser. If your certificate was not generated from an authenticated SSL source (godaddy.com, for example), you will see a window with a message about "This Connection is Untrusted.... blah, blah, blah...." Simply select "I Understand the Risks", and "Confirm Security Exception".

Now, at the browser navigation bar (where you type the URL), you should see the left of the URL a little icon to indicate the SSL connection for that URL. Click on that icon to open up a window that contains information about that SSL certificate. Click on the "More Information ..." button to open up a window with a few tabs at the top. You should now be at the "Security" tab. Click on the "View Certificate" button to open up a window that contains your certificate information. Click on that window "Details" tab. After that, click on "Export...", and save that file to a temporary folder in your computer (e.g., "C:\tmp" or "/tmp"). Keep the Save as type "X.509 Certificate (PEM)" selected, and name the file however you like. For example, I named mine as "restclient", and Firefox automatically appended the extension "crt" to the filename.

That is it for exporting the SSL certificate to a local file. Now, the next step is to import the SSL certificate in that file to a local java keystore that will be used by the RESTClient application.

Importing PEM Firefox certificate into Java Keystore

In order to import the PEM certificate exported earlier into a keystore, you will need to have access to the java "keytool.exe" command from your system prompt. You will need to specify a "keystore" filename that you will later configure on the RESTClient application. The steps below illustrates the commands that I had to do on my cygwin (Linux-Like) shell to import this PEM certificate to a local java keystore.

$ pwd
/cygdrive/c/tmp
rugomes@rugomes-WS /cygdrive/c/tmp

$ ls -l restclient.crt
-rwx------+ 1 Administrators Domain Users 1336 Jan 25 18:15 restclient.crt

Now, type the command below to import the SSL certificate into a keystore called "c:/java/restclient.store". Notice that I am using cygwin (Linux-Like) shell, and the folders are separated by "/". If you use the Windows command shell, you would name that keystore as "C:\java\restclient.store" instead.

When prompted for the keystore password, simply type changeit.

$ keytool -noprompt -import -keystore "c:/java/restclient.store" -alias restclient -file restclient.crt
Enter keystore password: changeit
Re-enter new password: changeit
Certificate was added to keystore

To verify that your certificate was properly added to the above keystore (e.g., "C:\java\restclient.store"), type the following command. In my case, I am typing the following command from my cygwin (Linux-Like) shell. When prompted for the password, enter the same password typed previously "changeit".

The information about the certificate just imported should be displayed on your computer. I am not showing that entire screen here for security reasons (that is, I don't want to reveal the details of my certificate).

$ keytool -list -v -keystore "c:/java/restclient.store"
Enter keystore password: changeit
Keystore type: JKS
Keystore provider: SUN
Your keystore contains 1 entry
Alias name: restclient
Creation date: Jan 25, 2012
Entry type: trustedCertEntry
Owner: ...
Issuer: ...
Serial number: ...
Valid from: Fri Jan 20 17:00:01 EST 2012 until: Mon Jan 17 17:00:01 EST 2022
Certificate fingerprints:blah, blah, blah...

Configuring the SSL store on RESTClient

Now that we have the above certificate store created with the proper certificate, we can go to the step of configuring that store on the RESTClient GUI. For this step, you need to run the RESTClient GUI application, and go to the SSL tab window. Here is how I ran the RESTClient GUI from my Cygwin Linux-Like shell:

$ cd c:
rugomes@rugomes-WS /cygdrive/c
$ cd java/restclient
rugomes@rugomes-WS /cygdrive/c/java/restclient
$ java -jar restclient-ui-2.3.3-jar-with-dependencies.jar

Once the RESTClient GUI window shows up, select the "SSL tab". Then click the little button to the right of the "Trust store file: " prompt, and navigate thru the windows to select the above certificate keystore filename (e.g. C:\java\restclient.store).

Under the "Trust store password:", type the password "changeit" that was used during the above step when you created the keystore and imported the certificate into it. Then, you may want to select "Strict" for the Hostname verifier. Here is what each option under "Hostanem verifier" means:

ALLOW_ALL: The URL requested doesn't need to match the URL in the Certificate.
STRICT: The URL requested needs to match the URL in the Certificate.
BROWSER_COMPATIBLE: The URL requested must be in the same domain

Now, enter the https URL to the URL prompt under the same SSL tab window, and you should see the response from your HTTP/SSL connection. For example, in my case, I entered a URL similar to the following in the URL prompt of the RESTClient GUI:

https://{host}:{port}//rest/reports/test?outputType=csv

Please, note that you may need to configure other headers as required by your HTTP RESTful Web Service. For example, in my case I also had to configure Auth Type BASIC, and enter a Username and Password in the Auth tab window.

Happy SSL REST testing :)


Rubens.

What Is a Literal in Computer Programming?

In computer programming languages, a literal refers to a piece of information (such as a word, digit) that is written exactly as it is meant to be interpreted.

Below are some statements followed by comments (text starting with //). In Java a statement is a text ending with a ";". A statement is a complete sentence that provides a command (or instruction) to be executed by a computer. Comments is any text not interpreted nor executed by a computer. It is there solely for readability purposes. The computer skips everything that starts with "//" until the end of the line.

int x;

// int is a type

// x is a variable

x = 1; 

// 1 is an integer literal

String text = "abc";

// text is a variable

// = is an operator

// "abc" is a literal

Long nr = null;
// nr is a variable
// null is a literal

boolean var = true; 

// boolean is a type

// var is variable

// = is an operator

// true is a literal

As you can see, "1" is a integer number whose value is also 1. Therefore, 1 is a literal. "null" is a special kind of literal that has a value of 0 (zero). In the case above, assigning "null" literal to the variable "nr" implies that the computer should use the corresponding value of null (most of the times 0) and assign it to the variable. Other types of literal in java is true or false. In the case above the computer will assign "true" to the boolean typed variable called "var".

Rubens Gomes

EZLista a Free Online Address Book for your smartphone

I have developed a free online address book on the Internet called EZLista (http://www.ezlista.com/). EZLista is an Internet address book where you save and access your contacts from your smartphone (mobile cell phone) or desktop anywhere you have Internet access. The site was developed with easy and security in mind. Your information is safe at EZLista. All the user/password information is encrypted at our server. They are also encrypted during transit on the Internet. EZLista requests users to confirm their email as a safe measurement to ensure that no one uses third party emails in the system.

When you are on the streets you may use your smartphone (mobile cell phone) to access your contacts. EZLista provides an easy interface that renders a mobile web site on most cellular phones in the market. All you need is an Internet browser on your phone.

EZLista is a free address book for desktop and smartphones.

http://www.ezlista.com/

Setting Up SELinux httpd with tomcat and SVN modules

I have an IBM x342 server running CentOS 5. In this machine, I have configured SELinux running in "enforcing" mode along with a "targeted" policy type. And I am using SELinux to manage the security around the httpd process. I am using Apache HTTPd 2.2 as the entry point for all SVN (subversion), tomcat and static page requests.

Here are my configurations for httpd + svn (over SSL):

1) SVN repository: /var/svn/repository.

2) Changed the user/group ownership of the repository directory to "apache" (which is the user/group that owns the 'httpd' daemon)

3) Changed the security context of the svn repository as follows:
$ chcon -v -R -h -t public_content_rw_t /var/svn/repository/
$ ls -Z /var/svn/repository/
drwxr-xr-x apache apache system_u:object_r:public_content_rw_t:DefaultCategory conf
-- DefaultCategory is just an alias I gave to the s0 category.

4) Configure mod_ssl as follows:
LoadModule ssl_module modules/mod_ssl.so
Listen 443
AddType application/x-x509-ca-cert .crt
AddType application/x-pkcs7-crl .crl
SSLPassPhraseDialog builtin
SSLSessionCache shmcb:/var/cache/mod_ssl/scache(512000)
SSLSessionCacheTimeout 300
SSLMutex default
SSLRandomSeed startup file:/dev/urandom 256
SSLRandomSeed connect builtin
SSLCryptoDevice builtin
ErrorLog logs/ssl_error_log
TransferLog logs/ssl_access_log
LogLevel warn
SSLEngine on
SSLProtocol all
SSLCipherSuite ALL:!ADH:!EXPORT:!SSLv2:RC4+RSA:+HIGH:+MEDIUM:+LOW
SSLCertificateFile /etc/pki/tls/certs/localhost.crt
SSLCertificateKeyFile /etc/pki/tls/private/localhost.key
SSLOptions +StdEnvVars
SSLOptions +StdEnvVars
SetEnvIf User-Agent ".*MSIE.*" \
nokeepalive ssl-unclean-shutdown \
downgrade-1.0 force-response-1.0
CustomLog logs/ssl_request_log \
"%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"

5) Configured dav_svn.conf as follows:
LoadModule dav_svn_module /usr/lib/httpd/modules/mod_dav_svn.so
LoadModule authz_svn_module /usr/lib/httpd/modules/mod_authz_svn.so
# BASIC htpasswd authentication over SSL
DAV svn
SVNPath /var/svn/repository
SSLRequireSSL
AuthType Basic
AuthName "Subversion repository"
AuthUserFile /etc/svn-auth-file
Require valid-user

I found SELinux to be a very interesting technology. I would strongly advise you to read the SELinux docs on RedHat before you jump into configuring security contexts, policies and categories. Also, you should enable the "setroubleshootd" service - this service along with the X SELinux Troubleshooter is a *must* to help you debug avc denies errors.

I will add further information on how to configure httpd with the tomcat module (mod_jk) later on.