Mobile RA - User Guide

Transcription

1 DRAFT Mobile RA - User Guide Version 0.32 Mobile RA User Guide V0.32, PrimeKey Solutions AB, Page 1 of 9

2 Table of Contents 1 Introduction Mobile RA System Overview Mobile RA Operation Sample Run Server Configurations Web s Interface Request URL Sample Request Response Data Authentication HTTP POST Option Device Certificate Placeholders User Name Template Installation Prerequisites Quick Install Testing Configuration Properties QR Code Support Client Protocol Support <keygen> SCEP KeyGen LCEP...9 Mobile RA User Guide V0.32, PrimeKey Solutions AB, Page 2 of 9

3 1 Introduction This document describes a extension to that facilitates efficient certificate enrollment for mobile devices and PCs including BYOD (Bring Your Own Device) scenarios. 2 Mobile RA System Overview A Mobile RA installation consists of the following components: tifications SMS Provider (External) QR-Code High-Security Zone WS Interface (Optional) CA Admin-enroll Self-enroll Push-mail-like HTTPS Connections (data is delivered on returns) In addition to the mechanics needed for enrollment, the Mobile RA system also provides a security proxy scheme that enables different security zones for the CA, RA and enrollment server. Also see Server Configurations. The Mobile RA supports two basic scenarios: Administrator-driven enrollment where an administrator initiates an enrollment session and optionally let the end-user deal with the last part (typically using a OOB-supplied password). Self-service mode where a user authenticates to the RA according to the issuer's policy and also performs the other steps needed for completing the enrollment process Since it is quite difficult creating a fully universal application for administrating users, there is also a WS (Web ) interface designed for easy integration in existing customer portals and similar. Using Web s, user data would normally be derived from existing user databases such as AD (Active Directory). In all configurations the Mobile RA acts as a trusted service to (which only performs PKI operations like certificate issuance and revocation). That is, the Mobile RA provides with pre-authenticated external certificate data including subject DNs Mobile RA User Guide V0.32, PrimeKey Solutions AB, Page 3 of 9

4 3 Mobile RA Operation The Mobile RA in its current incarnation essentially only provides a single function: Enabling a user or administrator creating an enrollment session which is subsequently used by the system to enroll a certificate on a mobile device or PC. However, since the enrollment scheme also requires users to intervene, it is good to understand the entire process. In the Mobile RA System Overview the steps are marked with numbers as follows: 1. Initiation of enrollment session after creation of subject certificate data 2. An URL is sent to an external message distribution server 3. The URL is received by the enrolling device 4. After user accept of the URL, a request is sent to the using the device's Internet browser. Depending on configuration and notification method, the user may also need to authenticate with a PIN. The above probably looks rather simple but since there are no established standards for the device-to-issuer enrollment process, quite different protocols are actually used behind the curtain. This also means that the user-interaction between for example Android and ios devices also differs markedly. 3.1 Sample Run Below is the sequence of GUI operations involved in step #4 using an ios version 6 device: tification Message User Authentication ios Certificate Explanation: The first screen shows the notification message sent by the Mobile RA. By clicking on the URL, the ios browser is started. The Mobile RA has in this case been configured to require an enrollment PIN-code as well shown in the second screen. After successful user authentication the Mobile RA returns an ios profile which contains a SCEP enrollment request. If the user accepts this request by clicking on Install the rest of the process is performed. Mobile RA User Guide V0.32, PrimeKey Solutions AB, Page 4 of 9

5 4 Server Configurations If you take a look at the system overview, you will note that there are three distinct servers involved (disrespecting external mail-, SMS-, LDAP-, or database-servers). However, the Mobile RA system can be configured to only run on a single server together with which may be satisfactory for testing and low-volume production (not due to capacity issues but due to security considerations). The following picture outlines the different server-deployment alternatives: Single Server Enroll/RA Combo CA CA Separate Fully Distributed System CA CA The configuration is created during building the Mobile RA application which shipped in source like. Mobile RA User Guide V0.32, PrimeKey Solutions AB, Page 5 of 9

6 5 Web s Interface The Web s interface currently offers a single function: Initiating an enrollment session. To keep complexity low a REST-like HTTP GET operation based on URL-encoded name-value pairs is used. The parameters are as follows: Name Description Required tifmeth tification Method. The argument must be sms or mail. DestAddr Destination Address. The argument must either contain a mail-address like john@example.com or an international mobile phone number like as defined by the tification Method. If the calling service would rather like to deal with the notification messages itself, tifmeth and DestAddr must be undefined. CAName CA name Yes EEProf end entity profile name Yes CertProf certificate profile name Yes SubjectDN SAN Subject DN according to RFC Also see Device Certificate Placeholders Subject Alt Name extensions separated by,. Example: rfc822name=john@example.com Also see Device Certificate Placeholders PIN User authentication PIN. t applicable to LCEP User DeviceID AuthData user name. Also see Device Certificate Placeholders. te that if User is not supplied a User Name Template is used instead Device ID for KeyGen2. te that the existence of DeviceID will force the Mobile RA system to use the KeyGen2 protocol Authentication Data for LCEP. te that the existence of AuthData will force the Mobile RA system to use the LCEP protocol TimeOut session time-out in seconds GraceTime Optional session life-time in seconds after a successful or actively aborted enrollment process WSMode Argument must be true Yes Yes 5.1 Request URL The WS invocation URL is http[s]://mobile_ra_host:port/mobilera/certreq?web_service_arguments where http versus https, mobile_ra_host, and port depends on the configuration. In the default, single-server mode, you should be able to execute WS-commands on Sample Request The following is a complete WS request argument string with SMS notification for a user with phone number The issued certificate will (at least) contain the subject DN attribute CN=tester. The user is also supposed to authenticate with a PIN tifmeth=sms&destaddr=%2b &caname=mobile1&eeprof=mobile&certprof=mobile &SubjectDN=CN%3Dtester&PIN=1234&WSMode=true Argument order in a request is of no importance. Mobile RA User Guide V0.32, PrimeKey Solutions AB, Page 6 of 9

