Important Security Update: PrintOS API Authentication Migrating to SHA256

This is an important announcement for all developers and users of the Printos API. To enhance the security and robustness of our platform, we are upgrading the API authentication method from SHA1 to SHA256. This change will be effective from March 30th, 2022.

PLEASE READ/CLICK HERE FOR FULL DETAILS

This transition is crucial to maintain the highest security standards for your PrintOS integrations. Below, we outline the necessary steps to ensure your applications remain compatible and secure.

Generating Your API Key and Secret in PrintOS

To authenticate your applications with the PrintOS APIs, you need to generate a unique Key/Secret pair within your PrintOS account. Here’s a step-by-step guide:

1. Access the Marketplace: Navigate to the application switcher, located at the top right corner of your PrintOS interface. The application switcher icon is depicted as . Click on this icon and select “Marketplace” from the dropdown menu. This will take you to the PrintOS Marketplace.

2. Go to Application Connectors: Within the Marketplace, locate and select the “Application Connectors” tab. This section is dedicated to managing API keys and secrets for your applications.

3. Add a New Connector: Click on the “Add Connector” tile. This action initiates the process of creating a new API Key/Secret pair.

4. Descriptive Name: In the “Description” field, provide a clear and descriptive name for your connector. This name should help you easily identify the purpose of this specific Key/Secret in the future (e.g., “Order Processing API Key” or “MyCompany Integration Key”).

5. Filter by Application: Use the “Filter by Application” dropdown menu to select the specific PrintOS application for which you are generating this Key/Secret. This ensures the key is correctly scoped for the intended application.

6. Choose the Appropriate Role: From the “Role” dropdown menu, select the role that aligns with the API functionalities you intend to use. The role defines the permissions associated with this Key/Secret. Available roles are detailed in the next section.

7. Generate Key/Secret: Click the “Add” button to finalize the process and generate your unique Key/Secret pair.

8. View Your Credentials: Return to the “Application Connectors” tab. Your newly generated Key/Secret will be listed here.

Important Security Caution: Treat your Key/Secret with utmost confidentiality. Providing this information to any third party grants them control over your PrintOS APIs and potentially your account. Only share these credentials with trusted parties.

Understanding Key/Secret Roles for PrintOS API Access

The “Role” you select when generating your Key/Secret determines the level of access granted to your application. Here’s a breakdown of the available roles and their functionalities within the PrintOS API:

• Order Creation: This role grants permissions specifically for order submission, file uploading related to orders, and querying information about created orders and files. It is ideal for applications focused on initiating print orders.
• Order Creation and Enquiries: Expanding on the “Order Creation” role, this option also allows your application to query various system information. This includes accessing details about product types, SKUs (Stock Keeping Units), and other relevant system data. This role is suitable for applications that need to both create orders and retrieve product or system information.
• Print Beat Data Access: This role provides access to Print Beat data, HP’s print production monitoring solution. You can query historical and near-real-time data, as well as Color Beat* and OEE (Overall Equipment Effectiveness) data (*Color Beat access requires a separate subscription). This role is designed for applications focused on performance monitoring and data analytics related to print production.
• Jobs Enquiries: This role offers access to job-specific information for supported devices through the Print Beat API – jobs context. It allows you to retrieve detailed data about individual print jobs.
• Composer SDK: This role is specifically for applications utilizing PrintOS Composer. It enables the upload of variable data components and the rendering of PDF outputs using the PrintOS Composer service.

Implementing HMAC Authentication with SHA256

To securely communicate with the PrintOS API, your application must include specific HTTP headers in each request. These headers facilitate HMAC (Hash-based Message Authentication Code) authentication using the SHA256 algorithm.

The following HTTP header fields are mandatory for every API request:

• x-hp-hmac-authentication: This header contains the authentication signature. It follows the format Key:Signature, where Key is the API Key you generated in PrintOS, and Signature is a generated HMAC Hex String (explained below).
• x-hp-hmac-date: This header provides the current timestamp in ISO 8601 format (YYYY-MM-DDThh:mm:ss.sssZ). Crucially, the timestamp must be in UTC (GMT/Zulu) time, indicated by the trailing ‘Z’. Ensure your application generates timestamps in UTC.
• x-hp-hmac-algorithm: This header specifies the hashing algorithm used for the signature. For all future requests, this must be set to “SHA256”. This is a mandatory header to signify the use of the updated SHA256 authentication method.

