deviceTRUST Property Queries

deviceTRUST provides a default query to provide specific displays, networks, access points, printers and certificates into the properties available for the host or device. However, the default queries may not be suitable, or may simply contain too much information. Therefore, the queries can be independently customized for both the host and the device within the policy assigned to the host.

Queries consist of one or more query strings, each containing one or more constraints. All constraints within any of the query strings must be matched for an item to be included in the results. For example, take the following 2 printer query strings:

• Server=’\\PRINTSERVER??’, Name=’Finance Printer’
• Default=’true’

The first of the two queries in the example above includes 2 constraints. Server=’\\PRINTSERVER??’ ensures that printers returned from the first query have a server matching the wildcard expression, such as \\PRINTSERVER01. Name=’Finance Printer’ ensures that only printers matching the given name are returned. In the second query, Default=’true’ ensures that default printers are returned. Since printers will be returned if they match any of the statements, default printers will always be returned, even if they are not the ‘Finance Printer’. Similarly, finance printers will be returned even if they are not the default printer.

The constraints available to a query depend upon whether it is targeting displays, networks, access points, printers or certificates. The operations available to a constraint depend upon the underlying data type. For example, the name of a printer is textual, hence string comparisons can be performed using wildcard characters. Alternatively, the speed of a network is numeric, hence comparisons can be made against a number.

Access Point Queries

Access Point queries can be used to discover access points on the host or device. The following constraints are supported:

• Text constraints for SSID and BSSID.
• Number constraints for Strength, Quality and Frequency.
• Boolean constraint for Secure.

For example:

• SSID=’MyAccessPoint’, Strength>=’-50’ – Matches access points with the SSID ‘MyAccessPoint’ and a RSSI strength greater than -50.
• Secure=’true’ – Matches all secure access points.

By default, no access points are queried.

Certificate Queries

Certificate queries can be used to discover certificates on the host or device. The following constraints are available:

• Text constraints for Store, Name, Subject, Issuer, SignatureAlgorithm, SerialNumber, ThumbprintSha1, Template, ExtendedUsage, RootName and RootThumbprintSha1.
• Enum constraint for Location with values CurrentUser and LocalMachine.
• Enum constraint for Version with values V1, V2 and V3.
• Enum constraint for VerificationError with values None, CannotBeVerified, Revoked, UntrustedRoot, UntrustedTestRoot, Chaining, Expired, Critical and NoRevocationCheck.
• Enum constraint for Usage with values EncipherOnly, CrlSigning, CertificateSigning, KeyAgreement, DataEncipherment, KeyEncipherment, NonReduiation, DigitalSignature and DecipherOnly.
• Date constraints for NotBefore and NotAfter.

For example:

• Template=’CompanyCert’, ExtendedUsage=’1.3.6.1.5.5.7.3.2’ - All certificates assigned by a template containing the name ‘CompanyCert’ for use with client authentication.
• VerificationError=’*’ - All certificates, regardless of their verification errors.
• VerificationError=’None;Expired’, Issuer=’TrustedAuthority’ - All valid or expired certificates whose issuer contains the text ‘TrustedAuthority’.

The default value is “Store=’My’, Location=’CurrentUser’, VerificationError=’None’”. Store defaults to ‘My’ unless specified. Location defaults to ‘CurrentUser’ unless specified. VerificationError defaults to ‘None’ unless specified.

Display Queries

Display queries can be used to discover the displays on the host or device. The following constraints are supported:

• Text constraint for Name.
• Number constraints for Width, Height and Bpp.

For example:

• Width>=’1024’, Height>=’768’ queries all displays which have a width greater than or equal to 1024 pixels, and a height greater than or equal to 768.

By default, all displays are queried.

Firewall Queries

Unlike other queries, the firewall queries are used to exclude firewall rules from the host or device. The following constraints are available:

• Text constraints for Name, Description, Group, Program, Service, Package, PackageName, PackageDescription, PackageFullName and PortName.
• Enum constraint for Type with values Program, Package, Service, System and Any.
• Enum constraint for Direction with values Inbound and Outbound.
• Enum constraint for Protocol with values Any, HOPOPT, ICMPv4, IGMP, TCP, UDP, IPv6, IPv6Route, IPv6Frag, GRE, ICMPv6, IPv6NoNxt, IPv6Opts, VRRP, PGM, L2TP, or any protocol number from http://www.iana.org/assignments/protocol-numbers/protocol-numbers.xml.
• Enum constraint for Profile with values Domain, Private, Public.
• Number constraints for Port, with additional option to use * to match rules that target any port.

For example:

• Direction=’Inbound’, Program=’*\MyApp.exe’, Port>=3000, Port<=3002 - Excludes all inbound traffic to MyApp.exe to ports 3000, 3001 and 3002. The default value does not filter the Firewall rules.

Logical Disk Queries

Logical Disk queries can be used to filter the logical disks that are discovered on the local host or remote device. The following constraints are available:

