1. Everything You Need toKnow About AgentDesign Options
andSecurity in LotusScriptBill BuchanHADSL 2007 Wellesley
Information Services. All rights reserved.
2. What Well Cover Overview Agent Manager introduction Agent
Manager deep dive Security introduction Security deep dive Calling
the C API security interfaces from LotusScript Summary 2
3. Introduction Who is the target audience? Lotus Notes
developers who use server-based agents People who like very long
titles (IBM?) What is this talk about? Agent Manager is a
little-understood black box, with its own set of design
considerations This presentation leads you through Agent Manager
considerations and best practices Lotus Notes is legendarily strong
in terms of security. However, many developers dont understand its
full capability. This session intends to remedy this 3
4. Who Am I? Bill Buchan Dual Principal Certified Lotus
Professional (PCLP) in Domino v3, v4, v5, v6, v7 10+ years senior
development consultancy for Enterprise customers Learn from my
pain! 5+ years code auditing CEO of HADSL Developing best-practice
tools 4
5. Overview This session: Is mostly slide-based Contains a few
code examples Is a deep dive in terms of theory Summarizes 10+
years of enterprise code auditing 5
6. What Well Cover Overview Agent Manager introduction Agent
Manager deep dive Security introduction Security deep dive Calling
the C API security interfaces from LotusScript Summary 6
7. Agent Manager: Introduction Its been in Domino since version
3 It handles both scheduled and triggered agents It handles
@Formula, Java, and LotusScript agents Its a very efficient place
to run code: Because its running on the server, it benefits from
all the server database, view, and document caches Up to version 6,
agents could only open databases on the server that the agent ran
on The Server document, security section field Trusted servers
allows you to define other servers that can use scheduled agents to
open databases on the current server 7
8. Agent Manager: Introduction (cont.) Agent Manager is a
Domino server add-in task Automatically loaded on server start You
can run agents with the console command: Tell Amgr Run It changes
behavior depending on the time Default server document settings are
shown: Should these be changed? 8
9. How Can I Tell Whats Scheduled to Run on My Server? On the
console, type the command: Tell Amgr Sched 9
10. Agent Manager: Agent Types Scheduled agents Schedule a
repeat time period Select either All Servers or a particular target
server Triggered agents From a client Before and after mail
delivery After document creation After document is pasted Remember
Agents can call other agents Useful for mixing languages 10
11. What Well Cover Overview Agent Manager introduction Agent
Manager deep dive Security introduction Security deep dive Calling
the C API security interfaces from LotusScript Summary 11
12. Scheduled Agents in LotusScript Scheduled agents: Are
single-threaded Have a time limit If they exceed this time limit,
they will be killed In this event, the Terminate code is executed
Respect this time limit You may have two instances of the same
agent executing at the same time Bear this in mind during design
12
13. Demo Demo Brief overview of AgentClass 13
14. Triggered Agents Agent Manager has mechanisms to ensure
that it does NOT trigger too often Usually needs at least two
minutes between each agent run Mail-in agents may not trigger
enough So if you have to rely on a mail-in database, create another
mechanism to pick up all unprocessed documents, such as a status
view 14
15. Scheduled Agents: Time Limit If the agent will take a long
time, it should: Record its start time Find out how long the task
should run on this server Stop processing before this time period
occurs Record its state so that it can restart This might be as
little as marking each document as processed Log its progress, and
allow you to see any issues Or: Re-architect the solution to avoid
this 15
16. What About Agent.RunOnServer? In LotusScript, when you use
notesagent.RunOnServer or tell amgr run Agent manager appears to
spawn a new agent thread The agent is not limited to a
server-document time limit The agent appears to run in its own
memory space You cant stop the agent This means: Try not to use it
in production If you have to, be especially careful about: Making
sure it terminates Logging all activity 16
17. Scheduled Agents: Setting Frequency The agent schedule
gives you a number of choices The shortest time period is five
minutes If you need more frequent time periods, re-architect the
solution by using triggers Is this triggered by a mail-in document,
document paste, etc.? Use Trigger Happy Open source project
www.openntf.org Can trigger LotusScript agents on Extension Manager
events 17
18. Scheduled Agents: Allowing Users to Manage Them One common
issue is allowing non-designers in production environments to
control agents Specifically, how often they run, on which servers,
etc. Typically, this is done by changing the template and
refreshing the design However, in larger environments, this may be
impractical One approach is to: Schedule the agent to run
frequently on all servers Check a configuration document within the
same database to see if this agent should run at this time on this
server Beware profile documents Agent Manager caches them, making
updates problematic 18
19. Scheduled Agents: Setting the Right Security Level From
Notes v6, you can define the security level required for your agent
on the Agent properties box Allows you to define whether its a(n):
Restricted Agent Unrestricted Agent Unrestricted Agent with
Administrator Privileges If you migrate databases from v5: They
default to the lowest level 19
20. What Well Cover Overview Agent Manager introduction Agent
Manager deep dive Security introduction Security deep dive Calling
the C API security interfaces from LotusScript Summary 20
21. Security Introduction A good developer should understand
the entire Domino security model Domino is used by governments,
government agencies, political parties, banks, and legal firms
worldwide Because its easy to build secure document-based workflow
applications You can build applications where different groups of
people can see and update fields on the same document It was one of
the first commercial RSA public/private key-based directories
publicly available And now supports 2048-bit key lengths 21
22. Security Introduction (cont.) Common mistakes I see
include: Lack of understanding leading to complex, unmaintainable,
and leaky security implementations e.g., trying to use the wrong
security technique and exposing data Entire companies losing all
their critical documents Reader/author field mismanagement Users
being granted too high a security level for their function e.g.,
-Default- set to Editor in the directory! External agencies making
private information public Dont add yourself to this list! 22
23. What Well Cover Overview Agent Manager introduction Agent
Manager deep dive Security introduction Security deep dive Calling
the C API security interfaces from LotusScript Summary 23
25. Access Server Layer This is normally controlled by fields
on the server security document: Deny Access Allow Access Best
practice is to: Restrict Allow Access to people defined in your
directory Add your Terminations group to Deny Access 25
26. Certificate Authority Layer Certificate authority security:
Is a public/private key-based certificate security based on the
users current certificate(s) Can be switched off by Allow Anonymous
Access on the security: Beware! Checks user certificate expiration
Can check public keys and passwords Users either: Are in the same
certificate hierarchy as the server Share cross certificates
between the server and their certifier In the Domino directory
26
27. Access Folder Layer Folders can have an optional Access
Control List (ACL) set on them Useful in terms of restricting
collections of applications to groups of users e.g., departments,
companies, etc. Beware Folders may also have Directory Links If the
user can navigate to the folder by using an alternative directory
link, the user can access the database 27
28. Access Database Layer The Database Access Control is then
checked to see: Whether the user is allowed to access this database
If so, what level and options the user security should be The user
is set to the maximum level possible based on his/ her collection
of ACL entries, unless the user is explicitly named For databases
accessed on local hard drives: The ACL is not checked unless
Enforce Consistent ACL is set to true This in itself is not a
security feature and may be bypassed Web users are also governed by
Maximum ACL Level 28
29. Application Roles Layer Roles are set within the ACL and:
Allow internal-application grouping of users Are usually used to
allow access to: Particular design elements Reader/Author fields in
documents For instance, applications usually have Administrator
roles @IsMember([Administrator]; @userRoles) 29
30. Reader/Author Fields Layer Reader fields dictate who is
allowed to read this document Author fields dictate who is allowed
to modify a document, if their ACL level is set to Author You may
have more than one Reader/Author field in a document You may have
more than one item in the field You may embed Roles into this field
e.g., [Administrators]: LocalDomainAdmins: */Acme 30
31. Reader/Author Fields: Best Practices Common mistakes
include: Losing access to documents NOT setting the Reader/Access
field as an Array from LotusScript LocalDomainAdmins;
[Administrators] will NOT work! Not setting the Reader/Author field
flag in LotusScript Not using canonicalized names in fields Trying
to use only one Reader/Author field There are lots of programmers
out there who do NOT know how to do this Dont be one of those!
31
32. Reader/Author Fields: ExamplePublic Function
setAuthorsField( doc As NotesDocument, _fieldName As String,
newName As String) As Integer Dim nn As New NotesName(newName) Dim
S(2) As String S(0) = "LocalDomainAdmins" S(1) = "[Administrators]"
S(2) = nn.Canonical Dim itm As NotesItem Set itm =
doc.ReplaceItemValue(fieldName, S) Itm.IsReaders = TrueEnd Function
32
33. Field-Level Encryption Layer If a user requires access to a
document and should NOT see particular fields, then field-level
encryption should be used Possibly one of the least used features
in Domino Two separate models: Encryption Keys or
SecretEncryptionKeys Public Key Encryption Each model has its
strengths and weaknesses 33
34. Encryption Keys Explained Can be: Generated, maintained,
and distributed by any user Incorporated into the User ID file
Distributed by Mail or by SneakerNet Used by the form to encrypt
selected fields by Name Best practices At least one copy of ANY key
used should be stored in a secure repository (a safe!), password
protected, and physically disconnected from any computer system For
instance, on a CD-ROM and a piece of paper! 34
35. Public Encryption Keys Explained Public encryption
key-based field-level encryption: Is calculated at run time Can be
updated Does not require any encryption key distribution Is based
on the target users public key Attractive for: Optional encryption
of particular documents for groups of users Can be completely
hidden from the end-user Does not inject new items into the ID file
35
36. Field-Level Encryption Compared Why use encryption keys?
Because only the people who possess the encryption key can
participate Far better from an auditing point of view New users can
see documents without the documents having to be updated Why use
public key encryption? No distribution of IDs required Ad hoc
encryption of documents is made more simple 36
37. Demo Demo Brief overview of Encryption Keys 37
38. What Well Cover Overview Agent Manager introduction Agent
Manager deep dive Security introduction Security deep dive Calling
the C API security interfaces from LotusScript Summary 38
39. Calling C API Security Interfaces: Introduction The Notes C
API reference manual lists: 27 security functions Starts with SEC
13 registration functions Starts with REG Most are quite difficult
to use Lets focus on two: REGGetIDInfo: Get information about an ID
file SECKFMChangePassword: Change a password on an ID file 39
40. Calling C API Security Interfaces: REGGetIDInfo
REGGetIDInfo allows you to examine an existing ID file It can
return both a boolean value and a string Best to declare it as two
separate functionsDeclare Function W32_REGGetIDInfo_BOOL Lib
LIB_W32 Alias {REGGetIDInfo} (_ Byval IDFileName As Lmbcs String, _
Byval InfoType As Integer, _ OutBufr As Long, _ Byval OutBufrLen As
Integer, _ ActualLen As Integer) As IntegerDeclare Function
W32_REGGetIDInfo_STRING Lib LIB_W32 Alias {REGGetIDInfo} (_ Byval
IDFileName As Lmbcs String, _ Byval InfoType As Integer, _ Byval
OutBufr As Lmbcs String, _ Byval OutBufrLen As Integer, _ ActualLen
As Integer) As Integer 40
41. Calling C API Security Interfaces: REGGetIDInfo (cont.) We
need to define some flags The following InfoType codes are defined
for REGGetIDInfo Note that the Certifier Flag can only exist on a
hierarchical ID and that Certifier, NotesExpress, and Desktop flags
are not present in safe copies of ID filesConst REGIDGetUSAFlag=1
Structure returned is BOOLConst REGIDGetHierarchicalFlag = 2
Structure returned is BOOLConst REGIDGetSafeFlag = 3 Structure
returned is BOOLConst REGIDGetCertifierFlag = 4 Structure returned
is BOOLConst REGIDGetNotesExpressFlag = 5 Structure returned is
BOOLConst REGIDGetDesktopFlag = 6 structure returned is BOOLConst
REGIDGetName= 7 Structure returned is StringConst REGIDGetPublicKey
= 8 Structure returned is StringConst REGIDGetPrivateKey = 9
Structure returned is StringConst REGIDGetIntlPublicKey = 10
Structure returned is StringConst REGIDGetIntlPrivateKey = 11
Structure returned is String 41
42. Calling C API Security Interfaces: REGGetIDInfo (cont.)
Therefore, to find out if an ID is a certifier: Dim
strCertifierPath As String, fIsCertifier As Long Dim actualLen As
Integer, LerrrorValue as Long fIsCertifier = 0 Lerrorvalue =
W32_REGGetIDInfo_BOOL( _ strCertifierPath, _ REGIDGetCertifierFlag,
_ flsCertifier, _ 4, _ actualLen) _ If (flsCertifier) then Print
Certifier: + strCertifierPath + is a certifier Else Print
Certifier: + strCertifierPath + is NOT a certifier End if 42
43. Calling C API Security Interfaces: REGGetIDInfo (cont.) To
find out the name of this certifier: Dim strCertifierPath As
String, strIDName As String Dim myName As String*1024, actualLen As
Integer Dim Lerrorvalue as long Lerrorvalue =
W32_REGGetIDInfo_STRING (_ strCertifierPath, REGIDGetName, myName,
1024, actualLen) If Lerrorvalue 0 Then Print Failed during
REGGetIDInfo Else If actualLen = 0 Then Print "Did not get a name
from this ID file" Else strIDName = Left(myName, actualLen) Print
This ID name is: " + strIDName End If End if 43
44. Calling C API Security Interfaces: SECKFMChangePassword
SECKFMChangePassword allows you to change the password on an ID
file You have to know the previous password The new password has to
conform to certifier password restrictions We need to use the
following function declaration: Declare Function
W32_SECKFMChangePassword Lib LIB_W32 Alias {SECKFMChangePassword}
(_ Byval IDFileName As Lmbcs String, _ Byval OldPass as Lmbcs
String, _ Byval NewPass as LMBCS String) As Integer 44
45. Calling C API Security Interfaces:SECKFMChangePassword
(cont.) So to change a password: Dim strIDName As String, oldPass
As String Dim newPass as String, Lerrorvalue as long Lerrorvalue =
W32_SECKFMChangePassword (_ strIDName, oldPass, newPass) If
Lerrorvalue 0 Then Print Failed during SECKFMChangePassword Else
Print ID : +strIDName+ has changed password from: +_ oldPass + to:
+ newPass End if 45
46. What Well Cover Overview Agent Manager introduction Agent
Manager deep dive Security introduction Security deep dive Calling
the C API security interfaces from LotusScript Summary 46
47. Resources My Leveraging the Power of Object Orientated
Programming in LotusScript presentation
www.billbuchan.com/web.nsf/htdocs/BBUN6MQECQ.htm Steve McConnell,
Code Complete, Second Edition, (Microsoft Press, 2004).
www.amazon.com/gp/product/0735619670 Normunds Kalnberzin,
LotusScript to Lotus C API Programming Guide, (November 2003).
www.ls2capi.com Lotussphere 2004 : AD104 LotusScript Tips and
Tricks in the Lotus Sandbox
www-10.lotus.com/ldd/sandbox.nsf/ecc552f1ab
6e46e4852568a90055c4cd/68797abc4efa809a85
256e51006a2c8a?OpenDocument 47
48. Resources (cont.) NSFTools Notes Tips
www.nsftools.com/tips/NotesTips.htm The Notes FAQ!
www.keysolutions.com/NotesFAQ Brian Benz and Rocky Oliver, Lotus
Notes and Domino 6 Programming Bible, (Wiley, John & Sons,
Incorporated, 2003). www.amazon.com/gp/product/0764526111 Notes.Net
(of course) www.notes.net 48
49. 7 Key Points to Take Home Agent Manager is a harsh
taskmaster Write well-behaved scheduled agents Understand Agent
security levels Especially when migrating from v5 Understand
triggers, schedules, and run on server Implement security poorly
and suffer Approach with caution, spend the time, get it right
Understand all security layers And use the most appropriate for
your requirements The C API security interface gives you more
detail At the cost of more complex code 49