Skip to content
This repository has been archived by the owner on Dec 10, 2018. It is now read-only.

Using QZ Tray

Jump to bottom
klabarge edited this page Jun 19, 2015 · 32 revisions

#Using QZ Tray

###Background

QZ Tray is a desktop version of the QZ Print application. In anticipation of changes in Google Chrome (dropping support of NPAPI), the QZ Print plugin now offers desktop support via the QZ Tray desktop application beta.

###Installing QZ Tray (Windows)

  1. Install Java 7 or higher from Oracle's website.

  2. Download the appropriate version for your operating system from the qz website.

  3. Install, taking the defaults.

image

Note to Firefox users:

  • Currently, in order for HTTPS to work with Firefox, QZ Tray must be installed (or reinstalled) AFTER Firefox.
  • The certificate installation is performed when Firefox is opened, so closing all running versions of Firefox is required for HTTPS support.
  • Mac users will need to fully quit Firefox via Command (⌘) + Q.
  • These steps are required for Windows, Linux and Mac versions of QZ Tray.

###Running QZ Tray (Windows)

  1. If QZ Tray is installed correctly, an icon will appear in the Windows System Tray.

image

Note: The install dialogue box will not close on its own.

image

  1. A desktop icon is not created by default. To create one, right click the QZ Tray icon down in the tray. Then, go to Advanced > Create Desktop shortcut

###Testing QZ Tray

  1. Open install folder via Tray Icon > Advanced > Open File Location

image

  1. Open sample.html from the demo folder.

image

image

  1. When prompted to allow access, click Allow

Note: This dialog is often hidden behind the browser window. Click the Tray Icon to bring it to the forefront. Hitting refresh will prevent proper loading per bug #11

image

  1. Click Allow to allow the web page to interact with QZ Tray. The page should turn from yellow to gray.

image

  1. Click Detect Printer

  2. Test a print button:

Note: For security reasons, all print requests must be digitally signed. If they are not, a warning will appear on each print. For silent printing, a new signing method must be used. This is further explained in "Signing Messages" section below.

image

###Troubleshooting QZ Tray

  1. Error:

"Could not find the main class: qz.ws.PrintWebSocketServer. Program will exit."

--OR--

"Exception in thread "main" java.lang.UnsupportedClassVersionError: org/eclipse/jetty/server/Handler : Unsupported major.minor version 51.0"

image

Cause: Java 7 or higher is missing from the system. Java 7 or higher is required to run QZ Tray

Resolution: Install Java 7 or higher from the Oracle website.

  1. Error:

The page was loaded over HTTPS, but ran insecure content from 'ws://localhost:8181': this content should also be loaded over HTTPS (wss://).

--OR--

Failed to construct 'WebSocket': An insecure WebSocket connection may not be initiated from a page loaded over HTTPS.

Cause: Some browsers block or warn about the non-secure access of resources when loading a page over HTTPS.

Resolution: HTTPS is supported on versions 1.8.92 and higher so as long as it is install via the full Desktop installer, which configures the system for proper wss:// (compatible with HTTPS).

###Certificates If you have purchased a premium version of QZ Print, you can follow the steps below for trusted-signing. Trusted-signing will suppress the print warnings.

image

  1. Navigate to https://qz.io/login/
  2. Enter in the product key and click Sign In

Note: Make sure there are no blank spaces before or after the product key.

  1. Once signed in, you are given two options. Select QZ Tray.

image

  1. At the next screen you have the ability to generate a CSR (Certificate Signing Request) and a public/private key pair.

You may already have a CSR and/or a public/private key pair. If that is the case, you can upload both of these at this screen.

  1. Fill in the required fields and hit Submit request

    image

  2. After a few seconds a new field will appear at the bottom of the page. Download the public key, private key, and certificate.

    image

  • Private Key: Needed for signing messages. This allows silent printing.
  • Public Key: Not needed for printing, but is used to request new certificates.
  • Certificate: Used on page load for silent printing.

###Technical Signing Details The following steps assume that you have obtained an Intermediate Signing Certificate from QZ Industries, LLC. The Certificate Signing Request is based off of a private key that you or your organization will be using to sign the messages.

  • This request MAY be created from a known-trusted certificate. -- OR --
  • This request MAY be a cert created and used solely for the purposes of printing. -- BUT --
  • It MUST have the minimum identifiable information that X509 PKI requires. This usually includes Country, State/Province, City, Business Name, Requestor, FQDN
  • It MUST be used for all signed messages to the software.
  1. Supply the software with the public certificate (intermediate certificate).

  • A new getCertificate(...) function has been added to QZ Tray to allow the quick whitelisting of REQUEST communication from a trusted host to the QZ Tray application.

  • A sample certificate chain is provided with the demo, labeled as "localhost". This will display a trusted message on load of the page.

Note: This certificate will **NOT REMOVE WARNINGS FOR SEND ** communication. SEND communication is only allowed when messages are signed using the same private key used to generate the CSR.

  1. Replace the "localhost" certificate chain with the public certificate provided by QZ Industries, LLC.
   callback("-----BEGIN CERTIFICATE-----" + \n

   "MIIFEjCCA/qgAwIBAgICEAAwDQYJKoZIhvcN" + \n ...
  • This certificate can be provided directly via JavaScript, or alternately, a separate AJAX call.
   function getCertificate(callback) {
    $.ajax({
        method: 'GET',
        url: 'assets/auth/public-key.txt',
        success: callback // Data returned from ajax call should be the site certificate
    });
  • Change the url to match where the public key is located. If this key was generated by qz, it will be called qztray_rsa.pub
  1. Sign the privileged SEND communication so that the software knows they derived from a trusted source.
  • This is done to safeguard against unknown sites accessing your native resources.

  1. First, request and obtain a public certificate chain from QZ Industries, LLC using a standard Certificate Signing Request (CSR).

  2. Use the new signRequest(...) function that has been added to the software to prevent anonymous printing.

Note: This is a security measure to ensure the identity of websites can be verified by the software.

function signRequest(toSign, callback) {

 $.ajax({
     method: 'GET',
     url: '/secure/url/for/sign-message.php?request=' + toSign,
     async: false,
     success: callback // Data returned from ajax call should be the signature
 });
 

 //Send unsigned messages to socket - users will then have to Allow/Deny each print request
 callback();
}
  • A server-side signing method must be used in combination with the AJAX call. This signing will happen with your company's private key.

Note: DO NOT send private keys to QZ Industries, only CSRs.

  • A signing example is provide with the software, please see sign-message.php (.cs, .py, etc)

  • Trusted websites with a valid public key chain pair and properly configured 'signRequest(...)' AJAX function will automatically print to QZ Tray. Untrusted websites will continue to show a warning dialog

Clone this wiki locally