Security for stand-alone Java programs that use the Notes API

Since its launch in the early 1990s, Lotus Notes has had a wonderful security architecture which implemented a public/private key architecture which has only recently been widely adopted by other platforms. Unfortunately this meant that many people are not really familiar with how it works.

I recently blogged about how to write stand-alone Java programs which can manipulate Notes/Domino databases. A few people commented upon the fact that when they run their stand-alone programs on a machine on which they have a Notes client installed they are normally prompted to enter a password each time the program launches. Since they don't get a similar password prompt when they run their program on a machine which has a Domino server installed on it, they seem tro think that the Domino server code gives them some form of privelege to bypass Notes security. This is not true, but to explain why I will first need to explain some important facts about Notes/Domino secuirty model.

1. Notes implements what security experts call "two factor authentication". This means that you need to prove your identity by two different mechanisms. Firstly you need to have an ID file containing your private key and secondly you need to know the password used to secure the ID file.
2. Domino servers also have ID files to prove their identity. However, most administrators insist that their real human users choose a complex password to secure their ID file and change it frequently, but most administrators don't use any password at all on their servers' ID files. This is because otherwise they would need a human to be present to type in the password every time the server is restarted and in any case sharing the ID file's password with all of the potential administrators would negate any security benefit from having a password.

When you run a Java stand-alone program that used the Notes API on a machine which has the Notes client installed you will run with the identity of currently installed ID file (which typically requires you to type a password). When you run this same program on a machine which has the Domino server installed you will run with the identity of server's ID file (which probably doesn't require you to type a password). Because of this you will need to ensure that the server is granted the appropriate access rights to the databases your program needs to use.

Domino has the concept of "scheduled agents" which can run on a server in the background and do various maintenance tasks. If these tasks executed with the server's ID it would be necessary to give the server access rights to a lot of databases which would not be very secure. Instead Domino implements a mechanism that these scheduled agents run with the access rights of the user who signed the agent this means that each of the users can run their own version of the agent running with access rights to just their own databases.

[xpost] Running stand-alone java programs that read and write Notes/Domino databases

[This post was originally posted to my IBM internal blog]

Most code which interfaces with Notes/Domino databases will run in the context of a running client or server e.g. a notes agent which runs on a schedule or in response to an event. However, there are times when you might want to run a stand-alone programs that will read and write Notes/Domino databases.

Bob Balaban (who wrote the definitive book on the Notes Java API) recommends that programmers should write agents in such a way that they can be run either as a stand-alone program or as a Notes agent because of the fact that it is so much easier to debug a Java program than to debug a Notes/Domino agent (he calls this the two headed beast). However, it is also often handy to distribute a program which modifies a Notes database in the form of a stand alone program e.g. I recently had to  write a program which tweaked the settings of a Sametime Community server - since many Sametime administrators don't even realize that they have a Domino server underneath I thought it would be easier to distribute the code in the form of a stand-alone program rather than as an agent and asking administrators to go through the complexity of installing and enabling a Notes agent.

One of the things that is complex about running a piece of Notes/Domino code is that you need a lot of context e.g what Notes ID etc. If you are running java agent on a machine which has Notes installed upon it then the environment variables will be already set up for you, but if your machine does not have Notes installed it can be tricky to figure out all of the paths and environmental variables that are needed. In particular I have often wasted a lot of time trying to get Java programs to run on Linux Domino servers.

What many people don't realize is that Domino Linux servers come with a very handy startup script in /opt/ibm/lotus/notes/latest/linux. that can do all of the hard work for you. To use this program you should invoke your program with the script, like:

/opt/ibm/lotus/notes/latest/linux/startup /LOCATION/MYTOOL

where LOCATION is the path to your tool and MYTOOL is the name of your tool. Then your tool will get invoked with all of the necessary environmental variables defined properly.

This startup script  is really handy, I am not sure why it is not more widely documented.