• Enum constraint for Type with values Removable, Fixed, Cdrom and Ramdisk.
• Enum constraint for Flags with values NotReady, PreservedNames, CaseSensitiveSearch, DaxVolume, SupportsCompression, NamedStreams, PersistentAcls, ReadOnly, SequentialWriteOnce, SupportsEncryption, ExtendedAttributes, HardLinks, ObjectIds, OpenByFileId, ReparsePoints, SparseFiles, Transactions, UsnJournal, UnicodeFileNames, IsCompressed, SupportsQuotas.
• Text constraints for Label, FileSystem, Drive and Path.
• Number constraints for TotalMB and FreeMb.
• Boolean constraints for Encrypted.

For example:

• Drive=’D:,E:,F:,G:’ - Returns any drive mapped to letters D, E, F or G.
• Type=’Removable’ - Returns only removable disks.

The default value returns all logical disks represented by a drive letter (e.g. Flags!=’NotReady’, Drive!=’’).

Mapped Drive Queries

Mapped Drive queries can be used to filter the mapped drives that are discovered on the local host or remote device. The following constraints are available:

• Text constraints for Drive, Server, Share, User and Provider.

For example:

• Drive=’D:’ - Returns any drives mapped to a local D:.
• User=’DOMAIN\*’ - Returns any mapped drives authenticated by a member of the ‘DOMAIN’ domain.
• Server=’\\SERVERNAME’ - Returns any mapped drives using a remote server name of ‘\\SERVERNAME’.

The default value returns all mapped drives.

Network Queries

Network queries can be used to discover networks on the host or device. The following constraints are supported:

• Text constraints for Name, Description, Mac, GatewayMac, WifiSsid, WifiBssid, WifiSecurity and DnsSuffix.
• Enum constraint for Status with values Up, Down, Testing, Unknown, Dormant, NotPresent and LowerLayerDown.
• Enum constraint for Type with values Other, Ethernet, TokenRing, PPP, SoftwareLoopback, ATM, WiFi, Tunnel, Firewire and Mobile.
• Enum constraint for Category with values Public, Private and Domain.
• Boolean constraint for DhcpEnabled.
• Number constraints for Speed and WifiStrength.
• IpAddress constraints for IP, Gateway, DNS, WINS and DhcpServer.

For example:

• DhcpEnabled=’true’, DhcpServer=’192.168.100.1-2’, GatewayMac=’01-02-03-04-05-06-07’ - Matches networks assigned an ip address from a DHCP Server of address 192.168.100.1 or 192.168.100.2 configured with a gateway using MAC address 01-02-03-04-05-06-07.

The default value is “Status=’Up’, Type=’Ethernet;WiFi’”. Status defaults to ‘Up’ unless specified and type defaults to ‘Ethernet;WiFi’ unless specified.

Printer Queries

Printer queries can be used to discover printers on the host or device. The following constraints are available:

• Text constraints for Name, Server, Share, Port, Location, Driver, DriverFile and DriverManufacturer.
• Boolean constraint for Default, Local, DirectoryPublished and KeepPrintJobs.
• Enum constraint for Errors with values Paused, Error, PendingDeletion, PaperJam, PaperOut, PaperProblem, Offline, OutputBinFull, NotAvailable, TonerLow, NoToner, CannotPrintPage, UserIntervention, OutOfMemory, DoorOpen, ServerUnknown, ServerOffline and DriverUpdateNeeded.
• Version constraint for DriverVersion.

For example:

• Default=’true’ - Returns just the default printer.
• Share=’\\SERVER??\’, Errors=’’ - Returns printers which have a share matching the wildcard ‘\\SERVER??\*’ regardless of the error value.

The default value is “Errors!=’Offline;ServerOffline;NotAvailable’”. Errors defaults to all values except ‘Offline;ServerOffline;NotAvailable’ unless specified.

Security Product Queries

Defines queries which can be used to limit the security products. The following constraints are available:

• Text constraint for Name.
• Enum constraint for Category with values AntiVirus, AntiSpyware and Firewall.
• Enum constraint for Status with values Active, Out-Of-Date and Inactive.
• Date constraint for Timestamp.

For example:

• Status=’Active’, Category=’AntiVirus’ - Queries all AntiVirus security products with a status of Active. For full details, please see deviceTRUST Property Queries within the deviceTRUST Administration Guide.

The default query includes all security products.

Text Constraints

Text constraints are used to match textual properties of an item, such as a name or description. The text is case insensitive and must match in full. Operators of equals ‘=’ and not equals ‘!=’ are supported. The asterisk ‘*’ wildcard character matches zero or more unspecified characters, and the question mark ‘?’ character matches a single digit. Multiple text matches can be specified by separating them with a semi-colon ‘;’.

For example:

• Name=’ABC*’ – matches any name starting with ABC, such as ABC, ABCD, ABCDE, abc, etc.
• Name=’ABC’ – matches any name containing ABC, such as ABC, ABCD, 1234ABCD, etc.
• Name=’A?C’ – matches any name with 3 digits, starting with A and ending in C, such as AAC, ABC, ADC, etc.
• Name!=’ABC’ – matches any name which does not contain ABC, such as AB, ABD, etc.
• Name=’ABC;XYZ’ – matches any name which contains the text ABC or DEF, such as 1234ABCD or XYZ987, etc.

