Security APIs in Notes/Domino 7.0

Take a sneak peek at the new encryption/decryption APIs offered by Lotus Notes and Domino 7.0.

Phillipe Loher, Software Engineer, IBM

Phillipe Loher is a Software Engineer working on Lotus messaging and collaboration products. Current projects include Domino, unified communications, and mobile-based functionality. Phillipe lives near Boston and likes playing tennis and making wine as a hobby.



26 July 2005

Also available in Russian Japanese

In this article, we discuss many different features related to the new Notes/Domino 7 Notes encryption/decryption APIs. We describe how business partners and other Notes developers can give their programs the ability to read and create Notes-encrypted and S/MIME-encrypted messages. There are endless numbers of scenarios where business partners and developers may want to implement the ability to view and/or create encrypted notes from within their applications. This article looks at the critical technical and administrative details required to implement these and other Notes/Domino 7 security features.

Due to the large number of different scenarios in which Notes applications may need access to encrypted documents, we suggest that you use this article as an introduction to help you understand how the new APIs work. You can then adjust the implementation procedures contained in this article to suite the architecture of your application.

This article assumes that you are an experienced Notes/Domino application developer with a solid understanding of Notes/Domino security. Knowledge about Domino’s security certificate model would also be helpful. For information about security and all other features in Notes/Domino 7, see the developerWorks: Lotus articles, "New features in Lotus Domino 7.0 Beta 4" and "New features in Lotus Notes and Domino Designer 7.0 Beta 4."

Notes/Domino 7 security API overview

The new security API methods are part of the Notes/Domino 7 run-time C library. Applications that are able to use NRPC calls can access the APIs with the Notes/Domino 7 run-time library.

Prior to the new APIs introduced in Notes/Domino 7 (a subset of which was also introduced in Notes/Domino 6.5x), a Notes application could read/create Notes-encrypted and S/MIME-encrypted documents by using the APIs NSFNoteCopyAndEncrypt and NSFNoteDecrypt, respectively. There are several reasons why this method may not be sufficient for a Notes application. First, the application must switch context to the user performing the encryption/decryption by issuing the SECKFMSwitchToIDFile call. Switching context between users (for example, switching from admin-user to another user, and then back) multiple times has performance implications. In addition, SECKFMSwitchToIDFile requires that the ID file of the user be present and up-to-date. That means that the Notes application would have to keep track of the users' ID files and detect changes that reflect on the ID files (Name changes and public key changes). The new APIs can detect these changes for you and help simplify the management of the ID files. Using the new security APIs is not required, but will help you with the limitations above.

In addition, the previously existing APIs PKCS12_ExportIDFileToFile and PKCS12_ImportFileToIDFile allow internet certificates and keys to be imported and exported in the ID file. With Internet certificates and private keys in the ID file, it is possible to read S/MIME-encrypted mail and send S/MIME-signed mail. While this method will allow you to read S/MIME messages (if you had a proper crypto engine), it might not be a convenient solution for you and can only be used for helping decode S/MIME, and not Notes, encrypted messages. The new APIs make it easy to access/create both Notes-encrypted and S/MIME-encrypted messages.


New Notes/Domino APIs

A more detailed and accurate description of the APIs are described in the Lotus C API Notes/Domino 7.0 Reference and User Guide. This section presents brief descriptions of the APIs that will be discussed in this article.

SECKFMOpen

This method supplies a handle to the credentials of the ID file if you pass it the correct ID file name and password. This credential handle can now be passed around to the other functions in this list so that switching user context via SECKFMSwitchToIDFile is not necessary. Encryption/decryption is not possible without the proper credentials.

SECKFMClose

This closes the SECKFMOpen handle when you are done with it.

SECAttachIdFileToDB

