Certificate-based Authentication and Authorization with the VerdeTTo IoT Access Valve. Version 1.0. User Guide

Transcription

1 Certificate-based Authentication and Authorization with the VerdeTTo IoT Access Valve Version 1.0 User Guide

2 Copyright 2017 Certified Security Solutions, Inc. All Rights Reserved. User guides and related documentation from Certified Security Solutions ( CSS ) are subject to the copyright laws of the United States and other countries and are provided under a license agreement that restricts copying, disclosure, and use of such documentation. This documentation may not be disclosed, transferred, modified, or reduced to any form, including electronic media, or transmitted or made publicly available by any means without the prior written consent of CSS and no authorization is granted to make copies for such purposes. Information described herein is furnished for general information only, is subject to change without notice, and should not be construed as a warranty or commitment by CSS. CSS assumes no responsibility or liability for any errors or inaccuracies that may appear in this document. The software described in this document is provided under written license agreement, contains valuable trade secrets and proprietary information, and is protected by the copyright laws of the United States and other countries. It may not be copied or distributed in any form or medium, disclosed to third parties, or used in any manner not provided for in the software licenses agreement except with written prior approval from CSS.

3 Software Change Log...2 Introduction and Installation...2 About the VerdeTTo IoT Access Valve...2 Installing the VerdeTTo IoT Access Valve Extension...3 Configuration and Usage...4 VerdeTTo IoT Access Valve Configuration...4 CMS VerdeTTo IoT Identity Platform Configuration...6 Extending the Valves...7 References...8 Document Revision History...8 1

4 Software Change Log Version Release Date Changes 1.0 1/17/2017 Initial Release Introduction and Installation Extension Type: Security This document provides installation and usage instructions for the VerdeTTo IoT Access Valve Extension. About the VerdeTTo IoT Access Valve The VerdeTTo IoT Access Valve, together with the CMS VerdeTTo IoT Identity Platform, enable the performance of additional validation of inbound requests to the ThingWorx platform, based on unique client certificates and their extended attributes. It offers features such as: Dynamic client certificate authentication requirements Turn requirements on and off without restarting your server or disconnecting any clients. Adaptive authorization Adaptively allow or deny device connections individually or as a collection. Time and location restrictions Restrict device access to certain IP addresses and/or time of day. Monitoring Log unsuccessful connection attempts or attempts with certificates that have been revoked. The CMS VerdeTTo IoT Identity Platform is a pre-requisite, and must be actively deployed in order to make use of this extension. The CMS VerdeTTo IoT Identity Platform is a separately licensable platform from Certified Security Solutions CMS VerdeTTo is also able, through a set of agent components, to monitor and manage the contents of a Root of Trust (RoT) including certificate keystores and truststores on both the platform server and the client devices. This ensures that certificates with a compromised key or certificate authority can be quickly blocked from accessing the platform, and that replacement certificates can be automatically issued and delivered to a device keystore. Agent support is an optional feature that can be added separately to your CMS VerdeTTo system from Certified Security Solutions. 2

5 Installing the VerdeTTo IoT Access Valve Extension 1. Configure Tomcat's server.xml to require client certificate authentication to the ThingWorx platform. (See [1] for instructions). This section of the xml will then look as follows: <Connector port="8443" protocol="org.apache.coyote.http11.http11nioprotocol" maxthreads="150" SSLEnabled="true" scheme="https" secure="true" sslprotocol="tls" enablelookups="false" keystorefile="conf/tomcat.keystore" keystorepass="mypassword" clientauth="true" truststorefile="conf/truststore.jks" truststorepass="myotherpassword"> </Connector> Truststore.jks and tomcat.keystore must be configured as Java Keystores and provisioned with the appropriate certificates. 2. Provision your devices with a certificate trusted by the server and configure them to use this certificate when connecting. The process for this will vary by platform. For example, in Java this is done by setting the javax.net.ssl system properties. 3. Place the VerdettoValve.jar, httpclient-4.5.jar, httpcore jar, commons-codec- 1.9.jar, commons-logging-1.2.jar, and joda-time jar in the Tomcat /lib directory. 4. Add the following line to your Tomcat server.xml, with the appropriate parameters. This will typically go within a Host section, within the Catalina Engine section, but will depend on your Tomcat server configuration. See the "Operation" section below: <Valve classname="com.css_security.verdetto.valve.verdettovalve" server="corp.example.com" b64credentials="aaaa==" logfile="c:/thingworxstorage/logs/communicationlog.log" fields="ipaddress, StartTime, EndTime, Authorization" /> 5. Add additional valves as needed, following the guidelines in the "Operation" section below. 6. Configure your VerdeTTo server to grant access by importing the device certificates (if not already present) and defining your metadata fields, as described in the "Operation" section below 7. Restart Tomcat and attempt to navigate to the composer in your browser <server>:8443/thingworx/composer/index.html You should be prompted for a certificate (you will need to install one on your machine if not), and access should only be allowed with the VerdeTTo metadata for your certificate configured to match the values expected by the Valve. 3