Enumeration (Enum) Constraints

Enum constraints are used to match properties which have a predefined set of potential values, such as a network type which can be Ethernet, WiFi, Mobile, etc. The values which can be contained within the property are specific to each property. Operators of equals ‘=’ and not equals ‘!=’ are supported. The asterisk ‘*’ wildcard can be used to match any value, which becomes useful to override the default behavior of a constraint. Multiple enum matches can be specified by separating them with a semi-colon ‘;’.

For example:

• Type=’WiFi’ – matches a type of WiFi.
• Type=’WiFi;Ethernet’ – matches a type of WiFi or Ethernet.
• Type!=’WiFi’ – matches any type which is not WiFi.
• Type!=’WiFi;Ethernet’ – matches a type which is neither WiFi or Ethernet.
• Type=’*’ – matches any type.

Number Constraints

Number constraints are used to match properties which are numeric, such as the speed of a network. The following operators are supported:

• Equals ‘=’ – matches the number exactly.
• Not Equals ‘!=’ – matches all numbers except the one specified.
• Greater Than ‘>’ – matches all number greater but not equal to that specified.
• Greater Than or Equals ‘>=’ – matches all numbers greater than or equal to the one specified.
• Less Than ‘<’ – matches all numbers less but not equal to the one specified.
• Less Than or Equals ‘<=’ – matches all numbers less than or equals to that specified.

Constraints can be specified multiple times to form range constraints.

For example:

• Speed=’1000’ – matches the speed when it is equal to 1000.
• Speed>=’1000’ – matches the speed when it is greater than or equal to 1000.
• Speed>=’1000’, Speed<’2000’ – matches the speed between the range 1000 and 1999.

Date Constraints

Date constraints are used to match properties which represent a date, such as the NotBefore and NotAfter properties of a certificate. Date constraints support the same operators as the number constraints. Dates can either be specified as a specific RFC2822 or ISO 8601 date string, such as ‘2016-03-21’, as a positive or negative number representing the number of days relative to the current date. Constraints can be specified multiple times to form range constraints.

For example:

• Expiry=’2016-03-21’ – matches the expiry of 21st March 2016.
• Expiry>=’2016-03-21’ – matches any expiry greater than or equals to 21st March 2016.
• Expiry>=’2016-03-21’, Expiry<’2017-03-21’ – matches any expiry between the dates of 21st March 2016 and 20th March 2017.
• Expiry=’1’ – matches the expiry of tomorrow.
• Expiry>’0’, Expiry<=’7’ – matches any expiry in the next week.
• Expiry<’0’, Expiry>=’-7’ – matches any expiry in the past week.

Boolean Constraints

Boolean constraints are used to match properties which can only be ‘true’ or ‘false’. Operators of equals ‘=’ and not equals ‘!=’ are supported, and values of ‘true’, ‘false’ and asterisk ‘*’ to match any value.

For example:

• Default=’true’ – matches the default of true.
• Default=’false’ – matches the default of false.
• Default=’*’ – matches either true or false.

IpAddress Constraints

IpAddress constraints are used to match properties which represent one or more IP addresses, such as a network’s IP or Gateway. Operators of equals ‘=’ and not equals ‘!=’ are supported. Values can be either IPv4 or IPv6 addresses, and are only compared for the level of detail supplied in the constraint. For example, ‘192.168’ will match any address starting with 192.168. An asterisk ‘*’ can be supplied to match any digit within the address, and a dash ‘-‘ can be used to define a valid range of numbers.

For example:

• IP=’192.168.100.1’ – matches the exact address 192.168.100.1.
• IP=’192.168’ – matches any address starting with 192.168, such as 192.168.100.1.
• IP=’192.168.*.1’ – matches any address starting with 192.168 and ending in 1.
• IP=’192.168.100.1-2’ – matches the addresses 192.168.100.1 and 192.168.100.2.
• IP!=’192.168.100.1-2’ – matches all addresses except 192.168.100.1 and 192.168.100.2.

Version Constraints

Version constraints are used to match properties which represent a dot ‘.’ delimited version number, such as the printer driver’s version number. Operators of equals ‘=’ and not equals ‘!=’ are supported. Values are compared for the level of detail supplied in the constraint. For example, ’18.1’ will match any version starting with 18.1. An asterisk ‘*’ can be supplied to match any digit within the version number, and a dash ‘-‘ can be used to define a valid range of numbers.

For example:

• Version=’18.1.100.0’ – matches the exact version 18.1.100.0.
• Version=’18.1’ – matches any version starting with 18.1.
• Version=’18.1.*.0’ – matches any version starting with 18.1 and ending in 0.
• Version=’18.1.100-200.0’ – matches any version starting with 18.1, having a third digit between 100 and 200, and a fourth digit of zero.
• Version!=’18.1’ – matches any version which doesn’t start with 18.1.