This is used to take an ID file and securely attach it to the database (for instance, the user's mail file). This makes it easier to manage user ID files so that a central repository of ID files won’t have to be maintained. The ID file and password need to be supplied for the attachment to take place. The ID file is stored in a profile note (the name is specified when calling function) of the database.

SECExtractIdFileFromDB

This function detaches the ID file attached by the SECAttachIdFileToDB function. The ID file will need to be detached so that the proper ID path can be given to SECKFMOpen.

SECRefreshIdFile

This function checks for Notes certification changes, Internet certification changes, and user renames for the given user in the directory. You pass to this method the ID file, password, and server on which to check for changes. If any changes are detected, the ID file will be refreshed. Normally, when changes are detected, you should reattach the ID file using SECAttachIdFileToDB. You should issue SECRefreshIdFile after you extract the ID to ensure that it is up-to-date.

NSFNoteDecrpytExt2

This is the extension to NSFNoteDecryptExt. You pass this method the KFM credential handle so that you can properly decrypt a message.

NSFNoteCopyAndEncryptExt2

This is the extension to NSFNoteCopyAndEncrypt. You pass this method the KFM credential handle so that you can properly encrypt a message.


Using the new security APIs

Before encryption/decryption can occur, the Notes ID with credentials to the secure document has to be accessible so that the proper credentials can be used. If you have the user's ID file and password, you can attach her ID file into her mail file using the new SECAttachIdFileToDB function. For instance, your Notes application can store each user's ID file into a $MyId (or other unique name) profile document. Generally speaking, there is an endless number of interfaces your application could use to prompt for and store the user's ID and password. It’s up to your application to provide the proper interface in a manner that’s acceptable to the end user and architecture of your product.

Using Domino Web Access as an example, the Notes ID is attached as the $shimmerid profile. You can verify that the $shimmerid document exists by using the Notespeek tool that will show you the list of IDs (see figure 1):

Figure 1. Notespeek IDs list
Notespeek IDs list

Domino Web Access provides a good example of a user interface that allows users to attach their Notes ID files. As you can see from the Security Preferences tab shown in figure 2, users can select their Notes ID file and supply the password:

Figure 2. Security Preferences tab
Security Preferences tab

Your application can provide a similar GUI that your users have access to. Once the user supplies the ID and password, your Notes application can call SECAttachIdFileToDB to attach the ID file to the mail file. Your Notes application will have to be able to access this ID file and password when attempting to encrypt and decrypt messages. Your Notes application should also treat the user’s data (ID file and password) securely as it is security-sensitive information.

In addition, this method gives users of your application the ability to re-attach a new ID file when needed. For instance, if they request new public/private keys they will need to attach their new ID file to access new encrypted messages.

Using the attached ID to read encrypted messages

Your application needs to determine whether or not the document is encrypted. It can accomplish this by using the Notes API method NSFNoteIsSignedOrSealed. If it determines that the note is encrypted, then your application can make use of the new security APIs. One approach would be to use the following steps as a guideline:

  1. Detach the user's ID file from the mail file by using the method SECExtractIdFileFromDB. (The user must have the ID file in his mail file for this to succeed. The process for doing this is explained earlier in this section.) You must also have the user's password of the ID file to do this.
  2. Issue the SECRefreshIdFile method on the detached ID file. This will ensure that Notes certification changes, Internet certification changes, and user renames are reflected on the detached ID file.
  3. If SECRefreshIdFile picked up any changes, reattach the ID file back to the mail file using SECAttachIdFileToDB.
  4. Passing the detached ID file/password as a parameter, use SECKFMOpen to extract the ID file handle.
  5. Use the ID file handle in the NSFNoteDecrpytExt2 method to access the encrypted message. Make sure the contents stay secure after decryption because encrypted messages normally tend to contain sensitive data.
  6. Use SECKFMClose to close the ID file handle.
  7. Close the note and remove the detached ID file from storage.

Using the attached ID to create encrypted messages

If your application needs to encrypt a message, it can make use of the new security APIs. One way to do this would be as follows:

  1. Detach the user's ID file from the mail file by using method SECExtractIdFileFromDB. (Again, the user must have the ID file in his mail file for this to work.) You must also have the user's password for the ID file.
  2. Issue the SECRefreshIdFile method on the detached ID file. This will ensure that Notes certification changes, Internet certification changes, and user renames are reflected on the detached ID file.
  3. If SECRefreshIdFile picked up any changes, reattach the ID file back to the mail file using SECAttachIdFileToDB.
  4. Passing the detached ID file/password as a parameter, use SECKFMOpen to extract the ID file handle.
  5. Use the ID file handle in the NSFNoteCopyAndEncryptExt2 method to encrypt the document.
  6. Use SECKFMClose to close the ID file handle.
  7. Close the note and remove the detached ID file from storage.

Other concepts for Notes ID administration

It is likely that you may want your application to be able to encrypt and/or decrypt messages from a variety of different users. In this case, it may be inconvenient to attach each ID file individually. Your Notes application can in turn make a bulk tool to attach multiple ID files to simplify the process.

As long as your Notes application has access to all the ID files and passwords that need to be attached to users' mail files for encryption/decryption to occur, it can use method SECAttachIdFileToDB to attach all the ID files. You would have to create a tool to cycle through the attaching of the IDs. Your tool would need some sort of secure repository that contains the users' ID files and passwords to read from. The ID files and passwords should be kept in a secure and confidential fashion.

How to give the user the ability to change their Notes ID password

For security reasons, you may want to give individual users of your product the ability to change the password of the Notes ID used by your application for creating/reading encrypted messages. One example of when they would want to change their password is when the password is compromised. Also, your Notes application may need to create policies that ensure that users change the password of the Notes ID used by your application on a regular basis.

Figure 3 shows Domino Web Access' Change Internet Password dialog. This allows users to change their Notes ID passwords. Your application can use this dialog as a model:

Figure 3. Change Internet Password
Change Internet Password

You may want to provide an interface to collect the user's existing password and new password. This interface would then be able to feed the data to your application. One way to do this would be as follows:

  1. Detach the user's ID file from the mail file by using the method SECExtractIdFileFromDB.
  2. Issue the SECRefreshIdFile method on the detached ID file. This will ensure that Notes certification changes, Internet certification changes, and user renames are reflected on the detached ID file.
  3. Using the new password data, use SECKFMChangePassword to change the password.
  4. Reattach the ID file back to the mail file using SECAttachIdFileToDB.
  5. Close the note and remove the detached ID file from storage.

Conclusion

In this article, we've introduced you to the new security APIs introduced in Notes/Domino 7. We've also shown you how to use these APIs, and have offered some practical application examples. We hope you found this article useful. Please feel free to suggest other Notes/Domino security related topics that you would like to see discussed in future articles.

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Select information in your profile (name, country/region, and company) is displayed to the public and will accompany any content you post. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into IBM collaboration and social software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Lotus, Security
ArticleID=90338
ArticleTitle=Security APIs in Notes/Domino 7.0
publish-date=07262005