tutorial

Apple Mail Encryption with GPGMail and OpenPGP

I've dabbled with encryption several times over the past few decades, never really getting serious about it.  It started when, in college, I would see that the faculty in the CS department had these weird signature blocks appended to the their USEnet posts containing something called a public key.

This is like setting a can of lighter fluid and box of blue-tip matches in front of a 10 year-old boy -- irresistible.

What I found in the later years is that using encryption for email is a lot like being one of the early adopters of the telephone.  Now that I have one, who am I going to call?  My family certainly doesn't use encryption in their email...those that have discovered email anyway.

Co-workers aren't likely to invest the time and effort into encryption simply because we're all too busy with work to be playing spy-games with our de-coder rings.

And, Dorothy, we're not in Academia anymore where, I imagine, it's really in use.  Closeted anarchists posting semi-heretical Berkeley-esqe rants against the Proletariat and all that.

And then there's the whole nouveau post-9/11 trend of "Guilty until Proven Innocent" thing happening.  I imagine some fedora-capped DHS agent squinting at me in a menacing fashion while I try to reason a plausible excuse for being so brazen as to need encryption for my emails in the first place...

So, at this point, let's assume that, like me, you're willing to whack the hornet's nest with a stick and use encryption for your emails and that you actually have someone on the other end willing to dust-off the de-coder ring and play with you.  We'll also assume that you know what PGP, GPG and OpenPGP actually are, and that you know how basic public-key encryption works.  (If not, leave comments to this article and I will do a future article explaining same.)

Standard Disclaimer: I am providing this tutorial as a hands-on, learn-with-me type of tutorial.  I am not an expert, nor do I pretend to claim anything other than neophyte status when it comes to encryption.  I do not advocate, support, or intend for you to use this, or any, technology as a means to intentionally bending, fracturing, or breaking laws in one or more jurisdictions.  MY only intent is to share what I've recently learned with you and to have some fun.

OK - that crap out of the way, let's get started.  First, as the title implies, this set-up is for Apple Mail under OS X Lion.  The release of the OS I'm currently working on is 10.7.4.

Download and install the GPGTools utility  (Version 2012.03.18 as of this writing.)

Although this article is for Apple mail, the GPGTools utility includes support for Enigmail in Thunderbird 7.  When you launch the installation utility, you'll be presented with a list of packages to install.  I installed all packages.

Once the install has been completed, you'll see a little dialog box appear on your desk top telling you the installation was successful, and would you like to read the Quickstart Tutorial?  This would be a good thing to do because I am not going to walk you thought the next steps in any great detail.  This reference, however, does.  With pictures.  So... go there and follow the installation step to:

Generate a key

You will generate a public and a private key.  Anyone with whom you wish to exchange encrypted email with must also have done the same.  They're called public and private keys for a reason.  One you share with the public and one you do not.  Key, using the nomenclature, are stored on what's called a keyring.  There are public and private key-rings.  GPGTools refers to key-rings as  keychains - these are one and the same things.

Please note that for whichever email account you're going to use to generate a key-pair for, that account must already exist in Apple mail.  The email address is case-sensitive so make sure you type it in exactly as it is stored in Apple Mail -- otherwise, your encryption will not work.

Over the years, I have created several key-pairs for various email addresses I have had.  What's critically important to remember is this:  write down your pass-phrase.  Also, click on the Advanced options tab, and set an expiration date (a couple of years is fine and 4-years is the current default - point being: set an expiration date) for your keys.  That way if, after a few years, you return to a previous email account address, and you've certainly forgotten your passphrase from lack of use, then you'll still be able to generate a new key pair if the old one has expired.  To remove a key pair, most public key rings require you to enter your passphrase.  This is known as a conundrum.

Once you've created your passphrase and uploaded your key, and you can see your new key in your keychain, open Apple Mail.  Send an email to

the email address you've just created (I know...) and you should see two buttons appear in the lower-right corner of the header bar as shown in the image on the right.

The two buttons, as shown above, allow you to either sign or encrypt your mail message.

Signing your email is flagging the email to the recipient assuring them that it was actually you who sent the mail.  In order to sign an email, OpenPGP has to have access to your private key. (You did keep your private key private, right?)  Since you're the only one, presumably, with access to your private key, then signing the mail guarantees to the recipient that the mail did come from you.

The recipient does not need to have your public key, nor do you need to have the recipient's public key, to sign an email.  Think of this as the "certified mail" from the US Post Office equivalent for email.

If you have a recipient's public key, then you may send them an encrypted email.  The recipient will need to have your public key in order to decrypt and read the email -- this is why we store public keys on public key rings.

[codesyntax lang="text" lines="no" capitalize="no"]

-----BEGIN PGP SIGNATURE-----

