Your SlideShare is downloading. ×
  • Like
  • Save
Dev buchan everything you need to know about agent design
Upcoming SlideShare
Loading in...5

Thanks for flagging this SlideShare!

Oops! An error has occurred.


Now you can save presentations on your phone or tablet

Available for both IPhone and Android

Text the download link to your phone

Standard text messaging rates apply

Dev buchan everything you need to know about agent design



Published in Technology
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
    Be the first to like this
No Downloads


Total Views
On SlideShare
From Embeds
Number of Embeds



Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

    No notes for slide


  • 1. © 2007 Wellesley Information Services. All rights reserved.Everything You Need toKnow About AgentDesign Options andSecurity in LotusScriptBill BuchanHADSL
  • 2. 2What We’ll Cover …• Overview• Agent Manager introduction• Agent Manager deep dive• Security introduction• Security deep dive• Calling the C API security interfaces from LotusScript• Summary
  • 3. 3Introduction• 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 ownset of design considerations This presentation leads you through Agent Managerconsiderations and best practices Lotus Notes is legendarily strong in terms of security.However, many developers don’t understand its full capability. This session intends to remedy this
  • 4. 4Who Am I?• Bill Buchan• Dual Principal Certified Lotus Professional (PCLP) inDomino v3, v4, v5, v6, v7• 10+ years senior development consultancy forEnterprise customers Learn from my pain!• 5+ years code auditing• CEO of HADSL Developing best-practice tools
  • 5. 5Overview• 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
  • 6. 6What We’ll Cover …• Overview• Agent Manager introduction• Agent Manager deep dive• Security introduction• Security deep dive• Calling the C API security interfaces from LotusScript• Summary
  • 7. 7Agent Manager: Introduction• It’s been in Domino since version 3• It handles both scheduled and triggered agents• It handles @Formula, Java, and LotusScript agents• It’s a very efficient place to run code: Because it’s running on the server, it benefits from all theserver database, view, and document caches• Up to version 6, agents could only open databases onthe server that the agent ran on The Server document, security section field “Trusted servers”allows you to define other servers that can use scheduledagents to open databases on the current server
  • 8. 8Agent 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 “<db>” ‘<agent>’• It changes behaviordepending on the time Default serverdocument settingsare shown: Should thesebe changed?
  • 9. 9How Can I Tell What’s Scheduled to Run on My Server?• On the console, type the command: Tell Amgr Sched
  • 10. 10Agent Manager: Agent Types• Scheduled agents Schedule a repeat time period Select either “All Servers” or aparticular 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 …
  • 11. 11What We’ll Cover …• Overview• Agent Manager introduction• Agent Manager deep dive• Security introduction• Security deep dive• Calling the C API security interfaces from LotusScript• Summary
  • 12. 12Scheduled 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 atthe same time … Bear this in mind during design
  • 13. 13DemoDemoBrief overview ofAgentClass
  • 14. 14Triggered Agents• Agent Manager has mechanisms to ensure that it doesNOT 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 anothermechanism to pick up all “unprocessed” documents, suchas a status view
  • 15. 15Scheduled 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
  • 16. 16What 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 can’t 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
  • 17. 17Scheduled 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 thesolution by using triggers Is this triggered by a mail-in document, document paste, etc.? Use Trigger Happy Open source project Can trigger LotusScript agents on Extension Managerevents
  • 18. 18Scheduled Agents: Allowing Users to Manage Them• One common issue is allowing non-designers inproduction environments to control agents Specifically, how often they run, on which servers, etc.• Typically, this is done by changing the template andrefreshing 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 tosee if this agent should run at this time on this server Beware profile documents Agent Manager caches them, making updatesproblematic
  • 19. 19Scheduled Agents: Setting the Right Security Level• From Notes v6, you can define the security levelrequired for your agent on the Agent properties box Allows you to define whether it’s a(n): Restricted Agent Unrestricted Agent Unrestricted Agent with Administrator Privileges If you migrate databases from v5: They default to the lowest level
  • 20. 20What We’ll Cover …• Overview• Agent Manager introduction• Agent Manager deep dive• Security introduction• Security deep dive• Calling the C API security interfaces from LotusScript• Summary
  • 21. 21Security Introduction• A good developer should understand the entire Dominosecurity model• Domino is used by governments, government agencies,political parties, banks, and legal firms worldwide Because it’s easy to build secure document-based workflowapplications You can build applications where different groups of peoplecan see and update fields on the same document• It was one of the first commercial RSA public/privatekey-based directories publicly available And now supports 2048-bit key lengths
  • 22. 22Security 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 andexposing 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• Don’t add yourself to this list!
  • 23. 23What We’ll Cover …• Overview• Agent Manager introduction• Agent Manager deep dive• Security introduction• Security deep dive• Calling the C API security interfaces from LotusScript• Summary
  • 24. 24Seven Layers• Domino has seven layers of security1. Access server2. Certificate authority3. Access folder4. Access database5. Application roles6. Reader/author fields7. Field-level encryption
  • 25. 25Access Server Layer• This is normally controlled by fields on the serversecurity 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
  • 26. 26Certificate Authority Layer• Certificate authority security: Is a public/private key-based certificate security based on theuser’s current certificate(s) Can be switched off by “Allow Anonymous Access” on thesecurity: 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
  • 27. 27Access Folder Layer• Folders can have an optional Access Control List (ACL)set on them Useful in terms of restricting collections of applications togroups 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 alternativedirectory link, the user can access the database
  • 28. 28Access 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 explicitlynamed• For databases accessed on local hard drives: The ACL is not checked unless “Enforce Consistent ACL” isset to “true” This in itself is not a security feature and may be bypassed• Web users are also governed by “Maximum ACL Level”
  • 29. 29Application 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)
  • 30. 30Reader/Author Fields Layer• Reader fields dictate who is allowed to read thisdocument• Author fields dictate who is allowed to modify adocument, if their ACL level is set to “Author”• You may have more than one Reader/Author field in adocument• You may have more than one item in the field• You may embed Roles into this field e.g., “[Administrators]”: “LocalDomainAdmins”: “*/Acme”
  • 31. 31Reader/Author Fields: Best Practices• Common mistakes include: Losing access to documents NOT setting the Reader/Access field as an Array fromLotusScript “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 NOTknow how to do this Don’t be one of those!
  • 32. 32Reader/Author Fields: ExamplePublic Function setAuthorsField( doc As NotesDocument, _fieldName As String, newName As String) As IntegerDim nn As New NotesName(newName)Dim S(2) As StringS(0) = "LocalDomainAdmins"S(1) = "[Administrators]"S(2) = nn.CanonicalDim itm As NotesItemSet itm = doc.ReplaceItemValue(fieldName, S)Itm.IsReaders = TrueEnd Function
  • 33. 33Field-Level Encryption Layer• If a user requires access to a document and should NOTsee particular fields, then field-level encryption shouldbe 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
  • 34. 34Encryption 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 asecure repository (a safe!), password protected, andphysically disconnected from any computer system For instance, on a CD-ROM and a piece of paper!
  • 35. 35Public 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 user’s public key• Attractive for: Optional encryption of particular documents for groupsof users Can be completely hidden from the end-user Does not inject new items into the ID file
  • 36. 36Field-Level Encryption Compared• Why use encryption keys? Because only the people who possess the encryption key canparticipate Far better from an auditing point of view New users can “see” documents without the documentshaving to be updated• Why use public key encryption? No distribution of IDs required Ad hoc encryption of documents is made more simple
  • 37. 37DemoDemoBrief overview ofEncryption Keys
  • 38. 38What We’ll Cover …• Overview• Agent Manager introduction• Agent Manager deep dive• Security introduction• Security deep dive• Calling the C API security interfaces from LotusScript• Summary
  • 39. 39Calling 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• Let’s focus on two: REGGetIDInfo: Get information about an ID file SECKFMChangePassword: Change a password on an ID file
  • 40. 40Calling 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
  • 41. 41Calling 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
  • 42. 42Calling C API Security Interfaces: REGGetIDInfo (cont.)• Therefore, to find out if an ID is a certifier:Dim strCertifierPath As String, fIsCertifier As LongDim actualLen As Integer, LerrrorValue as LongfIsCertifier = 0Lerrorvalue = W32_REGGetIDInfo_BOOL( _strCertifierPath, _REGIDGetCertifierFlag, _flsCertifier, _4, _actualLen) _If (flsCertifier) thenPrint “Certifier: “ + strCertifierPath + “ is a certifier”ElsePrint “Certifier: “ + strCertifierPath + “ is NOT a certifier”End if
  • 43. 43Calling C API Security Interfaces: REGGetIDInfo (cont.)• To find out the name of this certifier:Dim strCertifierPath As String, strIDName As StringDim myName As String*1024, actualLen As IntegerDim Lerrorvalue as longLerrorvalue = W32_REGGetIDInfo_STRING (_strCertifierPath, REGIDGetName, myName, 1024,actualLen)If Lerrorvalue <> 0 ThenPrint “Failed during REGGetIDInfo “ElseIf actualLen = 0 ThenPrint "Did not get a name from this ID file"ElsestrIDName = Left(myName, actualLen)Print “This ID name is: " + strIDNameEnd IfEnd if
  • 44. 44Calling C API Security Interfaces: SECKFMChangePassword• SECKFMChangePassword allows you to change thepassword on an ID file You have to know the previous password The new password has to conform to certifier passwordrestrictions• We need to use the following function declaration:Declare Function W32_SECKFMChangePassword Lib LIB_W32Alias {SECKFMChangePassword} (_Byval IDFileName As Lmbcs String, _Byval OldPass as Lmbcs String, _Byval NewPass as LMBCS String) As Integer
  • 45. 45Calling C API Security Interfaces:SECKFMChangePassword (cont.)• So to change a password:Dim strIDName As String, oldPass As StringDim newPass as String, Lerrorvalue as longLerrorvalue = W32_SECKFMChangePassword (_strIDName, oldPass, newPass)If Lerrorvalue <> 0 ThenPrint “Failed during SECKFMChangePassword “ElsePrint “ID :” +strIDName+ “ has changed password from: ”+_oldPass + “ to: ” + newPassEnd if
  • 46. 46What We’ll Cover …• Overview• Agent Manager introduction• Agent Manager deep dive• Security introduction• Security deep dive• Calling the C API security interfaces from LotusScript• Summary
  • 47. 47Resources• My “Leveraging the Power of Object OrientatedProgramming in LotusScript” presentation• Steve McConnell, Code Complete, Second Edition,(Microsoft Press, 2004).• Normunds Kalnberzin, LotusScript to Lotus C APIProgramming Guide, (November 2003).• “Lotussphere 2004 : AD104 — LotusScript Tips andTricks” in the Lotus Sandbox
  • 48. 48Resources (cont.)• NSFTools — Notes Tips• The Notes FAQ!• Brian Benz and Rocky Oliver, Lotus Notes and Domino6 Programming Bible, (Wiley, John & Sons,Incorporated, 2003).• Notes.Net (of course)
  • 49. 497 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
  • 50. 50Your Turn!How to contact me:Bill