Encryption Decryption
Chapter 12-2
Encryption/Decryption
You can use the C API to encrypt documents and to decrypt and read encrypted documents. Encrypted documents are those that contain encrypted fields.
Encryption-Enabled Fields
To encrypt a document, the document must contain at least one encryption-enabled field. Only the encryption-enabled fields in a document are encrypted. An API program uses NSFItemAppend to write an encryption-enabled field. Set ITEM_SEAL in the item flags.
| encrypt.c: Writing an Encryption Enabled Text Field |
#define ENCRYPTED_ITEM "SECRET"
DBHANDLE hDB; / database handle /
NOTEHANDLE hNote; / note handle /
char EncryptKey; / name of secret encryption key /
char TextField[100]; / contents of a text field /
NOTEHANDLE hEncryptedNote; / note handle of encrypted note */
if (error = NSFItemAppend (hNote,
ITEM_SUMMARY | ITEM_SEAL,
ENCRYPTED_ITEM, strlen(ENCRYPTED_ITEM),
TYPE_TEXT,
TextField, strlen(TextField)))
{
PrintAPIError(error);
NSFNoteClose (hNote);
NSFDbClose (hDB);
NotesTerm();
return (1);
}
Encryption Keys
Encryption keys are used to encrypt documents. Secret encryption keys (also known as personal encryption keys) can be created by the user. These are stored in the user's ID. Every Notes user has a public encryption key, which is stored in the Domino Directory and used mainly for sending encrypted mail. Every Notes user also has a private encryption key that is stored in the user's ID. The private encryption key is used to decrypt documents that were encrypted with that user's public encryption key.
You specify whether to use the current user's public key or a different key in the call to NSFNoteCopyAndEncrypt.
If you want to encrypt a document with the current user's public key, specify the ENCRYPT_WITH_USER_PUBLIC_KEY flag.
If you want to encrypt a document with a secret encryption key, an ITEM_NAME_NOTE_SEALNAMES field containing the name of the secret key must be appended to the document before you call NSFNoteCopyAndEncrypt. The encryption-enabled fields in the note are encrypted using this key. The ITEM_NAME_NOTE_SEALNAMES item is of TYPE_TEXT (or of TYPE_TEXT_LIST if there are multiple secret encryption keys for the note) with the ITEM_SUMMARY flag set.
If you want to encrypt a document with a specified user's public key, an ITEM_NAME_NOTE_SEALUSERS field containing the canonical name of the user must be appended to the document before you call NSFNoteCopyAndEncrypt. The encryption-enabled fields in the note are encrypted using this key. The ITEM_NAME_NOTE_SEALUSERS item is of TYPE_TEXT (or of TYPE_TEXT_LIST if there are multiple users) with the ITEM_SUMMARY flag set.
| encrypt.c: Writing the ITEM_NAME_NOTE_SEALNAMES Field |
if (error = NSFItemAppend (hNote,
ITEM_SUMMARY,
ITEM_NAME_NOTE_SEALNAMES, (WORD)strlen(ITEM_NAME_NOTE_SEALNAMES),
TYPE_TEXT,
EncryptKey, (DWORD)strlen(EncryptKey)))
{
PrintAPIError(error);
NSFNoteClose (hNote);
NSFDbClose (hDB);
NotesTerm();
return (1);
}
| encrypt.c: Writing the ITEM_NAME_NOTE_SEALUSERS Field Containing Muliple Names |
if (error = NSFItemCreateTextList (hNote,
ITEM_NAME_NOTE_SEALUSERS,
USER1,
MAXWORD))
{
PrintAPIError(error);
NSFNoteClose (hNote);
NSFDbClose (hDB);
NotesTerm();
return (1);
}
/ Add another user to the ITEM_NAME_NOTE_SEALUSERS /
if (error = NSFItemAppendTextList (hNote,
ITEM_NAME_NOTE_SEALUSERS,
USER2,
MAXWORD,
FALSE))
{
PrintAPIError(error);
NSFNoteClose (hNote);
NSFDbClose (hDB);
NotesTerm();
return (1);
}
Encrypting the Document
Once you have appended all the encrypted-enabled fields to the document and identified the encryption key(s), you can use NSFNoteCopyAndEncrypt to encrypt the encryption-enabled fields. In the following example, the second argument is set to 0, indicating that you want to use one or more secret encryption keys, one or more public keys or both secret and public encryption keys to encrypt the document. Secret encryption keys are specified in the ITEM_NAME_NOTE_SEALNAMES field. Canonical user names are specified in the ITEM_NAME_NOTE_SEALUSERS field if you want to use their public encryption key to encrypt the document.
| encrypt.c: Encrypting the Document |
if (error = NSFNoteCopyAndEncrypt (hNote, 0, &hEncryptedNote))
{
PrintAPIError(error);
NSFNoteClose (hNote);
NSFDbClose (hDB);
NotesTerm();
return (1);
}
if (error = NSFNoteUpdate (hEncryptedNote, 0))
{
PrintAPIError(error);
NSFNoteClose (hNote);
NSFDbClose (hDB);
NotesTerm();
return (1);
}
Decrypting an Encrypted Document
Use the API function NSFNoteDecrypt to decrypt an encrypted document and read any field from it. The user must have the proper encryption key in the user ID file to decrypt the document and read encrypted fields.
| encrypt.c: Decrypting a Document |
NOTEID dwNoteID; / note id obtained earlier /
NOTEHANDLE hNote; / note handle /
STATUS error; / return code from API calls /
BOOL fSealed; / Is not encrypted? /
BOOL FieldFound;
WORD len;
char ItemText[500];
if (error = NSFNoteOpen (
hDB, / database handle /
dwNoteID, / note id /
0, / open flags /
&hNote)) / note handle (return) /
return (error);
/ If the note is encrypted, decrypt it. /
if (NSFNoteIsSignedOrSealed (hNote, NULL, &fSealed) )
if (fSealed)
if (error = NSFNoteDecrypt (
hNote, / note handle /
0, / reserved /
NULL)) / Key for attachments - not
needed /
{
NSFNoteClose (hNote);
return (error);
}
printf("\n\n\nNote ID: %lX\n\n", dwNoteID);
FieldFound = NSFItemIsPresent (hNote,
ItemName,
strlen (ItemName));
if (FieldFound)
{
len = NSFItemGetText (
hNote,
ItemName,
ItemText,
sizeof (ItemText));
if (fSealed)
printf ("The %s field has been decrypted.\n", ItemName);
else
printf ("The %s field is not encrypted.\n", ItemName);
printf ("Contents of %s field:\n\n%s\n", ItemName, ItemText);
}
/ If the specified field is not there, print a message. /
else
printf ("%s field not found.\n", ItemName);