Link-OS Multiplatform SDK Webservices Intro

Introduction
Certificate Requirement Overview
Certificate Request Generation

Link-OS Multiplatform SDK
(for Webservices)

Introduction

This information describes the certificate requirements and configuration for a Tomcat based implementation of a Websocket server as it relates to the Zebra MultiPlatform SDK. The implementation allows Zebra Print DNA printers running Link-OS^® to connect securely and communicate using the Link-OS Multiplatform SDK.

You will need an SSL certificate in order to establish communications between your Websocket server and a Print DNA printer. Although you may request and obtain a signed certificate from Zebra, we strongly recommend either creating and using your own self-signed certificates or obtaining them from a Publicly Trusted Certificate Authority. That provides you with greater flexibility and control of the certificates and ongoing management of them. As Zebra is not a trusted certificate authority, there's no advantage to obtaining a Zebra signed certificate.
The following sections describe the requirements and steps needed to create your own certificates or obtain one from Zebra.

API documentation for the SDK Weblink support is included in the Java API documentation.

More information regarding the Weblink/Websocket protocol can be found in the Weblink guide. Printer specific information and troubleshooting can be found in the Link-OS addendum.

Certificate Requirement Overview

This information supercedes what's included in the v2.14.5198 SDK due to changes in our certificate signing process and the ability to use self-signed or publicly trusted CA signed certificates.

Prior to Link-OS version 4, our printers only contained an embedded SHA-1 certificate for weblink connections. Through our firmware release notes, Zebra has given advanced notice that SHA-1 support will be removed in a future version of the printer Link-OS operating system. This step is being taken to enhance product security. SHA-1 is still supported in Link-OS v6.x but is intended to be removed in Link-OS v7.0 and beyond.

If you have an existing application using a Zebra signed SHA-1 certificate for weblink connections, you may consider the need to transition to SHA-256 in the future.

Link-OS version 5 and later contain a SHA-256 embedded certificate and Zebra may now only issue SHA-256 signed certificates in accordance with our recommended security best practices.

Alternatively, you have the option not to use a Zebra signed certificate but to supply and use your own certificates which requires a certificate chain to be loaded onto every printer that needs to connect to your server. Security and certificate information related to Zebra printers can be found in our PrintSecure Administration Guide available here. This support article contains the instructions to create your own self-signed certificates.

Please note the following important information if you wish to use Zebra signed SHA-256 certificates:

The time to sign and return certificate requests may take 7 – 10 days.
Zebra SHA-256 signed certificates have a 3 year expiration period and will need to be renewed prior to the expiration date.

Note: Zebra does not provide a notification service of certificate expiry.

Where certificates are required for development and test, the common name maybe a computer hostname or static IP address. Since Zebra cannot verify domain ownership in this case, the certificate expiration period shall be shorter.
All printers will require Link-OS 5 or later (available here) in order to successfully connect using this certificate.
A new CA chain is required in combination with the SHA-256 signed certificate. If you have previously installed the ZebraCAChain.cer file, you will need to remove it and install the new CA chain provided with the signed certificate.

In addition, certificate requests need to conform to these requirements:

The domain for the common name field of the certificate to be signed shall be either :
1. a specific non-wildcard subdomain (acceptable example: something.mydomain.com)
2. a wildcard that must contain a 'z' or 'zebra' or 'zserver' subdomain.

Acceptable Examples	Unacceptable Examples
*.z.mydomain.com	*.mydomain.com
*.z.subdomain.mydomain.com	*.subdomain.mydomain.com
*.zebra.mydomain.com
*.zebra.subdomain.mydomain.com
*.zserver.mydomain.com
*.zserver.subdomain.mydomain.com

a computer hostname or static IP address (for development and test only which will have a shorter expiration period).

The CSR must contain all the fields listed here with the addition of the email field.
1. It must include the correct 2-character ISO format country code detailed in the link above.

Shall not use a SHA1 signature algorithm.

Proof of domain ownership by either of the following methods:
1. Sending the CSR to Zebra in an email where the email domain matches the domain in the CSR.
2. A Domain Control Validation challenge. Upload an HTML page with content we specify to a folder on the website for the common name you're using.

Note: This is not a requirement for certificates used for development & test as noted above.

Usage on AWS
1. If you’re using AWS, the cryptographic algorithm of an imported certificate must match the algorithm of the signing CA. Zebra maintains an ECC Prime-256 Weblink server CA and therefore for use on AWS you should provide us a CSR using ECC algorithm and not RSA.

This online tool can be used to verify the fields in your CSR before sending it to Zebra for signing.