7 5.3 Response Data If the request is successful (HTTP 200) the response body constitutes of a simple text/plain string containing the URL that the client should use to activate the enrollment process like: http[s]://enroll_host:port/m/enroll?id=1078&a=wk7c0wdub10vtsyxgnn6kuqns8s Internal and input errors always return HTTP 50x. 5.4 Authentication Web s can operate in two authentication modes, none or TLS-client-certificate-authentication. authentication may be used in systems where the HTTP port is bound to localhost only and the calling service is running on the same server as the. For remote Web s calls TLS-client-certificate-authentication is recommended. External security solutions like SSH tunnels are of course also possible. te: The UserID/Password authentication mode if used for Web s requires fairly specific code which is supplied in the add-on application: Mobile_RA_INSTALL/optional-applications/secure-credential-cloning. 5.5 HTTP POST Option te that you may also access Web s using HTTP POST, by putting the argument data (minus the initial?) in the request body and setting the header Content-Type to application/x-www-form-urlencoded while Content-Length must match the length of the request string. 5.6 Device Certificate Placeholders For client protocols that support device certificates (currently including KeyGen2 and LCEP), the SubjectDN, SAN and User arguments may contain the placeholder $DCSHA1$ which during certification will be replaced by the SHA1 hash of device certificate in hexadecimal notation. Example: SubjectDN (before URL-encoding): CN=John Doe,O=$DCSHA1$,C=US Actual SubjectDN sent to : CN=John Doe,O=FE26045C97507B0F153A2BCCD4FA83CBEF1703ED,C=US te: There are no syntax restrictions on placeholders, they are just text substitutions. In addition to $DCSHA1$ there is also a device certificate placeholder $DCDEVID$ associated with LCEP. 5.7 User Name Template If no User argument is given, the Mobile RA uses a template that automatically creates user-names based on SubjectDN and SAN components. It also honors the Device Certificate Placeholders. The table below shows the supported substitutions: Placeholder $DN$ $CN$ $O$ $OU$ $C$ $SERIALNUMBER$ $ ADDRESS$ Takes the entire SubjectDN string as is Description These placeholders are matched against the corresponding SubjectDN X.509 attribute fields If there is a SAN argument holding an RFC822Name attribute it will be used for the substitution, otherwise SubjectDN will be searched for an Address attribute te that searches are case-insensitive and replacements will use the string N/A if there is no match. The default template is Mobile RA: $DN$. The template can be configured. TBD. Mobile RA User Guide V0.32, PrimeKey Solutions AB, Page 7 of 9

8 6 Installation Before you install the Mobile RA you need to decide which configuration to use. See Server Configurations. 6.1 Prerequisites If you plan to do a more advanced installation with multiple servers you need to have the following support packages available for the non- servers. JDK 6 ANT or later JBoss GA The Mobile RA runs on the same operating systems as but only requires 500M of RAM and 1G of disk for JBoss. If the Enroll service runs stand-alone, you must install an Apache Tomcat 6.x or 7.X server rather than JBoss on that server. 6.2 Quick Install To install the Mobile RA perform the following steps: 1. Unpack the Mobile RA distribution ZIP in a free directory on the server to which the deploy user has full access 2. Copy the file Mobile_RA_INSTALL/ejbca/mobilera.properties to the directory _INSTALL/conf/plugins 3. Edit the file _INSTALL/conf/plugins/mobilera.properties: Set the property plugin.ejbca.ant.file so that it points to Mobile_RA_INSTALL/build.xml 4. Perform ant clean deploy while standing in the _INSTALL directory 5. Start JBoss This represents a minimalist installation (see Single Server) which is useful for verifying that everything is in place. JBoss should initialize without any errors in the log. The CA component (see Mobile RA System Overview) must always be installed on the -server using the process above. 6.3 Testing If you after performing a quick install invoke the server with a browser using the URL you should get a dialog like the following: If you have a default installation you may try a round with the Mobile RA by inserting suitable information in the dialog above and click on Submit Request. The Mobile RA will note that you haven't configured any SMS or Mail provider but the request should nevertheless be accepted. The returned URL can be pasted into Firefox, Safari (on OSX only), or Chrome, and should eventually return a certificate in the browser keystore. Mobile RA User Guide V0.32, PrimeKey Solutions AB, Page 8 of 9

9 7 Configuration Properties The Mobile RA supports a huge number of properties. The properties are defined in a file as described in Installation and packaged with the application during build. All properties are documented in the template file available in Mobile_RA_INSTALL/ejbca/mobilera.properties. 8 QR Code Support You can enroll devices having a rear camera using QR-code if you have a suitable QR app installed. QR-code operation is enabled by enrolling using the Web GUI at the URL: http[s]://mobile_ra_host :port/mobilera/qrcertreq Using QR-codes there is no need for PIN-codes since the authenticated web-page and the enrolling device are paired by the QR-code. 9 Client Protocol Support Since there are no generally accepted standards for certificate enrollment in mobile devices, the Mobile RA implements a selection of the most popular schemes. 9.1 <keygen> <keygen> is an HTML-based browser-extension featured in Firefox, Safari for OS/X, and in Android devices SCEP The Mobile RA implements the SCEP scheme used in ios devices, including signed profile data KeyGen2 KeyGen2 is an experimental enrollment protocol LCEP LCEP is a custom enrollment protocol described in a separate document. Mobile RA User Guide V0.32, PrimeKey Solutions AB, Page 9 of 9