Version: GnuPG/MacGPG2 v2.0.18 (Darwin)

iQEcBAEBAgAGBQJPtnyiAAoJEC4S4zGLhwvBFNMH/1Yoh59etAcYZpAhZ+htpd81
QzZWDxOR2PeXtPkY3GWl4vdW7GABJ9ysl8vpdErsDtXs6LEVZXag5mV6CGTDNXmm
pdozUJCgNwbHTgoIUdjinmAXLR+4pYSfALTB1S2qpxzMpykBkR7SMuPm3+0LC77/
dwnsSVx5CNtJd8cPoPjwXJ6zaStJCNK+H17MItS5kpw3MqMU35qZdNCDV6ehhA8j
FmTyFoh1TeTmuBrNECWz9z3KniG6SWVl3K21LmS8PQExeHq8qcHGBz5yK2YhoW/w
bn4PIyHaUiXKQTNhYBSd1DrCPUWJKDJ+VCKQ0L97aUPeVPQBI14jsFOgc1dwUjs=
=xfmB
-----END PGP SIGNATURE-----

[/codesyntax]

That's pretty much it -- once you send a signed an encrypted mail, you can rest assured that (hopefully) your emails are safe from casually-prying eyes as they're no longer being sent in clear-text across the ether sphere.

Here's the raw-text (what's sent out over the ether) of an encrypted email message:

 

[codesyntax lang="text" lines="no" capitalize="no"]

Return-Path: <mshallop@gmail.com>

Received: from [192.168.0.2] (c-50-136-203-107.hsd1.ca.comcast.net. [50.136.203.107])
by mx.google.com with ESMTPS id qu6sm6794406pbc.36.2012.05.18.09.54.57
(version=TLSv1/SSLv3 cipher=OTHER);
Fri, 18 May 2012 09:54:58 -0700 (PDT)
Content-Type: multipart/encrypted; boundary="Apple-Mail=_4C5344B9-76FE-43EF-8620-073841EBF944"; protocol="application/pgp-encrypted";
Subject: test both
Mime-Version: 1.0 (Apple Message framework v1278)
X-Pgp-Agent: GPGMail 201 (a30)
From: Micheal Shallop <mshallop@gmail.com>
Date: Fri, 18 May 2012 09:54:56 -0700
Content-Transfer-Encoding: 7bit
Message-Id: <407C94BA-32A1-4930-B9F6-BBFE7900D213@gmail.com>
Content-Description: OpenPGP encrypted message
To: Micheal Shallop <mshallop@gmail.com>
X-Mailer: Apple Mail (2.1278)

This is an OpenPGP/MIME encrypted message (RFC 2440 and 3156)
--Apple-Mail=_4C5344B9-76FE-43EF-8620-073841EBF944
Content-Transfer-Encoding: 7bit
Content-Type: application/pgp-encrypted
Content-Description: PGP/MIME Versions Identification

Version: 1

--Apple-Mail=_4C5344B9-76FE-43EF-8620-073841EBF944
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
filename=encrypted.asc
Content-Type: application/octet-stream;
name=encrypted.asc
Content-Description: OpenPGP encrypted message

-----BEGIN PGP MESSAGE-----
Version: GnuPG/MacGPG2 v2.0.18 (Darwin)