6 Configuration and Usage The VerdeTTo Access Valve is installed on the Tomcat server hosting the ThingWorx platform. When a user or device attempts to connect to the platform with a client certificate, this valve intercepts the request and may allow or deny it based on several parameters. The basic flow of this system is shown below. VerdeTTo IoT Access Valve Configuration The decision to allow or deny a request is governed by two pieces: a series of valves defined in the Tomcat request handling pipeline, and a set of attributes associated with a client identity in VerdeTTo. The respective parts of these two configuration sources are described below. The inbound HTTP requests to the platform are intercepted by a series of valves, as configured in the server.xml for your Tomcat server. The first valve should always be the "com.css_security.verdetto.valve.verdettovalve" valve, which validates the certificate used by the client and retrieves a set of attributes from the VerdeTTo platform. This may be followed by one or more additional valves which make authorization decisions based on the attributes retrieved. A number of valves are included by default, and extensions to these can be implemented as needed (see the section "Extending the VerdeTTo Valves" below). The default valves each take parameters, defined in the server.xml. Valves will be executed in the order they are listed in the server.xml, and each valve can be included multiple times with different parameters. A list of these valves, along with their behavior and parameters, is shown below: 4

7 VerdeTToValve EqualityValve IPAddressValve RangeValve Validates the client certificate and retrieves associated attributes. server Hostname or IP address of the VerdeTTo Platform server. b64credentials Credentials for the VerdeTTo Platform server, in the format "DOMAIN\user:Password" and base- 64 encoded. fields Comma-separated list of the names of the attributes that should be retrieved from VerdeTTo. logfile Path to the file where access logs should be written. verbose Optional parameter. If present, logs additional info. Compares an attribute of the request to an expected value and denies the connection attempt if the actual value does not match the expected. In the simplest form, the "field" and "expected" parameters are set, and the value for the VerdeTTo attribute specified by "field" is compared to the value specified by "expected". The "field" name must match one of the entries in the "fields" list specified in the VerdeTToValve parameters. More nuanced logic can be achieved by implementing an "actualgetter" and/or an "expectedgetter" as described in "Extending the VerdeTTo Valves" below. field Name of the attribute retrieved by VerdeTTo to be compared. expected Static value expected for the attribute. actualgetterpath Path to the directory containing the ValueGetter class used to extract the request's "actual" value for comparison. See "Extending the VerdeTTo Valves". actualgetterclass Name of the ValueGetter class used to extract the "actual" value for the request. expectedgetterpath Path to the directory containing the ValueGetter class used to define the "expected" value for comparison. expectedgetterclass Name of the ValueGetter class used to extract the "expected" value for comparison. An extension of the EqualityValve that compares the IP address of the request's source to a value set in the "IPAddress" VerdeTTo attribute. This is used when a certificate should only be used to access the platform from a particular, known IP address. No parameters are required. Determines if an attribute of the incoming request is greater than a given lower bound, and/or less than an upper bound. In its simplest form, static numerical values are defined for the lower and upper bounds, and the actual value to range-check is retrieved from a VerdeTTo attribute with the given field name. More complex comparisons can be performed by implementing ValueGetters for the lower, upper, and/or actual values. For non-numeric value types, a ValueComparer must also be implemented. Instructions on this can be found in "Extending the VerdeTTo Valves" below. field Name of the attribute retrieved by VerdeTTo to be compared. 5