Certificate Request Generation

These are the steps to get a certificate signed by Zebra.

Download and install the latest version of OpenSSL on your computer.
Create a folder on your computer named zebra_certs. This folder may reside anywhere you choose (desktop, etc.).
From the Start menu, choose "Run" and type cmd.exe. This opens a Command Prompt.

Note: This step requires that you have administrator privileges.

In the Command Prompt, navigate to your zebra_certs folder and type the following commands, pressing Enter after each command. All the following openssl commands should be run in this Command Prompt.

set RANDFILE=.rnd
openssl

Zebra supports RSA and ECC certificates. Listed below are command examples for generating certificate requests for both RSA and ECC types. Enter the appropriate command for either RSA or ECC and substitute the field values for your information:

These are the required certificate fields used the certificate request generation command:

"/C=xx/ST=yyyyy/L=aaaaa/O=jjjjj/OU=rrrrrr/emailAddress=sssss/CN=uuuuu" -key uuuuu.key -out uuuuu.csr

Where:
xx is the two-digit ISO Country Code
yyyyy is the full State name
aaaaa is the City or town name
jjjjj is the Organization or company name
rrrrrr is the Organizational unit name
sssss is the contact email address for the certificate creator
uuuuu is the full DNS name of the server

RSA

Type the following commands followed by Enter:

genrsa -out zserver.abccompanyinc.com.key 2048

req -new -sha256 -subj "/C=US/ST=Illinois/L=Anytown/O=ABC Company Inc/OU=IT
Team/emailAddress=John@abccompanyinc.com/CN=zserver.abccompanyinc.com" -key
zserver.abccompanyinc.com.key -out zserver.abccompanyinc.com.csr

ECC

Type the following commands followed by Enter:

ecparam -out ec_params.pem -name prime256v1

req -new -sha256 -subj "/C=US/ST=Illinois/L=Anytown/O=ABC Company Inc/OU=IT Team/emailAddress=John@abccompanyinc.com/CN=zserver.abccompanyinc.com" -newkey ec:ec_params.pem -keyout zserver.abccompanyinc.com.key -out zserver.abccompanyinc.com.csr -nodes

Note: zserver.abccompanyinc.com is the full DNS name of your server. The DNS name must match the DNS name supplied to the printer as the weblink location URL.

Important: These commands generate the key which is part of the security for the server communications. It should be kept secure and backed up and not given out to anyone. If unauthorised individuals get the key, the security of the connection between the Zebra printer and the Zebra Servlet may be compromised.

Email the certificate request file (.csr file) to WTech@Zebra.com
The certificate will be signed and sent back to you.
Copy the zip file containing the signed certificate files to the zebra_certs folder.
Extract the signed certificate files into the same folder.
Enter the following command and replace the filenames where necessary:

pkcs12 -export -in zserver.abccompanyinc.com.crt -inkey zserver.abccompanyinc.com.key -out zserver.abccompanyinc.com.p12 -name tomcat -CAfile WeblinkCAChain.crt -caname root –chain

Where zserver.abccompanyinc.com is the full DNS name of your server.

Note: This step converts the certificate and asks you to set a passkey.

Enter a standard alphanumeric passkey, but do not include any special characters (for example, do not use characters such as $, %, &, or @).

Note: The passkey should be something easy to remember but should not be distributed to anyone.

Configure your server to use the certificate file and passkey from the steps above.

Steps to configure a Tomcat server

Navigate to the Tomcat server.xml file in the following folder:

%TOMCAT_INSTALL_LOCATION%\conf

Modify the ssl connector to use the new key/cert. Edit the server .xml file to add the following <Connector ... /> tag within the <Service> tag.

Where zserver.abccompanyinc.com is the full DNS name of your server.
Where YourPasskey = passkey from Step 11 above.

Run the following command from the zebra_certs folder. Ensure you run the command for the same JRE used by the Tomcat instance.

keytool -importcert -file WeblinkCAChain.crt –keystore "%JRE_HOME%\lib\security\cacerts" -alias "ZebraCAChain"

Note: The default password for the Java cacert keystore is: changeit

Copy zebra.war from $ZEBRA_SDK_INSTALL_PATH$\link_os_sdk\Webservices\VERSION\lib to $TOMCAT_INSTALL_LOCATION$\webapps
Restart the Tomcat server.
Ensure the printer weblink.ip.conn[1|2].location value is set to "https://$CN$/zebra/weblink/". Where $CN$ is your server host name and ensure the / is present at the end or the printer will fail to connect.

To Top