The Signature component of the x-hp-hmac-authentication header is created by signing a specific message using the SHA256 algorithm and your PrintOS generated Secret. The message to be signed adheres to the following format: method + ” ” + path + timestamp

• method: This is the HTTP method used for the API request (e.g., POST, GET, PUT, DELETE). This value must be in ALL CAPS.
• path: This represents the API endpoint you are accessing (e.g., “/api/partner/orders”, “/api/printbeat/data”).
• timestamp: This is the same timestamp used in the x-hp-hmac-date header, generated at the time of request submission and in ISO 8601 format.

Example Message to Sign: “POST /partner/api/orders2023-10-27T10:30:00.000Z”

Code Examples for Generating HMAC Headers

Below are code snippets in various programming languages demonstrating how to generate the necessary HMAC headers. For more comprehensive examples and SDKs, please visit our GitHub repository.

C#

 private static void CreateHmacHeaders(string method, string path, HttpClient client) { string timeStamp = DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ"); string stringToSign = method + " " + path + timeStamp; HMACSHA256 hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret)); byte[] bytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(stringToSign)); string signature = BitConverter.ToString(bytes).Replace("-", string.Empty).ToLower(); string auth = key + ":" + signature; client.DefaultRequestHeaders.Add("x-hp-hmac-authentication", auth); client.DefaultRequestHeaders.Add("x-hp-hmac-date", timeStamp); client.DefaultRequestHeaders.Add("x-hp-hmac-algorithm", "SHA256"); }

Java

 public String getHmacAuthentication(String method, String path, String timeStamp) throws InvalidKeyException, NoSuchAlgorithmException {     SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(), "HmacSHA256");     Mac mac = Mac.getInstance("HmacSHA256");     mac.init(secret_key);     String toHash = method + " " + path + timeStamp;     byte[] rawHmac = mac.doFinal(toHash.getBytes());     StringBuilder hash = new StringBuilder();     for (byte b : rawHmac) {         hash.append(String.format("%02x", b & 0xff));     }              return key + ":" + hash.toString(); }

JavaScript

 function createHeaders(method, path) { var timestamp = (new Date()).toISOString() var toSign = method.toUpperCase() + " " + path + timestamp var hash = crypto.createHmac("sha256", secret) hash.update(toSign) var sig = hash.digest("hex"); var headers = { "X-HP-HMAC-Authentication": key + ":" + sig, "X-HP-HMAC-Date": timestamp, "X-HP-HMAC-Algorithm": "SHA256" } return headers; }

PHP

 function createHmacAuth($method, $path, $timestamp) { global $key, $secret; $str = $method . ' ' . $path . $timestamp; $hash = hash_hmac('sha256', $str, $secret); return $key . ':' . $hash; }

Python

 def create_headers(method, path, timestamp): string_to_sign = method + ' ' + path + timestamp local_secret = secret.encode('utf-8') string_to_sign = string_to_sign.encode('utf-8') signature = hmac.new(local_secret, string_to_sign, hashlib.sha256).hexdigest() auth = key + ':' + signature return { 'content-type': 'application/json', 'x-hp-hmac-authentication': auth, 'x-hp-hmac-date': timestamp, 'x-hp-hmac-algorithm' : 'SHA256' }

Ruby

 def create_hmac_auth(method, path, timestamp) str = method + ' ' + path + timestamp; hash = OpenSSL::HMAC.hexdigest("SHA256", $secret, str) return $key + ":" + hash end

Need Access to PrintOS API?

If you are looking to integrate with the PrintOS API but do not currently have a PrintOS account, you can request a development account. Click the button below and complete the form to begin the access request process. Providing detailed information in your request will help expedite the process.

Request Access

By migrating to SHA256, PrintOS is committed to providing a secure and reliable platform for all users. Ensure you update your API integrations to align with these changes by March 30th, 2022, to maintain uninterrupted access to PrintOS APIs.