8 TimeRangeValve lower Static value for the lower bound of the allowed range. upper Static value for the upper bound of the allowed range. actualgetterpath Path to the directory containing the ValueGetter class used to extract the request's "actual" value for comparison. See "Extending the VerdeTTo Valves". actualgetterclass Name of the ValueGetter class used to extract the "actual" value for the request. expectedgetterpath Path to the directory containing the ValueGetter class used to define the "lower" AND "upper" bounds for the range. expectedgetterclass Name of the ValueGetter class used to define the "lower" AND "upper" bounds for the range. An extension of the RangeValve that compares the current time to the "StartTime" and/or "EndTime" attributes from VerdeTTo. This is used when a certificate should only be used to access the platform during certain hours of the day. No parameters are required. An example pipeline configuration is as follows: <Valve classname="com.css_security.verdetto.valve.verdettovalve" server="corp.example.com" b64credentials="aaaa" logfile="c:/thingworxstorage/logs/communicationlog.log" verbose="true" fields="ipaddress, StartTime, EndTime, Authorization" /> <Valve classname="com.css_security.verdetto.valve.ipaddressvalve"/> <Valve classname="com.css_security.verdetto.valve.timerangevalve"/> <Valve classname="com.css_security.verdetto.valve.equalityvalve" field="authorization" expected="true" /> <Valve classname="com.css_security.verdetto.valve.equalityvalve" field="rotatingkey" expectedgetterpath="c:/program Files/ThingWorx/extensions/" expectedgetterclass="com.example.corp.things.myrotatingkeygetter" /> <Valve classname="com.example.corp.things.myequalityvalve" /> CMS VerdeTTo IoT Identity Platform Configuration The CMS VerdeTTo Management Portal is a browser-based web portal installed as part of your CMS VerdeTTo deployment. This allows you to view and manage the devices in your fleet and the operating parameters associated with them. You will need to perform the following configuration to use VerdeTTo to control access to your ThingWorx server: 1. Open your "Device Authorization" tab. 2. Define any default values for the IPAddress, StartTime, EndTime, and Authorization parameters that you wish. 6

9 3. Import your device certificates into VerdeTTo. This can be done in several ways through the "Identity Provisioning" tab. 4. Open your "Device Identities" tab. 5. Edit attributes for any certificates that should not use the default values.: a. Double-click the certificate you wish to edit b. Click the edit icon by the field you wish to edit c. Enter the desired value d. Click "Save" 6. Define Certificate Collections as needed by your use case for easy access and control. Extending the Valves When the built-in valves are not sufficient to implement the desired access control, custom valves can be inserted into the pipeline to augment the authorization logic. The two primary methods for doing this are to implement ValueGetters for one or more of the values to be compared, or to extend one of the builtin classes and override the default constructor to define ValueGetters and/or ValueComparers for the comparison. Both methods are described below. The ValueGetter interface The VerdeTToValve.jar package defines the VerdeTToValve, EqualityValve, and other valve classes. In order to support dynamic evaluation of a value for comparison, these valves make use of "ValueGetters". The ValueGetter interface is defined thus: package com.css_security.verdetto.valve; import org.apache.catalina.connector.request; import org.apache.catalina.connector.response; public interface ValueGetter { public String getvalue(request req, Response resp, String param); } 7

10 When a Valve needs to retrieve a value for comparison and a ValueGetter is specified, the Valve calls the "getvalue" method, passing in the request and response as the Valve currently sees them. The third parameter specifies the type of value to be retrieved. This will be one of "actual", "expected", "lower", or "upper", and allows one getter to handle multiple types of retrieval. By referencing this jar library and implementing this interface, you can create a ValueGetter class that can be accessed through the valve parameters by filepath and class name. Within your getvalue method, you can access attribute values retrieved from VerdeTTo through the request attributes. The value of a field specified in the VerdeTToValve "fields" parameter will be stored in a request header with the field name capitalized and prefixed by "X-CSS- VERDETTO-". So a field named "foo" will be stored in the "X-CSS-VERDETTO-FOO" header, and can be accessed through req.getattribute("x-css-verdetto-foo"). The value will always be a string and can be safely cast to a String object. Extending a Valve The VerdeTToValve.jar package also contains the definitions for the EqualityValve and RangeValve. By extending one of these classes and overriding the default constructor, you can set custom ValueGetters without writing an explicit class. This can be done by initializing the protected expectedgetter and/or actualgetter fields in the constructor (following the example below). For example, the IPAddressValve constructor includes the following definition: this.expectedgetter = new public String getvalue(request req, Response resp, String param) { return (String)req.getAttribute("X-CSS-VERDETTO-IPADDRESS"); } }; In this manner, a custom valve can be created more easily, and can be included in the request handling pipeline with less configuration. References [1] Enabling SSL Communication and Client Certificate Authentication between Apache Web Server and Apache Tomcat: communication-and-client-certificate-authentication-between-apache-web- Document Revision History Revision Date Version Description of Change 8