Chapter 12. Finding and Fixing Problems: the pidiag Utility
6.9 Trust Login Security
6.9.7 Examples
The PI Server compares incoming connection credentials with every Trust Login record. Each field in a trust record is compared to the corresponding credential field. Every field that is not blank in the Trust Record must exactly match the passed credentials. Otherwise, the authorization is not granted. When an authorization is refused for one trust record, the PI Server continues to search the other records until it has exhausted the possibilities. You can create explicit individual trust records for each interface or you can group them according to subnet, host machine, or username. A group of interfaces can share the same privileges, based on matching a name in the User Database.
As explained previously, if IPAddr and Netmask fields are blank, they appear as 0.0.0.0.
Examples Restricted to Particular Client Applications or Remote Nodes
If a trust record includes only a truncated application name, only a PI API client application may be authorized. It might be advisable to include an additional restriction on Host name and/or IP address at the same time.
If a trust record includes only a full application executable file name, only a PI-SDK client application may be authorized. It might be advisable to include some additional restriction as well, based on one of the other optional fields.
A remote PI API node or PINet node may be specified by Fixed IPAddress or by IPHost name.
Example 1. Restricted to a Particular PI API Client Application
The trust record shows only three entries:
Trust record name
AppName = randE
PIUser name = IFGroupA.
An AppName that is four characters and “E” indicates a PI API application. “Rand” is the truncated name for the Random Interface.
The incoming credentials show:
AppName = randE, which matches the trust record
IPAddr and IPHost, which are blank in the trust record
Therefore, authorization to use the privileges of IFGroupA would be granted to the connecting Random Interface.
Trust Record Connection Credentials
Field Name Field Value Match? Name Value
Trust APIIF1
Trust Record Connection Credentials
Domain Domain
IPAddr 0.0.0.0 IPAddr 192.168.168.121 Netmask 0.0.0.0
IPHost IPHost Suzanne2
OSUser OSUser
PIUser IFGroupA
Example 2. Restricted to Particular PI SDK Client Applications
The trust record shows only 3 entries:
trust record name AppName = piperfmon.exe PIUser name = IFGroupB.
The incoming credentials show:
AppName = piperfmon.exe IPAddr = 192.168.168.121 IPHost = Vaughan
This application name includes the .exe extension, indicating a PI-SDK application. The application is running on Windows 98, because Domain and OSUser are blank.
Therefore, because AppName is the only specification in the trust record, and the incoming credentials include a matching AppName, then authorization to use the privileges of ‘IFTypeB’ would be granted to the connecting Performance Monitor Interface.
Trust Record Connection Credentials
Field Name Field Value Match? Name Value Trust SDKIF1
AppName piperfmon.exe yes AppName piperfmon.exe
Domain Domain
IPAddr 0.0.0.0 IPAddr 192.168.168.121 Netmask 0.0.0.0
IPHost IPHost Vaughan
OSUser OSUser
6.9 - Trust Login Security
Example 3. Specific PI API Application from a Specific Remote Node
The following example trust (GTinterface) allows a specific PI API application (GTin) from a particular remote IPHost (GT55) and IP address (123.123.123.22) the rights of a PI user
Operator1.
* (Ls - PITRUST) Piconfig> @mode create * (Cr - PITRUST) Piconfig> @istru
trust,IPHost,ipaddr,netmask,appname,piuser
* (Cr - PITRUST) Piconfig> GTinterface,GT55,123.123.123.22, 255.255.255.255,GTinE,Operator1
Example 4. Any PI API Application from a Specific Remote Node with a Fixed IP Address
The following example creates a trust record that would match any PI API application from a remote PI API node or VMS-based PINet remote data collection node with a fixed IP
address.
The trust record would allow the interface from a data source to write to the PI Server, just as the former Proxy Database did. Assume the entry in the User Database will be IFUser1.
@table pitrust @mode create
@istru Trust,IPAddr,Netmask,PIUser
MyTrust1,206.79.198.12,255.255.255.255,IFUser1 @endsection
Example 5. Any PI API Application from a Remote Node by Node (IPHost) Name
The following example creates a trust record that would match any PI API application from a remote PI API server called Lychee.osisoft.com.
This trust record could be used, for example, to allow an interface to a data source to write to the PI Server from a PI API remote data collection node or a VMS-based PINet remote data collection node. This is similar to the old Proxy Database, used before PI Server 3.3. Assume the user will be IFUser2.
@table pitrust @mode create
@istru Trust, IPHost, PIUser
MyTrust2,lychee.osisoft.com,IFUser2 @endsection
Examples of PI SDK Client Applications on Windows
The Windows operating systems permit more secure logins, using domain and User name.
Example 6. Domains Match on Windows
The following trust record grants the rights of IFTypeC for any PI-SDK application run on the Windows Domain OSI. In other words, only Domain is specified. This trust would not authorize any PI API application or any PI-SDK application on Windows 98.
Trust Record Connection Credentials Field Name Field Value Match? Name Value
Trust NT/2000/XP
AppName AppName piperfmon.exe Domain OSI yes Domain OSI
IPAddr 0.0.0.0 IPAddr 192.168.168.121 Netmask 0.0.0.0
IPHost IPHost Gerke
OSUser OSUser Suzanne
PIUser IFTypeC
The set of credentials at the right is sent by a PI-SDK application on Windows. This example has Domain OSI and User Suzanne logged on to machine Gerke at IPaddress
192.168.168.121 running an application called piperfmon.exe.
Note: If you specify either a domain or OSUser in the trust record, the PI Server
must be in the same domain as the connecting application.
In this case, the credentials match the information in the trust record, because only Domain OSI was specified in the trust record. The application would be granted access to PI as the user IFTypeC. For greater restriction, you might also specify the application name and/or
OSUser name or IP Addr.
Example 7. Assigning Any OSUser on a Particular Domain to a PI User Database Entry of the Same Name Using $
For PI-SDK applications, PI Server allows you to assign any OSUser on a particular Domain to the PI User Database entry of the same name.
Note: If you specify a domain or OSUser in the trust record, the PI Server must be in
the same domain as the connecting application.
Using this feature requires a Trust Record with OSUser set to “$” and PIUser set to “$”. Other fields are optional. The operating system for the client application must be Windows. This trust would not authorize any PI API application or any PI-SDK application on Windows 98.
Trust Record Connection Credentials
Field Name Field Value Match? Name Value
6.9 - Trust Login Security
Trust Record Connection Credentials
AppName AppName piperfmon.exe
Domain OSI yes Domain OSI
IPAddr 0.0.0.0 IPAddr 192.168.168.121 Netmask 0.0.0.0
IPHost IPHost Suzanne2
OSUser $ OSUser OSI\Perfmon
PIUser $
In the example above, if the User Database contains a user named Perfmon, the trust will be granted.
Whenever there is a record in the User Database that matches the entry in OSUser, the trust is granted.
You could restrict the trust record further by specifying more fields, such as IPHost, subnet, or AppName.
Example 8. Assigning Any Machine on a Particular Domain to a PI User Database Entry
A dollar sign in the IPHost field of the trust record causes any machine on the same domain as the PI Server to be authorized with the same access as the OSI entry in the User Database.
Trust Record Connection Credentials
Field Name Field Value Match? Name Value Trust Matchmachine
AppName AppName piperfmon.exe
Domain Domain OSI
IPAddr 0.0.0.0 IPAddr 192.168.168.12 1
Netmask 0.0.0.0
IPHost $ yes IPHost Suzanne2
OSUser OSUser Perfmon
Examples for Client Applications Using either PI API or PI SDK
PI API credentials specify AppName truncated and PI-SDK credentials do not. If you want to build a trust record for both types of applications, do not specify AppName. Use IPHost or IPAddr.
Using IPAddr and Netmask
The IPAddr and Netmask combination allows more flexibility than an all-or-nothing match. The IP Address of the connecting machine is bitwise “ANDed” with the Netmask and then compared to the IPAddr field of the Trust Record.
It is a match if the “ANDed” result matches the IPAddr field of the Trust Record. This allows granting Trust Logins based connecting machine subnets, similar to IP Routing algorithms.
Remember that you can use additional fields in the trust record to further limit access. The following table gives some IPAddr/Netmask combinations and evaluation results:
Row Trust IPAddr Trust Netmask Machine
IPAddr Result of AND between Trust Netmask and Machine IPaddr Trust IPAddr and result of AND match? A 0.0.0.0 0.0.0.0 192.168.168.121 0.0.0.0 Yes B 192.168.168.0 255.255.255.0 192.168.168.121 192.168.168.0 Yes C 192.168.168.0 255.255.255.0 192.168.175.004 192.168.175.0 No D 192.168.168.176 255.255.255.240 192.168.168.178 192.168.168.176 Yes E 192.168.168.176 255.255.255.240 192.168.168.121 192.168.168.112 No F 192.168.168.22 255.255.255.255 192.168.168.22 192.168.168.22 Yes G 192.168.168.22 255.255.255.255 192.168.168.20 192.168.168.20 No
In Row A, the trust IPAddr and the Trust Netmask are blank. The “ANDed” result is also blank; these fields are ignored in the matching process.
In Row B, when you combine Trust Netmask with Machine IPAddr, you get a 0 in the last field; this matches the Trust IPAddr. Use this when you want to authorize any PC on a subnet. See Example 8. In Row C, the third field does not match (168, 175).
In Row D, the “ANDed” result of 240 and 178 is 176, and thus, matches the Trust IPAddr. In Row E, the “ANDed” result process does not match. This type of Netmask restricts matching to certain IP addresses on a network subnet.
Row F and G illustrate the situation described in Example 9. Using IPAddr and Netmask to
Specify a Particular Address.
Example 9. Using IPAddr and Netmask to Specify a Particular Address
You can specify a trust record with an explicit machine address, as shown below, and any connecting application at that machine will be granted a trust login. This example is shown
6.9 - Trust Login Security
above in Row F. Similarly, the results of the credential IPAddr and the Netmask in Row G is not an exact match for the trust IPAddr and the trust is not authorized.
Trust Record Connection Credentials
Field Name Field Value Match? Name Value
Trust Matchmachine
AppName AppName piperfmon.exe
Domain Domain OS*I
IPAddr 192.168.168.121 yes IPAddr 192.168.168.121 Netmask 255.255.255.255
IPHost IPHost Suzanne2
OSUser OSUser Suzanne*
PIUser OpsPC15
* only included for PI-SDK applications
Example 10. Specifying a Subnet
This example limits the login trust to a domain (OSI) and a specific Class C IP subnet:
Trust Record Connection Credentials
Field Name Field Value Match? Name Value Trust SubnetC1
AppName AppName piperfmon.exe
Domain Domain OSI*
IPAddr 192.168.168.0 yes IPAddr 192.168.168.121 Netmask 255.255.255.0
IPHost IPHost Suzanne2
OSUser OSUser Suzanne*
PIUser SubnetC1User
* only included for PI-SDK applications
This Trust Record grants the rights of SubnetC1User for any application run on any machine on the Windows Domain OSI as long as the machine is in the Class C subnet 192.168.168.0.
PI SDK Application on a Subnet
The following example allows PI-SDK application with a name MG.exe running in domain
plant1 and on any machine from the subnet 123.125.125.0 with a name MGr and logged with
a user named interface the access rights of PI user Mginter.
* (Cr - PITRUST) Piconfig> @istru trust,appname,domain,IPaddr,netmask, IPHost,osuser,piuser
* (Cr - PITRUST) Piconfig> MGinterface, MG.exe, plant1, 123.124.125.0, 255.255.255.0, MGr0,INTERFACE, MGinter