hQEMAy4S4zGLhwvBAQf/YX1vGFhG0CLd7UU79fjHd4/nIHH9DVVsi8oqsmIwBNpl
zXvDZf3+uw3B7Shk3bls1fHcUdU8LZprY+HbQVZlh7IiGZ28K67rNIHKUtwuoX2I
DpZcLdRPGn1iGi7TNRs/3Fn3fjCCT15uVAbZZRvR1G3XqUc+//3TstCMTaNtg5Rl
KZbKnnrOaIt/OAou7BFCLQgGKAAIa3m/gFHEQxxLVaAQ3JISeX4/UZ7YlXAj5SYp
juVRKfekmjpoFoM4erf0Jjaw63lSjAZWXJi1m6IY8uSkzQZRUwANMYE577mBiZhw
d1kIBJfBlxWjUOK6FYV3bDZFjc2Fn2WM4+tEloOrcNLpASNVPOh332341GjxwVAg
USYLkh1Co7yqaQ1c830CD58XxmYsR/x0B8etL1bYQtZDJYITMa649tYCYtrAvHSw
GsgwDD67yaICruIJqwPAtz5+fkoF9xnlltz0UTUSsmzrlGkdbkHSnVrvOdgbvJEz
60UM1p7idKEcR5SCkNuLD9hYJaD/C7qRhyxYfjyjPlwtSSb9aSY+TBa0t/lRmPtU
q5N/EHRdm3CmTVqE3eT1IOoRsFibYfRJNJnkqgmVZdoHm/QhTOmuyK1SeBbB3P7F
Lnw7hS6aB7RMISg8rWiPGap+QVO8lzMjIXhd5BDu1Kxkk5dr7FLOC37aSC7X52VT
QcwvYlYPSV5s+ivFk/uKtB8L3k9rHsYHHkP13lli2a9ELy+KTv0SFp0Q8ClaC9Xm
RoWXKQxrTV2wxub4/V0UfSSUfct0mHfTFDltpDPAfaEL/ARgvIUI2SD6WXvfbums
yG2fS4Rr9NHr9bgkZJqt+anNGQOmly7654ecckD+Nj2PtmXnowBOrub91VvXSfKB
TKHZ7xmX9GOnk6qsFZppiXIxDXR9zYeLb5Ks0hCF3XDhXu8DAkS4vbmPm7BIn6fu
N1niCzihe187mJ3bKAj5rLSHpbBrMt/XcbaL+eNz7xIEtpWQjk+8qFUaxl5NxIX1
KtCwLhxUeZUCKHIv/cGOJKPANfdhN2SYHasFJvJ1Jts4us4JJg4rBjH50hiYaQ3W
OhGSQP7kvcKqMzHBhSXBKPpnwBtJ+tkXy5IpeMHUrREpGt39EOO4oiiyRYSrrm2T
GswOJwvv4Z32hreR2eAgfPAXZW3R6MtGA07xN3mqPtV1IO+izegbflVpQEi8Zlq3
KfT/ljoLiDTKdIsrlfIgtgec+G5SH6znO9Kv1IidYg9wtdL6G2bsTP9pCV24bCem
srTw3NDKfTK56Yu1ESQpf0WYMTzpGjzDhyHW86F5ej+jJV2rd4kicxvy0HJXOGbI
iHPvKVVoA7bMvvfVARoMIlqiQ5gzm41+
=z4VQ
-----END PGP MESSAGE-----

--Apple-Mail=_4C5344B9-76FE-43EF-8620-073841EBF944--

[/codesyntax]

 

Reference Pages and Additional Reading:

GPGTools First Steps Secure Email in Thunderbird and Apple Mail with GPG

Why is my mongo query so slow?

Why's my mongodb query so slow? I got my geospatial collection set-up -- I am running some really great queries making sure that the locations I am pulling aren't in any sort of cache, and I am just blown-away by how fast data is being returned.

The problem is:  when I query the collection to pull up the requisite lon/lat data by name:  city & state, or city & country, the query seems to take seconds to complete!

I set-up the table correctly...I indexed the crap out of all my columns...a week or two ago, I was at the mongoSV 2011 in Santa Clara and learned some really cool stuff about queries, indexing, and performance management, so let's dig-out the notes and see where I went wrong.  Because I strongly doubt that the problem is in mongo but, rather as we used to say in technical support: this is a PBCK issue...

The first thing I want to do is run an explain against my query so I can see mongo's query plan for my query.  This should provide me with a starting point for trying to figure out what went wrong.

> db.geodata_geo.find({ cityName : "Anniston", stateName : "Alabama" }).explain();

By adding the trailing function: .explain(), I'm requesting that mongoDB return the query-plan to me instead of executing the query.  I hit enter to launch the explain() and get back the following output:

> db.geodata_geo.find({ cityName : "Anniston", stateName : "Alabama"}).explain(); { "cursor" : "BasicCursor", "nscanned" : 3691723, "nscannedObjects" : 3691723, "n" : 1, "millis" : 2269, "nYields" : 0, "nChunkSkips" : 0, "isMultiKey" : false, "indexOnly" : false, "indexBounds" : {

} }

The important information, I bold-faced in the query output (above).   What this output is telling me is that I've using a "BasicCursor" for my search cursor -- which is indicates that, yes, I am doing a table-scan on the collection.  So, already I know my query is not optimal.  But, wait!  More good news...

The value for nscanned and nscannedObjects is the same: 3,691,723 -- which coincidently is the same as the cardinality of the collection.  This number is the number of documents scanned to satisfy the query which, given it's value, confirms that I am doing a full table scan.

millis tells me the number of milliseconds that the query would take:  2.269 seconds:  way too slow for my back-end methods() serving a REST API -- unacceptable.

And then we get to the tell:  IndexOnly tells me that if the query could have been resolved by an (existing) covering index.  Seeing the value false here tells me that the collection has no index on the columns I am scanning against.

What?!?  I know I indexed this collection...

So, I run db.geodata_geo.getIndexes() to dump my indexes and ... I ... don't see my name columns indexed.  Oh, I remembered to index the the ID and Code columns...but somehow, indexing the Name columns completely slipped past my lower brain-pan.

I add these indexes to my collection:

