Sign upLogin

alsutton/enterprisepasswordsafe

View on GitHub
Star
docs/manual.htm

Summary

Maintainability
Test Coverage
<!DOCTYPE html>
<html>
<head>
<meta name="generator" content="HTML Tidy for HTML5 for Windows version 5.4.0">
<meta http-equiv="Content-Type" content="text/html">
<title>Enterprise Password Safe</title>
</head>
<body lang="EN-GB">
<h1>Enterprise Password Safe Manual</h1>
<h2>Licensing</h2>
<p>The Copyright (c) 2017 Carbon Security Ltd. opensource@carbonsecurity.co.uk and contributors</p>
<p>Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted,
provided that the above copyright notice and this permission notice appear in all copies.</p>
<p>THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR
CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.</p>
<h2>Introduction</h2>
<p>The Enterprise Password Safe provides a centralised password repository and maintains an audit trail of accesses to the
stored passwords. The EPS has numerous security enhancing features such as;</p>
<ul>
<li>Restricted Access Passwords which require other users to approve access to passwords</li>
<li>The EPS encryption chain which ensures that passwords are not accessible without breaking at least one of the currently
established encryption standards.</li>
<li>All password data encryption is performed in application memory to avoid data being transmitted or stored in an unencrypted
form.</li>
<li>SMTP Email alerts sent to administrators when passwords are accessed.</li>
</ul>
<h2>Configuration matrices</h2>
<p>To assist with the creation of users and the correct assignment of accessing and viewing rights we recommend using a
spreadsheet which has the following three parts;</p>
<ol>
<li>A User List; This list contains all of the people who will be using the EPS.</li>
<li>A Group List; This list contains all of the groups that will be created in the EPS and the users from section 1 who belong
to the group.</li>
<li>A Password list; This list contains all of the passwords which will be managed by the EPS, a list of which groups have read
only access, which groups have modification access, which users have read only access outside of the groups they belong to, and
which users have modification access outside of the groups they belong to.</li>
</ol>
<p>The lists would look similar to the ones below;</p>
<h3>Users</h3>
<table border="1">
<tr>
<td>Username</td>
</tr>
<tr>
<td>alice</td>
</tr>
<tr>
<td>bob</td>
</tr>
<tr>
<td>charlie</td>
</tr>
</table>
<h3>Groups</h3>
<table border="1">
<tr>
<td>Group name</td>
<td>Members</td>
</tr>
<tr>
<td>Server Admins</td>
<td>alice, bob</td>
</tr>
<tr>
<td>Tech. Services</td>
<td>charlie</td>
</tr>
</table>
<h3>Passwords</h3>
<table border="1">
<tr>
<td>Password</td>
<td>Groups<br>
(read only)</td>
<td>Groups<br>
(modify)</td>
<td>Users<br>
(read only)</td>
<td>Users<br>
(modify)</td>
</tr>
<tr>
<td>root on svr01</td>
<td>&nbsp;</td>
<td>Server Admins</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr>
<td>nagios on svr01</td>
<td>Tech Services</td>
<td>Server Admins</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr style='mso-yfti-irow:3;mso-yfti-lastrow:yes'>
<td>DOMAIN\Administrator on winsvr1</td>
<td>Server Admins</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>bob</td>
</tr>
</table>
<h2>Installation</h2>
<p>You will need to run your own Java Servlet Engine (e.g <a href="http://tomcat.apache.org/">Apache Tomcat</a>) to deploy the
EPS. The must support Java 5 or above, the Java Servlet specification version 2.4 and above, and Java Server Pages (JSPs)
version 1.2 and above.</p>
<p>To connect to your database of choice you will need to install a JDBC driver for it in your chosen servlet engine. For
Apache Tomcat you can do this via the following process;</p>
<ol>
<li>Download the appropriate Type 4 JDBC driver from your database vendor.</li>
<li>Ensure the EPS is not running.</li>
<li>Copy the driver files into the lib directory within the jetty directory inside your EPS installation directory.</li>
<li>Start the EPS.</li>
</ol>
<p>You should then configure the connection to the database from the Database option available on the left hand menu when you
log in as an administrator.</p>
<p>If you choose to use an alternative application server you should consult your application server vendor for instructions on
how to install JDBC drivers.</p>
<h2>Default user details</h2>
<p>After installation the only user available has the user name <i>admin</i> and the password <i>admin</i>.</p>
<p>We recommend that you change the password for this user as soon as you log into the system.</p>
<h2>Page Layout</h2>
<p>All EPS pages have the same design, an example of which is shown below;</p>
<p><img src="image002.gif" alt="EPS Screenshot"></p>
<p>There are four main areas to any EPS page;</p>
<ol>
<li>The account bar at the top of the page which contains information and options relating to the user currently logged
in.</li>
<li>The page title shown in the area with the dark blue background below the account bar.</li>
<li>The action menu of the left of the page showing the actions available to the user</li>
<li>The main area where the information is shown.</li>
</ol>
<p>The options on the action menu will change depending on type of user logged in. The example above shows all of the options
available to a full administrator.</p>
<h2>The password hierarchy</h2>
<p>The password hierarchy allows passwords to be categorised into folders, and each folder may contain passwords and
sub-folders that contain further folders and passwords without limit. The hierarchy can be viewed by clicking on the
<i>View/Edit</i> option under the <i>Passwords</i> heading from the menu.</p>
<p>The password hierarchy has a separate set of permissions that allow administrators to control access to passwords based on
their location in the hierarchy. The hierarchy permissions take precedence over individual permissions when denying access to
passwords, therefore if a password <i>User @ System</i> is stored in a folder X, and a user has access read rights to the
password, but does not have access rights to the folder, the user will not be able to see the password, and any searches will
not include the password. It should be noted that permissions can not be set for the top level folder because it is the
starting place for all users when the log in.</p>
<h2>Editing the password hierarchy</h2>
<p>EPS administrators can modify the password hierarchy by clicking on the Edit Hierarchy link when viewing the password
hierarchy. Clicking on this link allows administrators to edit the location of passwords and set hierarchy permissions for
users and/or groups.</p>
<p>Whilst editing the hierarchy you can add new folders to the current level, copy, deep copy, cut, or delete sub-folders and
passwords, or navigate through the hierarchy in order to make modifications elsewhere.</p>
<p>Copy will only create copies of things you have selected; <i>Deep copy</i> will create copies of the things you have
selected as well as anything contained in the folders you have selected. For example if you have a folder called X and within
it there is a password Y, if you <i>copy</i> X to another location you will get an empty copy of X. If you <i>deep copy</i> X
to another location you will get a copy of X containing a copy of Y.</p>
<p>Administrators can also set the user and group permissions whilst editing the hierarchy by clicking on the User Permissions
tab or Group Permissions tab, and setting the appropriate rights for the users alter the user and group permissions. Please
note that user permissions will take precedence over group permissions, therefore if you deny access to a group.</p>
<h2>Importing data from files</h2>
<p>Users, groups, passwords, and the permissions linking them can be imported from text files using the Import options
available from the menu. All import files must start with a single line containing the letters EPS.</p>
<p>The users file consists of a series of lines, each containing a user name, full name, email address, and optionally the user
type and a password separated by commas. For example, importing a file containing the following three entries;</p>
<pre>alice, Alice Smith, alice@carbonsecurity.co.uk
bob, Bob Bloggs, bob@carbonsecurity.co.uk, N, block
charlie, Charlie Jones, charlie@carbonsecurity.co.uk, P</pre>
<p>Creates a user called <i>alice</i> who is a normal user and whose password will be generated by the EPS, a user called
<i>bob</i> who is also a normal user and whose password is <i>block</i>, and a user called <i>charlie</i> who is a password
administrator and whose password is created by the EPS.</p>
<p>If an SMTP Server has been set in the configuration screen and the email address for an imported user isn't blank the user
will be sent an email informing them that an account has been created for them.</p>
<p>Group files consist of the name of the group, a comma, and then a list of users separated by commas. For example, a file
containing the following two entries;</p>
<pre>group1,alice,bob
group2,alice,charlie</pre>
<p>creates two groups called <i>group1</i> and <i>group2</i>, and puts <i>alice</i> in both <i>group1</i> and <i>group2</i>,
puts <i>bob</i> in <i>group1</i> only, and <i>charlie</i> in <i>group2</i> only.</p>
<p>Passwords and permissions can be imported using the following format for each line;</p>
<p>System Name, User name, Password, Notes, Audit Policy, Record History</p>
<p>This can optionally be followed by a comma-separated list of custom fields. The custom fields must be of the following
format;</p>
<pre>CF:name=value</pre>
<p>Followed by a comma-separated list of permissions. Each permission consists of a U or G to represent if the permission is
for a User or Group, then a V or M to represent if that user or group should be allowed to view or modify the password, a
colon, and then the name of the user or group.</p>
<p>The <i>Audit Policy</i> can be set to <i>full</i> for to log and send alerts for accesses, <i>log</i> to only log the
access, or <i>none</i> to do nothing. If the Record History section can be either set to true to record all historical versions
of the password, or false to only retain the current version.</p>
<p>For example a file containing the following two entries;</p>
<pre>
system1, username1, pwd1, some notes, full, true, UV:alice, UM:bob
system1, username2, pwd2, notes, none, false, GM:group1, UV:charlie</pre>
<p>Will create two passwords both of which will be for system<i>1</i> with the following characteristics;</p>
<p>The first line creates an entry with the user name <i>username1</i> and the password <i>pwd1</i>, the user <i>alice</i> will
be able to view the password, and the user <i>bob</i> will be able to modify the password. When users access the password the
access will be fully audited (resulting in the access being logged and an alert sent), and all historical versions of the
password will be recorded.</p>
<p>The second line will create an entry with the user name <i>username2</i>, and the password <i>pwd2</i>. The group called
<i>group1</i> will be able to modify the password and the user <i>charlie</i> will be able to view the password. Accesses to
this password will not cause a log message or alert to be generated, and the EPS will not store historical versions of the
password.</p>
<p>When you import passwords they will be placed into the password hierarchy at the location you had most recently viewed.</p>
<p>All of the import features will display a page which allows you to select the file you wish to import, and will present you
with a report once the information has been imported.</p>
<h2>Password creation</h2>
<p>To create passwords select the <i>Create</i> option from the <i>Passwords</i> menu. A page will be displayed which allows
you to enter all of the information relevant to a password. Once you have entered all of the information requested click the
Create button. You will then be taken to a page that will allow you to set which users and groups have access to the newly
created password.</p>
<p>Passwords can have the <i>Restricted Access</i> feature enabled which will stop any user accessing the password without
approval from one or more other users. When enabling restricted access on a password you <b>must</b> ensure that you create
enough restricted access approvers. If you create a password that requires 2 RA approvers to approve access, and you only have
1 user defined as a restricted access approver, no-one will be able to access the password. Restricted Access applies to <b>all
users</b>, this means that even administrators will not be able to view a password without approval if restricted access is
enabled for it.</p>
<p>The Restricted Access also allows approvers to block a request to view a password using the <i>Blockers required</i> field.
If 3 approvers have been defined, and the password has the <i>Blockers required</i> field set to 1, if any of the approvers
denies the users request to view the password the users request will be denied.</p>
<p>It is possible to specify a set of custom fields to be included in new passwords by selecting the <i>Custom Fields</i>
option under the System title from the menu on the left of the page.</p>
<h2>Password deletion</h2>
<p>Passwords should be deleted through the hierarchy editor. You can select the box to the left of the password or passwords
you wish to delete, then choose <i>Delete Selected</i> from the <i>Action</i> drop down menu and click <i>Go</i>. Passwords are
not recoverable after deletion; so do not delete passwords which you may need at a later point in time.</p>
<h2>Password modification</h2>
<p>You can modify a password by selecting it from either the password hierarchy, the results of a search, or any other location
where you can view a password. Selecting the <i>Edit Details</i> option from the screen on which the password displayed will
take you to a screen that will allow you to edit all of the details of the password.</p>
<h2>Password restrictions</h2>
<p>This option allows administrators to create various policies controlling the characters that must be present in passwords.
An administrator can create any number of policies, and each policy can be associated with one or more passwords. The
restriction policy is set by administrators when the create or edit a password.</p>
<h2>Edit password access controls</h2>
<p>Altering access to a password can be performed after selecting the Alter Access option when viewing a password has created
the password. A page will be displayed with allows you to update the type of access that groups and users are allowed. For each
user and group you wish to change you will need to select the appropriate access rights and then click the <i>Update group
access</i> or <i>Update user access</i> button accordingly.</p>
<h2>Personal Password Folder</h2>
<p>Each user has a personal password storage area that contains password that only they can view. Clicking on the
<i>Personal</i> option under the Passwords title in the menu on the left of the page will access this area.</p>
<h2>Outstanding Restricted Access Requests</h2>
<p>The <i>RA Requests</i> option in the menu on the left shows the user any restricted access requests they have not approved
or denied.</p>
<h2>User creation</h2>
<p>To create users manually you should select the <i>Create</i> option from the <i>Users</i> menu. You should enter the details
requested in the spaces provided and click the Create button. Upon clicking the button you will either be shown any problems
with the details supplied, or, if the creation of the user is successful, you will be taken to a screen allowing you to alter
the users status, type, and group memberships.</p>
<h2>User deletion</h2>
<p>Users can be deleted from the system by selecting the <i>Delete</i> option under the <i>Users</i> heading. To delete a user
(or group of users) you should check the box to the left of the user name and then click the <i>Delete Users</i> button, and
then confirm the deletion.</p>
<h2>User modification</h2>
<p>To edit a user select the <i>View/Edit</i> option from the <i>Users</i> menu, a page will be displayed offering you a list
of all the users available in your installation of the EPS. Click on the user you wish to alter and you will be taken to the
user-editing screen.</p>
<p>The user type affects how a user can interact with the EPS. An <i>EPS Administrator</i> has full access to all of the
administration functions of the EPS. A <i>Password Administrator</i> only has the ability to create passwords and alter the
access other users have to any passwords to which the password administrator has modification rights. A <i>Normal User</i> can
only perform the actions available to them via the password access control system.</p>
<p>Altering the groups a user belongs to is performed by clicking on the group name. If the group is listed under the heading
<i>Current Membership</i> the user is already a member of that group and clicking on the group name will remove them from the
group. If a group is listed under the heading <i>Available Groups</i> then the user is not a member and clicking on the group
name will make them a member of that group.</p>
<p>Login restrictions are based around Network Zones (which are defined by clicking on the <i>Network Zones</i> option in the
<i>System</i> menu). The defined network zones are displayed and the administrator can select either <i>Treat as unknown</i>,
<i>Allow</i>, or <i>Deny</i>. If <i>Treat zone as unknown</i> is selected the setting for <i>Allow users to log in from unknown
network zones</i> in the Configuration page will determine if the user can log in from that zone or not.</p>
<h2>User authentication</h2>
<p>Users login passwords can be checked against external systems, but the EPS must maintain a copy of their password in order
to allow the password access controls to function properly.</p>
<p>If you wish to user an external system to authenticate a user you should select <i>Authentication</i> from the <i>Users</i>
menu, which will take you to a page showing any authentication sources that have already been defined. You may edit any of
these, or you may create a new authentication source by clicking on the <i>Create New Source</i> link.</p>
<p>The available types of authentication source will be shown to you if you decide to create a new authentication source, you
should select the most appropriate and enter the information requested. Please note that some authentication sources may
require modifications to your external authentication systems, any modifications necessary will be shown on the page relating
to that authentication source.</p>
<p>Once you have created your authentication source you can edit the user you wish to associated with the source and select the
name of the source from the drop down list beside the words <i>Authenticated by</i>, you should then click on <i>Update
Details</i> to store the change in authentication source.</p>
<p>If a user changes their password in the external authentication source and log into the EPS without changing their EPS
password they will be asked to synchronize the two. Once the synchronization has taken place they will be allowed to continue
as normal.</p>
<h2>Group creation</h2>
<p>Groups can be created manually using the <i>Create</i> option on the <i>Groups</i> menu. Once you have entered the name of
the group you wish to create in the box provided you should click the Create button, which will take you to the screen that
allows you to select which users should be part of the group.</p>
<h2>Group deletion</h2>
<p>Groups can be deleted using the <i>Delete</i> option under the <i>Groups</i> heading of the action menu.</p>
<p>Deleting a group will erase all of the access permissions any member of the group had to any of the passwords, you should
therefore ensure that you are not removing a group whose access rules are relied upon for your daily operations.</p>
<h2>Group modification</h2>
<p>You may alter which users belong to a group after the group has been created by selecting the <i>View/Edit</i> option on the
<i>Groups</i> menu.</p>
<p>If users are listed under the <i>Non-Members</i> heading they may be added to the group by clicking on their user name,
similarly if a user needs to be removed from a group their user name will appear under the <i>Current Members</i> heading and
the user name can be clicked on to remove them from the group.</p>
<h2>Audit logs</h2>
<p>The EPS maintains a log of accesses to passwords (where the password is set to be audited), user manipulation, and group
modification. The recorded actions can be viewed using the <i>View</i> option from the <i>Events</i> menu. When you select this
option a page will be displayed showing the time and date of each audit event along with the user involved, a summary of the
password involved (if there was one), the action which was performed, and, if available, a tamper stamp status.</p>
<p>Some events cannot have tamper stamps associated with them due to the action not involving a logged in user (such as failed
login attempts). Where a tamper stamp is available it will show as <i>Untampered</i> if an audit log entry has been verified as
not being altered outside of the EPS. If an entry appears as <i>Tampered</i> then a third party has attempted to modify the
entry, and it should be treated with suspicion.</p>
<p>The event log can be filtered by date ranges or to a specific user. These filters are shown at the top of the log, and once
changed you must click the <i>Update view</i> button to show the newly filtered entries.</p>
<p>The audit events can be exported by selecting <i>CSV File</i> in the drop down box beside <i>Output To :</i>.</p>
<h2>Audit alerts</h2>
<p>The EPS has the ability to send an Email containing details of any audited event via an SMTP Email Server. To set-up audit
alerts select the <i>Settings</i> option from the <i>Events</i> menu.</p>
<p>There are several types of alert which can be sent via email, you should select which types of events you wish to be sent
alerts about, enter the email address you wish alerts to go to, and whether or not you want to send an Email to the user
involved in any actions when they are recorded in the event log.</p>
<p>Once you have set these options you should click <i>Update settings</i> to store these values.</p>
<p>If the EPS is unable to send an alert for any reason it will store the error message in the audit logs.</p>
<h2>Configuration options</h2>
<p>Selecting <i>Configuration</i> from the <i>System</i> menu will allow you to alter various options related to the EPS's
operation. We recommend administrators visit this page in order to verify the settings comply with their existing security
policies and procedures. The available settings are as follows;</p>
<h3>Appearance</h3>
<p><i>URL for your logo (optional)</i></p>
<p>This option allows you to specify the URL of an image that will be displayed in the top right hand corner of all of the EPS
web pages.</p>
<h3>Email Settings</h3>
<p><i>SMTP Host</i></p>
<p>This should be set to the host name of a server through which all email notifications should be routed. This includes
notifications of restricted access requests, so it is vital that you set this if you wish to use restricted access passwords
effectively. The server must be able to accept emails using the SMTP protocol, and should be able to deliver email to all of
the email addresses you have associated with your users.</p>
<p><i>Emails will appear to be from</i></p>
<p>This option should be set to the address that you wish any restricted access notifications or audit alerts to come from. You
should remember that users may reply to these emails and thus you may want to make this the address of a monitored list.</p>
<h3>User Logins and Sessions</h3>
<p><i>Maximum failed login attempts before an account is locked</i></p>
<p>This is the number of times a user may incorrectly enter their password before the system will deactivate their account.</p>
<p><i>Allow users to log in from unknown network zones</i></p>
<p>This can be used to stop users logging in from a network zone which not been defined using the Network Zones. Please Note;
Setting this to No will stop the <i>admin</i> user from logging in. Only set this to No if you have already created another EPS
administrator user.</p>
<p><i>Maximum time a user can be inactive before being automatically logged out</i></p>
<p>This sets the maximum time in minutes a user can be inactive before the system will require them to re-login.</p>
<p><i>Default Authentication Source</i></p>
<p>This sets the default authentication source for new users created either via a browser or imported.</p>
<h3>Password Hierarchy</h3>
<p><i>Hide folders containing no user accessible passwords</i></p>
<p>This setting allows you to show or hide empty folders in the password hierarchy.</p>
<p><i>Default Hierarchy Access Rule</i></p>
<p>This option allows you to allow or deny access to folders within the password hierarchy for users who do not have explicit
rights to the folder.</p>
<p><i>Allow password administrators to edit the hierarchy</i></p>
<p>Setting this to Yes will allow users designated as password administrators to edit and create the folders in the password
hierarchy</p>
<h3>Password Display</h3>
<p><i>Restricted access request lifetime</i></p>
<p>This specifies the maximum amount of time (in minutes) between when the user entering a reason for wishing to view a
restricted access password, and when they can view it. All requests must be approved, and the user must view the password
within this time. Once the access has been approved the user will have access to the password for the specified period of
time.</p>
<p><i>RA approvers can vote on their own requests.</i></p>
<p>This option allows restricted access request users to vote when they try to access passwords they are restricted access
request approver for.</p>
<p><i>Require a reason for a viewing password</i></p>
<p>This specifies if users viewing non-restricted access passwords should be forced to enter a reason for viewing the
password.</p>
<p><i>Hide system list when editing or creating passwords</i></p>
<p>When set to <i>Yes</i> all users not be shown a list of already existing systems in the password creation and editing
pages.</p>
<p><i>Passwords are initially</i></p>
<p>This determines if a password is initially shown or hidden when the user views the password. Showing and hiding passwords
requires JavaScript to be enabled on the users browser.</p>
<p><i>Passwords shown as</i></p>
<p>This specified if passwords should be displayed as images or text.</p>
<p><i>Maximum time password is on screen</i></p>
<p>If JavaScript is enabled on the users browser this option will remove the password from the users view after the specified
period of time.</p>
<p><i>Allow the use of the browser back button to review a password</i></p>
<p>This specifies if the user should be allowed to click their browsers back button to return to viewing a password after they
have moved to another page.</p>
<p><i>Allow password administrators to view password audit events</i></p>
<p>If set to Yes this option allows password administrators to view a passwords event history.</p>
<h3>Password Editing</h3>
<p><i>Maximum number of days in the future an expiry date can be</i></p>
<p>This sets a hard limit for the number of days in the future an expiry date can be.</p>
<p><i>Hide password during creation and editing</i></p>
<p>If set to yes all passwords will replaced with asterisks when entering them in the password creation or editing screen, if
set to no the passwords will be shown in clear text.</p>
<p><i>Reject use of historical expiry dates</i></p>
<p>If set to Yes users will not be able to enter dates in the past for the expiry date of a password.</p>
<h3>Password Retention and Auditing</h3>
<p><i>Password History Retention</i></p>
<p>This specified whether or not a user creating or editing a password is allowed to set the history retention policy for a
password. If this option is set to <i>Choose when password is created</i> the user will be allowed to set the retention
policy.</p>
<p><i>Password Auditing Level</i></p>
<p>This option specified if a user creating or editing a password can set the auditing policy for passwords. If set to
<i>Configurable</i> the user will be allowed to set the auditing policy.</p>
<h3>Miscellaneous Options</h3>
<p><i>Separator for reports</i></p>
<p>This option sets the separator for the fields of any report generated by the EPS.</p>
<h2>Database configuration</h2>
<p>Selecting the <i>Database</i> option from the <i>System</i> menu will allow you to alter the access details for the database
storing the passwords in the password safe. Please note that if you change the JDBC URL the information in the current database
will <b>NOT</b> be transferred automatically to the new database and you will need to log in again using details valid for the
new database.</p>
<h2>Systems details</h2>
<p>Selecting the <i>Details</i> option from the <i>System</i> menu will take you to a screen that lists several pieces of
information which relate to the environment in which the EPS is running. If you wish to report a problem with your installation
of the EPS you should include this information to help us reproduce the issue.</p>
<h2>Integration modules</h2>
<p>The <i>Integration</i> option under the <i>System</i> menu allows administrators to install integration modules and develop
scripts that in turn allow the EPS to alter the passwords of remote systems. Each module may have one or many scripts
associated with it which can be assigned to passwords.</p>
<p>For details about the scripting language used by a particular module please consult the relevant manual or information sheet
for the module. For details on developing integration modules please see Appendix A.</p>
<h2>Network zones</h2>
<p>The <i>Network Zones</i> option under the <i>System</i> menu allows an administrator to define, edit, and delete IP address
ranges which can be applied to users to control which networks a user can log in from. Network zones can be specified in IPv4
or IPv6 depending on your network infrastructure.</p>
<p>Selecting the <i>All Passwords</i> option from the <i>Reports</i> menu will allow you to download the details of all
passwords stored in the system. Please note the passwords will <b>NOT</b> be encrypted and this feature should only be used
when you wish to create a human readable copy of your passwords that will be stored in a safe location.</p>
<p>Selecting the <i>User Access</i> option from the <i>Reports</i> menu will allow you to download a comma-separated value
(csv) file that contains details of the passwords users and groups have access to. The CSV file can be imported into many
popular applications (such as Microsoft Excel or OpenOffice Calc).</p>
<h2>Tips</h2>
<p>The following are some pieces of information you may find useful whilst using the EPS</p>
<ul>
<li>The default inactivity before a user is automatically logged out is 30 minutes. After 25 minutes if the user has JavaScript
enabled on their browser the background of the current page will change colour.</li>
<li>The EPS places no special requirements on the database it uses. Any backup tool capable of correctly backing up and
restoring a database from you database software can be used to backup and restore the information stored in the EPS.</li>
<li>The password, group, and user data is only stored in the database, therefore moving the EPS between servers can be
performed by transferring the database to an appropriate location and/or installing the EPS from scratch on the new
machine.</li>
</ul>
<hr>
<h1>Appendix A - Developing integration modules</h1>
<p>It is possible to implement custom integration modules which allow the EPS to change the password on remote systems. The
modules must implement the Java interface uk.co.argosytelcrest.passwordsafe.integration.PasswordChanger, and must be available
to the EPS via the class path set by the application server.</p>
<p>The <i>PasswordChanger</i> interface requires the following methods to be implemented;</p>
<pre>public void install(java.sql.Connection conn) throws Exception;
public void uninstall(java.sql.Connection conn) throws Exception;
public List getProperties();
public void changePassword( java.sql.Connection conn, java.util.Map pluginProperties, java.util.Map passwordProperties, String script )throws RemoteException, IOException;
public void rollbackChange( java.sql.Connection conn, java.util.Map pluginProperties, java.util.Map passwordProperties, String script ) throws RemoteException, IOException;</pre>
<p>The <i>java.sql.Connection</i> object passed to the relevant methods provides a connection to the EPS database. We recommend
that any tables you create begin with a prefix that clearly identifies them (e.g. <i>myldap_table</i>).</p>
<p>The pluginProperties <i>Map</i> passed to the <i>changePassword</i> and <i>rollbackChange</i> methods contains the settings
the user has specified for any module specific parameters. The map key is the internal name for your module property, and the
value is a String containing the value the user has set for this password.</p>
<p>The passwordProperties <i>Map</i> passed to the <i>changePassword</i> and <i>rollbackChange</i> methods contains values
specific to the password being changed. These are;</p>
<dl>
<dt>username</dt>
<dd>The user name associated with this password.</dd>
<dt>old_password</dt>
<dd>The original value for the password.</dd>
<dt>new_password</dt>
<dd>The value the password should be changed to.</dd>
<dt>system</dt>
<dd>The system on which the change should take place.</dd>
</dl>
<p>The script <i>String</i> passed to the <i>changePassword</i> and <i>rollbackChange</i> methods contains the script to be
executed for this password.</p>
<p>The <i>getProperties</i> method returns a <i>List</i> of <a href=
"https://github.com/carbonsecurity/enterprisepasswordsafe/blob/master/src/main/java/com/enterprisepasswordsafe/engine/integration/PasswordChangerProperty.java">
PasswordChangerProperty</a> objects which contain the details of the properties specific to the integration module. The
<i>PasswordChangerProperty</i> objects should be constructed using the following constructor;</p>
<pre>
public PasswordChangerProperty( String internalName, String displayName, String description, String defaultValue)</pre>
<p>Where <i>internalName</i> is the name that will be used for the parameter when the pluginProperties Map is constructed,
<i>displayName</i> is the name shown to the user when they are asked to set the values which will be held in the
pluginProperties Map, <i>description</i> is an optional description which is currently not used, and <i>defaultValue</i> should
contain a sensible default for the property</p>
<hr>
<h1>Appendix B - External API</h1>
<p>The EPS allows users to search for, fetch, and update passwords via an HTTP API. All parameters must be passed using HTTP
POST, and all results will be returned in the body of the response.</p>
<h2>Common Parameters</h2>
<p>The parameters used by all of the calls are as follows;</p>
<dl>
<dt>username</dt>
<dd>The name of the user the request should be audited under.</dd>
<dt>password</dt>
<dd>The users password.</dd>
</dl>
<h2>Search for a password or passwords</h2>
<h3>URL</h3>
<p>http://[servername]/passwordsafe/api/FindIds</p>
<h3>Additional Parameters;</h3>
<dl>
<dt>searchUsername</dt>
<dd>The username of the password required.</dd>
<dt>searchSystem</dt>
<dd>The system the password is on.</dd>
</dl>
<h3>Response</h3>
<p>The response will contain the id or ids of the passwords with the given username in the given system.</p>
<h2>Get a password</h2>
<h3>URL</h3>
<p>http://[servername]/passwordsafe/api/GetPassword</p>
<h3>Additional Parameters</h3>
<dl>
<dt>id</dt>
<dd>The id of the password to fetch.</dd>
</dl>
<h3>Response</h3>
<p>The password. The response will <b>only</b> contain the text from the password field.</p>
<h2>Update a password</h2>
<h3>URL</h3>
<p>http://[servername]/passwordsafe/api/UpdatePassword</p>
<h3>Additional Parameters</h3>
<dl>
<dt>id</dt>
<dd>The ID of the password to update.</dd>
<dt>newPassword</dt>
<dd>The value to set the password field to.</dd>
</dl>
<h3>Response</h3>
<p>The password. This response should always match the value set in newPassword.</p>
</body>
</html>