> db.geodata_geo.ensureIndex({ cityName : 1 }); > db.geodata_geo.ensureIndex({ stateName : 1 });

And then I rerun the query plan and see the following output:

> db.geodata_geo.find({ cityName : "Anniston", stateName : "Alabama"}).explain(); { "cursor" : "BtreeCursor cityName_1", "nscanned" : 2, "nscannedObjects" : 2, "n" : 1, "millis" : 101, "nYields" : 0, "nChunkSkips" : 0, "isMultiKey" : false, "indexOnly" : false, "indexBounds" : { "cityName" : [ [ "Anniston", "Anniston" ] ] } }

Instead of BasicCursor, I see BtreeCursor which gives me a happy.  I also see that the nscanned and nscannedObjects values are now more realistic...seriously:  2 is a LOT better than 3.6 million something, right?  Another happy for me!

I score the third happy when I see that the millis has dropped down to 101:  0.101 seconds to execute this search/query!  Not jaw-dropping, I agree -- but acceptable considering that everything is running off my laptop...I know production times will be much, much lower.

 

In the end, I learned that a simple tool like .explain() can tell me where my attention is needed when it comes to optimization and fixing even simple, seemingly innocent queries.  Knowing what you're looking at, and what you're looking for, is pretty much thick-end of the baseball bat when it comes to crushing one out of the park.

I hope this helps!

 

Reference Link:  Explain

Searching MongoDB Sub-Documents...

I've recently finished a mongo collection that stores all auditing data from my application -- specifically, it records every database transaction, conducted in either mySQL or mongo, assigning an event-identifier to the event, and storing the data under an event ID within a single sessionManger object.

Sounds good?

Well, I like it.   This design eliminated the need to maintain meta-data in my data tables since I can pull transaction history for any record that I've accessed.

The problem is that, being new to mongodb, accessing what I've put into mongodb isn't (yet) as intuitive as, say, my mySQL skills are.

Sub-documents within a mongo document are analogous to the results of a mySQL join.  One of the key motivators in storing this information in mongodb to begin with was that I could de-normalize the data by storing the sub-document with it's parent instead of having to incur the expense of a search-join-fetch later.

Traditionally, any data objects defined as a one-to-many type of a relationship (1:m) were stored in multiple mySQL tables and were accessed via some sort of join mechanism.

Mongodb breaks that traditional mold by allowing you to store a sub-document (the "m" part of the 1:m relationship) within the same document in which you're currently working.

Using my sessionManger document, I have a document that looks something like this:

[cc lang='javascript' line_numbers='false'] { _id : somevalue, foo : bar, event : {}, argle : bargle, } [/cc]

My desire is to, for every database event that is recorded, enter information about that event within the sub-document that I've wittily named "event".

In my PHP code, I've written a sequence manager for mongo that maintains a document containing sequence values for various tables.  Think of this as the functional version of mySQL's auto-increment feature.  I decided, then, for the sessionManager events, I would use this key sequence to obtain unique values and use those as my sub-document index.  I'd then store whatever data I needed to store using the sequence value as a sub-document key, or index:

[cc lang='javascript' line_numbers='false']{ _id : somevalue, foo: bar, event : { n : { created : dateval, table : tableName, schema : dbSchema, query : lastQuery } } argle : bargle }[/cc]

So, when I need to add another event, I just create a new sub-document under the event key, then add the data I need to store under the sub-document index key.

Worked like a champ!

And then I asked myself:  "So, Brainiac, how would you go about extracting event -n- from your collection?"

I went through a lot of failed query attempts, bugged a lot of people, googled and saw stuff  that led me down many plush ratholes until I finally, through some serious trial-and-error, got the answer...

> db.mytable.find( { foo : bar }, { 'event.n' : 1 } );

where n = the number of the event I want to find.

If I want to get all of the events for a particular document (sessionManger object), then I would write something like:

> db.mytable.find( {foo : bar}, { event : 1});

If I wanted to return all of the events for all of the objects, then I would write this:

> db.mytable.find( {}, {event : 1});

What I've not been able to figure out, so far, is how I can use $slice to grab a range of events within a document.  Everything I try returns the full sub-set of documents back to me.  The doc tells me that $slice is used to return a subrange of array elements, which is what I thought "event.n" was but, apparently, it's not.  (I think it's an object (sub-document) which is why $slice fails for me.)

It's not a big deal because, programmatically, I can grap the entire sub-document from it's parent and parse in-memory to get the desired record.  And, if I know what the value for -n- is, then I can fetch just that one sub-document.  So, I'm ok for now.  However, please feel free to enlighten me with your expertise and experience should you see where I am failing here, ok?

 

Web Services with PHP & nuSoap - Part 1.1

Introduction

[EDIT] - This is a re-hash of a document I wrote a couple years ago.  There's been changes to the nuSOAP library and I wanted to document the updates relative to the tutorial series.  Also, I need to fix a lot of the broken-links and code listings since I've changes hosting providers since this article was first written.

This article is specific to nuSOAP release 0.9.5 on 2011-01-13.  This tutorial was updated on September 22, 2011.

Once upon a time, I was tasked with developing a web-services by my boss as the integration point between our production application and Sales Force.  At this point, although I'd heard of web services ... kind of ... didn't Amazon use web services for something?  Still, I'd never coded a web-services based application before.

At this point, I have to assume you are unfamiliar with the concept of web services and why you may have to create and provide a web-services offering to your client base.  Web services allow a remote client to access functionality (as defined by you, the programmer) via the standard HTTP interface (normally, port:80) to your application and database services.

Back in the day, networking services (semaphores, pipes, streams, message queues, and other forms of IPC) were custom-written and assigned/slaved to unique networking ports for accessing specific service daemons.  Of course, the internet was a kinder, gentler place back then... and a given server may have had dozens, or even hundreds, of non-standard ports open, listening, waiting, for networking service requests.  Or hacking attempts.

Today, web-services is a replacement to dedicated networking apps - all handled by your web server, and all serviced over the same network port: port 80.  Since port 80 is a standard port and, usually, already open on a web-server, additional security risks by opening new non-standard ports for networking services are averted.  Your web-server, such as Apache, now has the responsibility of processing the request and delivering the results to the client.

The web-services component piece is a collection of functions that you've written that provide remote clients access to your system.  These functions are accessible only via the web services framework and while they may be duplicated from a dedicated and traditional web-based application, the web-services framework is designed as a stand-alone piece of software.  Think of the web-services piece as your application's data-processing layer minus the presentation layer.  The "M" and "C" of the "MVC" model.

Initially, when I was tasked with a similar set of objectives, I initially tried xml-rpc.  This led me down a rabbit-hole that spanned nearly a week of my time with the end-result being abandonment.  I hit road-blocks with xml-rpc over server authentication and passing complex objects.  Exacerbating the issue overall is that xml-rpc seems to be dated technology - I had a hard time locating resources that were recent.

Then I stumbled across nuSOAP - it's free via sourceForge, stable and, using a quote from sourceForge:

"NuSOAP is a rewrite of SOAPx4, provided by NuSphere and Dietrich Ayala. It is a set of PHP classes - no PHP extensions required - that allow developers to create and consume web services based on SOAP 1.1, WSDL 1.1 and HTTP 1.0/1.1."

nuSOAP seemed to have more of everything available: tutorials, examples, articles, blog posts.  When I started my implementation with nuSOAP, the first thing I received help with was server-level authentication.  I was able to immediately get my remote requests validated by the web-server and handed off to the web-services module!

The major selling point, for me, on nuSOAP is that nuSOAP is self-documenting.  As part of the API functionality, nuSOAP generates HTML pages that documents the exposed services via the WSDL  and also provides you with a complete XSLT definition file!

First off, download and install the nuSOAP libraries - I provided a link to the sourceForge site a couple paragraphs ago - and unpack the tarball.  You'll end-up with a directory (mine is called: ./nuSOAP) and, within that directory, is the one file you include: nusoap.php.

There are two pieces to this tutorial -- a server side piece and a client-side piece.  While you can execute both pieces off the same environment (machine), normally you'd use the client remotely to access the API server-side code.

What's Not Covered:

Apache.  Apache configuration for your vhost.  Apache .htaccess.  This article assumes that you've a working server and that you're able to install and access the server files via Apache.  Even if your Apache server is a localhost configuration, access the server-side files via localhost client, traversing the TCP stack locally, is still a valid method for testing your web-services server application.

 

Time to push up our sleeves and start working on the server code...

The Web-Services Server

Today, we're going to write a ping server -- where the server has an exposed service (method) named "ping" which takes a single argument (a string) and returns an array back to the calling client.  The return array contains two associative members: a boolean (which should always be true - otherwise there are other issues...) and a string which is the modification of the original string in order to prove that, yes, we went there and we came back.

Because my project, and I'm doing this project for my new company, is going to represent significant effort, size and complexity, I've broken out the components of nuSOAP request into exterior files because, later, these will become control file which will, in turn, load files that have been organized into a hierarchy friendly to the application's data model.

So, if this file, which I've named index.php, seems small, remember that you're not viewing the dependent files (yet).

[ccne lang="php" line_numbers="on" tab_size="4" width="100%"]

<?php
/**
 *
 */

// setup...
require('./nuSOAP/nusoap.php');
// set namespace and initiate soap_server instance
$namespace = "http://myapi/index.php";
$server = new soap_server('');
// name the api
$server->configureWSDL("myapi");
// assign namespace
$server->wsdl->schemaTargetNamespace = $namespace;
// register services
require('myServiceRegistrations.php');
// load WSDL...
include('mywsdl.php');
// load services code modules...
require('myServicesModules.php');
// create HHTP listener:
$request = isset($HTTP_RAW_POST_DATA) ? $HTTP_RAW_POST_DATA : '';
$server->service($request);
exit();
?>

[/ccne]

So far, so good - let's take a look at what we've just done:

  • we've included the nu_soap library...
  • declared our namespace (which is the URL of the api server)
  • instantiated a new soap_server instance and assigned it to the variable $server
  • initialized the WSDL
  • assigned the namespace variable to the WSDL
  • load and register our exposed services
  • load the WSDL
  • load the service code
  • create the HTTP listener
  • invoke the requested service
  • exit

This (index.php) file is the server-side file that will be invoked for ALL future API calls to the service.  It invokes three control files which, in turn loads the services (WSDL definitions), the WSDL variable definitions (think of these as inputs and outputs to your exposed services), and the actual code for all of the services, and their supporting functions, that you're going to expose via your API.

Side Note:  This is the file you'll reference in Apache when you're (preferably) creating a new Virtual Host for the API.  HTTP requests that resolve to your server will be serviced by Apache which will, in turn, serve the results of this program back to the client.

Next, we're going to define the myServiceRegistrations.php file that is required by index.php.  This file contains the WSDL for each and every exposed service that the API serves.

[ccne lang="php" width="100%" line_numbers="on" first_line="1" tab_size="4"]

<?php
/**
 *
 *
 */

$server->register('ping', array('testString' => 'xsd:string'),
                          array('return' => 'tns:aryReturn'),
                  $namespace, false, 'rpc', 'encoded',
'<p><strong>Summary</strong>: returns response to a ping request from the client.  Response
includes testString submitted.  Used to test Server response/connectivity.
</p>
<p>
<strong>Input</strong>: $testString (type: string) and random collection suffices.
</p>
<p>
<strong>Response</strong>: Service returns an array named $aryReturn with two associative
members: &quot;status&quot; and &quot;data&quot;.<br />$aryReturn[&quot;status&quot;] should
<i>always</i> return true.  (A time-out is an implicit false.)<br />If no value was passed
to the service via $testString, then the value of $aryReturn[&quot;data&quot;] will be
empty.<br />Otherwise it will contain the string: &quot;Rcvd: {yourString} (count)&quot; to
show that the message was received and returned. (count) is a character count of the
passed string, also validating that the passed data was received and processed.
</p>
');

[/ccne]

This PHP code registers a function called "ping" with the nuSOAP $server instance.  The second parameter is the input to function.  Note that all input (and output) parameters have to be declared as an array even if there's only a single value being passed.  Also notice that you have to type-cast the variable being passed using XML datatypes.  For your data definitions, you use one of the 44 built-in datatypes defined in this document: http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/.

(For more information on XSD object and XML schema, please visit: http://ws.apache.org/axis/cpp/arch/XSD_Objects.html.)

The third argument to the method "register" is the data type returned.  This is a complex variable called "aryReturn" -- don't worry about right now, we're going to define this complex-type variable in another configuration file.

The next four arguments are:

  • our $namespace variable we set in index.php
  • boolean false
  • 'rpc' for the call type
  • 'encoded'
Use these values literally.
The last variable is a huge block of HTML.  This block of HTML can be as large, or as small, as you need it to be.  It's the basis for the WSDL documentation that nuSOAP generates for your client-side developers.
When developers hit the server URL, they'll be presented with your API documentation that nuSOAP generates from the WSDL file(s).  As your API grows, exposed methods will be listed in the blue-ish box on the left side of the screen.  Clicking on any of the methods will expose the details (requirements) about that method thus:

Nice, huh?

The second file (that we've included in our source: (mywsdl.php)) is the WSDL file that defines our data structures that are used as either inputs, outputs, or both, to the exposed services.  Another thing I like about SOAP and nuSOAP is that it introduces a layer of strong-typing to the PHP stack.  You can save a bit of debugging time by requiring that you call a method with EXACTLY this and return EXACTLY that.  Anything else tends to generate a system-level error:

[ccne lang="php" width="100%" line_numbers="off"]

[Thu Sep 22 14:36:59 2011] [error] [client ::1] PHP Fatal error:  Call to a member function addComplexType() on a non-object in /htdocs/LL2/trunk/services/mywsdl.php on line 9
[Thu Sep 22 14:36:59 2011] [error] [client ::1] PHP Stack trace:
[Thu Sep 22 14:36:59 2011] [error] [client ::1] PHP   1. {main}() /htdocs/LL2/trunk/services/ll2wsdl.php:0
[/ccne]

This error message, from the apache error log, is somewhat obfuscated in it's meaning.   I attempted to return only the string, by itself, instead of returning the array (of two elements) that I had told nuSOAP I would return for this service.  This error was generated because the types (between the code and the WSDL) of the return variable (structure) did not exactly match.

If you've only ever coded in a loosely-typed language, like PHP, than this part of SOAP is going to be a bit of a ... transition ... for you.  When we say that something, be it a variable, function, or exposed service, is strongly typed, we're declaring the type of that object and, if the type of the object during run-time does not match, then SOAP will force PHP to throw a fatal as shown in the error log snippet above.

Keep this in-mind as you develop exposed services that are increasingly complex.  Since the error messages tend to point you at your code, at the point of failure, it's easy to forget that that the requirements of the underpinnings (in this case, the WSDL), are the root cause of your PHP fatals.

That being said, let's take a look at the WSDL for our ping service:

[ccne lang="php" width="100%" line_numbers="on" first_line="1" tab_size="4"]

<?php
/**
 * WDSL control structures
 *
 * initially, while in dev, this will be one large file but, later, as the product
 * matures, the plan will be to break out the WSDL files into associative files based
 * on the object class being defined.
 */
$server->wsdl->addComplexType('aryReturn', 'complexType', 'struct', 'all', '',
            array('status' => array('name' => 'status', 'type' => 'xsd:boolean'),
                  'data'   => array('name' => 'data',   'type' => 'xsd:string')));

[/ccne]

We're invoking the nuSOAP method addComplexType to define a structure to the WSDL in our Table Name Space (tns).   To do this, we first define the name of the structure that we're going to use: aryReturn and then we define the composition of that structure.

The declaration for this looks a lot like a standard PHP declaration for an array with the exception of the XSD (XML Schema Definition) appended at the end of each element's declaration.  (See the links I embedded above for explanations and examples of valid XSD.)

XSD provides part of the strongly-typed concept for our structure elements.  We're telling nuSOAP to expect a variable structure containing these named elements of this type.

What we have, then, is an associative array with two elements: 'status' and 'data'.  $aryReturn['status'] and $aryReturn['data'] and they're of type BOOL and STRING respectively.

Note, finally, that this variable structure isn't confined to single-use.  Once we've declared it within our tns, it's available to any exposed service where it's needed.  This is the model for my common error structure -- the boolean indicates success or fail on some service operation and the data component contains the relative diagnostic information.

The third and final file we're including into the server source is the code for the exposed service.  This is where you write the function handlers for your services.  Since you've already defined the input parameters, and the return types for the ping service, there's very little left to do.

[ccne lang="php" width="100%" line_numbers="on" first_line="1" tab_size="4"]

<?php
/**
 * ping
 *
 * service that confirms server availability
 *
 * input: any string
 *
 * output: reformatted string:  "Rcvd: {string} (charcount{string})"
 *
 * @param string $testString
 * @return string
 */
function ping($testString = '') {
    return(array('status' => true, 'data' => 'Rcvd: ' . $testString . '(' . strlen($testString) . ')'));
}

[/ccne]

Note the following in the code for our exposed service:

  • our exposed method is named ping because that's how we registered the service (myServiceRegistrations.php)
  • we're providing a default type-cast for the input param of string in case the service is invoked without input params.
  • we're returning BOOL true and prepending "Rcvd: " to the received string, and appending a character count to prove that the service successfully responded to the client's request.
  • the return structure exactly matches the WSDL declaration: the name of the array elements, and the element types.
If you've correctly installed and referenced (within your PHP) the nuSOAP libraries, then you should be able to load the url of the new server source file into your web browser to see the nuSOAP-generated documentation for your new web services.  Click on the WSDL service function: ping to see a detailed description of the function.

If you're using IE, then clicking on the WSDL link will return the XML.  If you're using Firefox, Chrome or other browsers, clicking on WSDL will display the generated XML for your service.

Now that the server is working on it's own, it remains fairly useless until we can get a client to connect to it invoke it's methods.  Let's work on the client next...

The Web-Services Client

The web services client application will also be written in PHP.

The web client is an application that connects to remote server using the http port 80.  To do so, you'll need the client to be aware of certain bits of information that may, or may not, be required to access the remote server.

In our client, we're not going to require remote authentication -- but I'll take a quick aside andexplain how you would include this, client-side, if your server required .htaccess authentication.

nuSOAP has a client method called setCredentials which allows you to specify your .htaccess username and password and the authentication schema.  It's a single line of code which is normally used to require not only clients to login to access your API, but, once identified, you can limit the set of exposed methods available to individual clients or groups.

For example, if you have a product you've developed in-house, then you'd want full-access for your front-end web/applications servers.  Your PM later decides to open a subset of the API to the general public and a subscription-based set of exposed methods in order to monetize your product.  Finally, the PM also wants to "white-box" the product so that other companies can use it but with their branding and access to isolated or discrete data sets.

What you'd end-up with is several levels of client access to your web services.  Implementation of limiting exposed services would be handled server-side but it would be based on your client's authentication and possibly the subject of a future tutorial...

So, to the client-side code: (name this file: apiTestClient.php)

[ccne lang ="php" width="100%" line_numbers="on" first_line = "1" tab_size="4"]

<?php
// Pull in the NuSOAP code
require_once('./nuSOAP/nusoap.php');
$proxyhost = isset($_POST['proxyhost']) ? $_POST['proxyhost'] : '';
$proxyport = isset($_POST['proxyport']) ? $_POST['proxyport'] : '';
$proxyusername = isset($_POST['proxyusername']) ? $_POST['proxyusername'] : '';
$proxypassword = isset($_POST['proxypassword']) ? $_POST['proxypassword'] : '';
$useCURL = isset($_POST['usecurl']) ? $_POST['usecurl'] : '0';
$client = new nusoap_client('http://{YOURSERVERURLHERE}/index.php', false, $proxyhost, $proxyport, $proxyusername, $proxypassword);
$err = $client->getError();
if ($err) {
	echo '<h2>Constructor error</h2><pre>' . $err . '</pre>';
}
$client->setUseCurl($useCURL);
$client->useHTTPPersistentConnection();
// Call the SOAP method
$result = $client->call('ping', array('testString' => 'Argle'), 'http://localhost');
// Display the result
if (!$result) {
    echo "service returned false";
} else {
    print_r($result);
}
unset($client);
?>

[/ccne]

The first thing we do in our client-side code is to include the nuSOAP libraries.

The next five lines of code read from the local POST environment, testing if you've established a proxy for your web-services server and, if so, populating the proxy variables.

The next line instantiates a nuSOAP client and associates it with our remote server.  Change "YOURSERVERURLHERE" to the name of your apache web server URL where you have the server side code installed.  (e.g.: localhost, myserver.com, etc.)

Note the name of the function call: newsoap_client()...as opposed to using the function soapclient().  This function name is legacy-compatible with PHP 5.0's instantiation call:  new soapclient() - the PHP SOAP extension uses the same instantiation function name as the nuSOAP library.  If you have both installed, (PHP 5.0 SOAP extension, and the nuSOAP libraries), executing the client will return errors as you've overloaded the soapclient() function.  (You're calling the PHP SOAP function with the nuSOAP function parameters.)  Rename the soapclient() function to the back-compatible function: newsoap_client().

The next two lines tell the nuSOAP client to useCurl, when possible and if previously saved and, if possible, to use HTTP persistent connections.

Next, we're going to consume the web-services from the server by making a call to the nuSOAP method: call().  The arguments to this method are:

  1. the name of the service being consumed (ping)
  2. the input string (note:  all inputs must be passed as arrays!)
  3. the namespace URI (optional:  WSDL can override)

Store the results of the web-services to the aptly-named variable $results and evaluate it upon return.  If the client call was not successful, then display an error message.

If the client call was successful, then display the contents of the returned array.

Note that you can run this client code from either a browser using the "file://" option or, if the client source code is accessible to apache, then you can display using a browser.

When I run this client-side software in the browser, I get displayed back:

Array ( [status] => 1 [data] => Rcvd: Argle(5) )

So, how do we know that the client went out and successfully returned from the server with the data?  Simple - in the client source, you will not find the literal "Rcvd:" anywhere in the source.  This data was supplied by the server-side function and returned back to the client.  It's a simple example, but it provides proof-of-concept that we're successfully able to connect to a remote web-server and return data created on the remote server back to the client program.

Let's wrap this up...

Summary:

This tutorial (hopefully) explained what web-services are, and provided you with a practical example of a consumable service: ping().  Such a service would normally be invoked as a means of testing server availability.

We created a web-services server file using the nuSOAP library by defining a complex-structure (an associative array) and registering a method with the nuSOAP server.  The method takes an input parameter which, although it's only a single input parameter, must be built and passed as an array construct to the server method.  Next, we showed that by loading the server source into a browser, we learned the nuSOAP provides built-in documentation for your web-services structures and methods.  Which is a very nice-to-have when you're creating your developer documentation!  Next we created the web-services client source code file which connected to our remote server and invoked the server's method: hellow().  If all worked correctly, you displayed the string returned from the remote server within your browser window.

In the next installment, I'll cover the web-services server-side of this business and we'll see how to create the various methods for accessing a mySQL database, complex structures as input and output parameters to those methods, and general debugging techniques.

Thank-you for your patience - I hope this article helped you.

September 26, 2011