Key Generator SDK 
-1- 
Version 4.2 
Key Generator SDK 
Version 4.2 / February 2016 
This document describes the interface between our order processing system and your 
individual key generators. It defines a set of rules that you should follow closely to ensure 
proper operation of your key generator with our license servers. 
Table of Contents 
1 Overview ....................................................................................................................... 2 
1.1 Supported Types of Key Generators ........................................................................... 2 
1.2 Supported Types of Keys ............................................................................................ 3 
2 Input Values ................................................................................................................... 3 
Additional Customizable Fields ...................................................................................... 5 
3 API for key generator programs hosted by us ................................................................ 5 
1 The Key Generation Process ...................................................................................... 5 
2 Command line arguments, Input/ Output files ............................................................. 6 
3 Input File Format ......................................................................................................... 6 
Character Encoding ....................................................................................................... 6 
4 Exit Codes .................................................................................................................. 7 
5 Output Files ................................................................................................................ 8 
Textual Keys = ERC_SUCCESS .................................................................................... 8 
Binary Keys = ERC_SUCCESS_BIN ............................................................................. 8 
4 HTTP Key Generators ................................................................................................... 8 
Example request (UTF8-Encoded) ................................................................................ 9 
Example response for a text key ...................................................................................10 
Example response for a binary key ...............................................................................10 
Error handling ...............................................................................................................10 
Success / Content Disposition and Filename ................................................................ 11 
Security Considerations ................................................................................................ 11 
5 Delivery e-mail Key Templates ...................................................................................... 11 
6 General Rules and Prerequisites ..................................................................................12 
7 How to submit a key generator .....................................................................................12 
8 F.A.Q. ...........................................................................................................................12 
9 Examples / Templates ...................................................................................................13 
Delphi XE .....................................................................................................................13 
C# .................................................................................................................................13 
Pdf compressor - Compress reduce PDF size in C#.net, ASP.NET, MVC, Ajax, WinForms, WPF
C# Code & .NET API to Compress & Decompress PDF Document
pdf change font size in textbox; change font size on pdf text box
Pdf compressor - VB.NET PDF File Compress Library: Compress reduce PDF size in vb.net, ASP.NET, MVC, Ajax, WinForms, WPF
VB.NET PDF Document Compression and Decompression Control SDK
pdf edit text size; adjust pdf page size
Key Generator SDK 
-2- 
Version 4.2 
JAVA .............................................................................................................................13 
Visual Basic .NET .........................................................................................................14 
HTTP Generator Examples ...........................................................................................14 
10 Key Generator Tester ....................................................................................................15 
1 Overview 
This document describes the interface between our order processing system and your 
individual key generators.  
Here the term “key” refers to any type of information that is generated upon the successful 
completion of a sale and sent to your customers, this could be: 
 a license serial number 
 a file containing a cryptographic key that unlocks your application 
 a HTML file including the key as well as additional registration information 
 whatever you can put into a file … 
The Key Generator SDK (Software Developers Kit) comprises of 
 this documentation, 
 code examples in a number of different programming languages and 
 a test program that calls your key generator and displays its results. 
1.1 Supported Types of Key Generators 
Your key generator can be implemented in one of several different ways: 
 As a program that is hosted on your server and called via HTTP/ HTTPS. We 
recommend this option, as you have the full control of your server, e.g. to check for 
errors, testing your implementation and schedule system updates 
 As a program that runs on our servers: 
o Windows Server 2012 console application executables (EXE, compiled for the 
x86 32bit or 64 bit architecture). COM+ server / OCX binaries requiring 
registration are not supported! 
o JAVA programs (currently JRE Version 1.3 through 1.4 supported, see section 
9) 
o .NET Framework Version 2.0 through 4.5 assemblies 
IMPORTANT: Before you continue reading, please make sure that you have downloaded 
the most recent version of this document from the Control Panel under:  
Start Page > Documentation 
NOTEPlease read this document carefully before writing and submitting a custom key 
generator. We will not accept new key generators that do not comply with the latest key 
generator specification. 
C# Word: How to Compress, Decompress Word in C#.NET Projects
Create a C# Project. In order to use the Word compressor and decompressor are dedicated to provide powerful & profession imaging controls, PDF document, image
change font size pdf fillable form; pdf file size
VB.NET Image: Multi-page TIFF Editor SDK; Process TIFF in VB.NET
How to view, edit, manipulate and annotate multi-page tiff document image file using VB.NET sample code.
best way to compress pdf file; change font size fillable pdf
Key Generator SDK 
-3- 
Version 4.2 
1.2 Supported Types of Keys 
For historical reasons this SDK supports two different types of keys. 
 Textual keys are made of plain text (e.g. “ABCD-1234-WXYZ”). They will be displayed 
inline inside the delivery e-mail that is sent to your customer. Optionally you can provide 
a key template that surrounds your key with additional information. (see section 5 
Delivery e-mail Key Templates”). 
 Binary keys can include anything and are forwarded to the customer as an attachment 
to the delivery e-mail. Their content is described by a MIME media type (e.g. text/xml) 
and a filename that has to be provided by your generator. Obviously binary keys are a 
superset of textual keys. (see http://www.iana.org/assignments/media-types/) 
2 Input Values 
The key server will collect all available data for the following fields and forward them to your 
key generator as input. Fields listed in bold always contain valid information. Other fields may 
be left out, if a particular piece of information is neither applicable nor available. 
You do not, of course, have to use all of these values to generate the key. Which ones and 
how many of these variables you use is left to your discretion. 
VB.NET Word: Word Docuemnt Compression and Decompression Guide
Please follow VB sample code below to compress Word file, and also customize your own Word compressor via changing some adjustable code.
adjust pdf size preview; pdf paper size
Key Generator SDK 
-4- 
Version 4.2 
FIELD KEY (TAG) 
SIZE 
DESCRIPTION 
PURCHASE_ID 
10 
Our purchase id number. (1
st
part of the unique key) 
Type: decimal string representation of an unsigned 32bit 
integer number > 0 
RUNNING_NO 
If the customer buys multiple products in one purchase they will 
be enumerated by RUNNING_NO. (2
nd
part of the unique key. 
The combination of PURCHASE_ID and RUNNING_NO is 
guaranteed to be unique!) 
Type: decimal string representation in the range 1..9999 
PURCHASE_DATE 10 
The date of purchase as string "DD/MM/YYYY", e.g. 
"24/12/2016":  
IMPORTANT: Your code must be able to parse this exact 
format, regardless of any user and/or OS settings! 
PRODUCT_ID 
10 
ID of the product purchased. (Useful if you write a key 
generator that works for multiple products.) 
Type: decimal string representation 
QUANTITY 
The number of copies ordered. Type: decimal string 
representation of an unsigned 32bit integer number > 0 
REG_NAME 
100 The name to which the customer chose to license the product. 
ADDITIONAL1 
500 1
st
Customizable Field (see below) 
ADDITIONAL2 
500 2
nd
Customizable Field (see below) 
RESELLER 
100 The name of the reseller or affiliate involved in this order (if 
applicable). 
LASTNAME 
50 
The customer's last name. 
FIRSTNAME 
50 
The customer's first name. 
COMPANY 
100 The customer's company name (if applicable). 
EMAIL 
100 The customer's e-mail. 
PHONE 
50 
The customer's telephone number. 
FAX 
50 
The customer's fax number. 
STREET 
100 The customer’s street address. 
CITY 
100 The customer's city. 
ZIP 
20 
The customer’s ZIP or Postal Code. 
STATE 
40 
The customer’s state or province (e.g. Florida in the US, 
Okayama in Japan) 
(Note: The state field could be used for any country state/ 
prefecture/ province) 
COUNTRY 
50 
The customer's country (English name) 
ENCODING 
var. <not present> = ISO-8859-1 (Latin 1) encoding 
“UTF8” = UTF8 Unicode 
LANGUAGE_ID 
The customer's preferred language:  
1=English / 2=German / 3=Portuguese / 4=Spanish / 5=Italian / 
6=French / 7=Norwegian / 8=Dutch / 9=Swedish / 10=Finnish / 
11=Japanese / 12=Russian / 13=Korean / 14=Danish / 
15=Simplified Chinese / 16=Polish / 17=Chinese Traditional / 
18=Czech / 19=Hungarian / 20= Turkish / 21=Greek 
Additional parameters in Version >= 2 
FIELD KEY (TAG) 
SIZE 
DESCRIPTION 
PROMOTION_NAM
var. Name of the promotion 
PROMOTION_COU
PON_CODE 
var. The actual promotion coupon code used for this order 
Key Generator SDK 
-5- 
Version 4.2 
FIELD KEY (TAG) 
SIZE 
DESCRIPTION 
ADD[<identifier>] 
var. User defined (hidden) additional parameters (see below) 
SUBSCRIPTION_D
ATE 
10 
Date of Subscription (format see PURCHASE_DATE) 
START_DATE 
10 
Start date of current re-billing period (format see 
PURCHASE_DATE) 
EXPIRY_DATE 
10 
Expiry date (date of next re-billing) (format see 
PURCHASE_DATE) 
ISO_CODE 
The customer’s two letter country code 
For example: US=United States, DE=GERMANY 
NLALLOW 
Customer has agreed to receive the publisher's newsletter or not 
Possible values: NLALLOW="YES" or "NO" 
INVOICE 
Payment on invoice for purchase orders. First call generates a 
temporary key and the second call, once the invoice has been 
paid, will generate the permanent key. 
Possible values: INVOICE="UNPAID" or "PAID" 
Note: If you want to use this parameter please contact the 
PRM Team to enable this for you. 
These additional parameters are only passed to the generator when they have been flagged 
with version >= 2 in our system (which is true for all new generator installations). 
Version 1 does not pass the additional parameters listed above for enhanced backwards 
compatibility with old legacy generators that depend on the exact ordering of parameters 
(which was never guaranteed). 
You should use version 3 to receive data UTF-8 encoded. This allows you for instance to 
support Chinese and Arabic.  
Additional Customizable Fields 
In addition to our fixed set of fields, we offer two customizable fields named “ADDITIONAL1” 
and “ADDITIONAL2”. These additional input values are optional and can be added to your 
order form by entering them in the Control Panel under Products > Additional Fields. 
Provide a short description of the type of information that you would like your customers to 
enter in these fields. The check boxes allow you to make a field required/ mandatory (checked) 
or optional (not checked). If your generator relies on these additional input values, don't forget 
to make the appropriate changes. 
Note: There is currently no way to validate additional input fields during the order process.  
3 API for key generator programs hosted by us 
Before going into the details of the key generator interface, here is an overview of the steps 
involved in the key generation process: 
1 The Key Generation Process 
1. Order processing system calls key server 
1. Key server writes input values to a temporary file (see section 2) 
2. Key server executes the key generator: 
1. Key generator reads input file 
2. Key generator decodes & checks input parameters 
3. Key generator calculates license key(s) 
Key Generator SDK 
-6- 
Version 4.2 
4. Key generator writes output files 
5. Key generator returns exit code 
3. Key server checks exit code and reads output files 
4. Key server checks if a key template is available for textual keys and inserts 
the generated key into the template 
5. Key server saves output files / error log into the database 
2. Order processing prepares the “delivery to customer” e-mail 
1. binary keys will be attached with the MIME type and filename returned by the 
key generator 
2. textual keys will be displayed inline 
2 Command line arguments, Input/ Output files 
EXE and JAVA generators are called with three command line arguments, all of which are file 
names, e.g. 
 First is the input file to be read by the key generator 
 The 2
nd
and 3
rd
parameter are output filenames which don’t exist upon invocation of the 
key generator, since they should be created by the key generator itself.  
Output filenames are provided by the calling server in order to be able to set their 
directory, make their names unique, read their contents and delete them after their 
contents has been copied to the database. 
3 Input File Format 
The input file format is somewhat similar to Windows INI file sections. Each line contains a 
key-value-pair separated by a '='. The values are terminated at the end of line (CR/LF), and 
may contain non-ASCII characters depending on the input encoding, e.g. 
When parsing the lines, all unknown keys should be ignored since there may be new input 
parameters in the future. There is no guarantee that the lines appear in a defined order, except 
for the encoding parameter, which is always first – if present. 
Character Encoding 
The encoding of the in- and output files defaults to the ISO-8859-1 (Latin 1) encoding. If the 
file starts with the line “ENCODING=UTF8” it will be UTF8 encoded, e.g. 
KeyGen.exe c:\temp\input-12653.txt c:\temp\input-12653.out1 
c:\temp\input-12653.out2 
PURCHASE_ID=12345678 
RUNNING_NO=1 
PURCHASE_DATE=04/07/2004 
PRODUCT_ID=100000 
LANGUAGE_ID=2 
QUANTITY=1 
REG_NAME=Peter "Test" Müller 
LASTNAME=Müller 
FIRSTNAME=Peter 
EMAIL=mueller@test.net 
Key Generator SDK 
-7- 
Version 4.2 
The file written by the key server will not include any byte order marks for UTF8. 
For a description of the available input parameters see section 5. 
4 Exit Codes 
The generator must provide an exit code, which tells the key server about the success or the 
reason for failure. See the following table for all predefined exit code values.  
Exceptions should be caught in the key generator main function and mapped to these error 
codes. Exception messages should be written to the first output file. 
ERROR CODE 
DESCRIPTION 
ERC_SUCCESS 
No error (a valid textual key has been generated) 
ERC_SUCCESS_BIN No error (a valid binary key has been generated) 
ERC_ERROR 
General error or runtime exception 
ERC_MEMORY 
Memory allocation failed 
ERC_FILE_IO 
Error during file i/o (map I/O exceptions to this error code) 
ERC_BAD_ARGS 
Missing, incomplete or wrong command line arguments 
ERC_BAD_INPUT 
Missing or incomplete input values or encoding 
ERC_EXPIRED 
Key generator has expired due to a limited validity period 
ERC_INTERNAL 
Other internal errors 
ENCODING=UTF8 
PURCHASE_ID=12345678 
RUNNING_NO=1 
PURCHASE_DATE=04/07/2004 
PRODUCT_ID=100000 
LANGUAGE_ID=2 
QUANTITY=1 
REG_NAME=Peter "Test" Müller 
LASTNAME=Müller 
FIRSTNAME=Peter 
EMAIL=mueller@test.net 
NOTE: In order for UTF8 input to be sent to your key generator it has to be registered as a 
Unicode compliant SDK 3 key generator with our support team upon submission / 
installation of the generator. Otherwise your generator will always get ISO-8859-1 input and 
non-ISO-8859-1 characters will be replaced by question marks. 
NOTE: The encoding of e-mails generated by the order processing system depends on the 
actual content of the e-mail body. If your textual key has characters that do not belong to 
(US-ASCII or ISO-8859-1) it will use the UTF8 encoding. Japanese mails will be encoded 
using ISO-2022-JP, if possible. Other encodings may be added to support other languages 
in the future. Since not all customers use UTF8 enabled mail clients, textual keys should 
only include characters that are common in their language. 
NOTE: Please do not return other values or change the numbering scheme provided in the 
SDK examples! 
Key Generator SDK 
-8- 
Version 4.2 
5 Output Files 
The data that should be written to the output files depends on success or failure of the key 
generation and the type of the key generator. Their interpretation by the key server is 
determined by the exit code. 
On failure the error message should be provided in the first result file. The second file can be 
omitted in this case. Example: Exit code ERC_BAD_INPUT and output file #1 contains "Value 
for REG_NAME must contain at least 8 characters!". 
On success the output file contents depends on the type of the key generator: 
Textual Keys = ERC_SUCCESS 
 The first output file is interpreted as the User Key which will be delivered to the 
customer. 
 The second output file is interpreted as the so-called CCKey (CC for “carbon copy”), 
and stored for your reference. You can view it in the sales section of the Control Panel, 
or in the export file. By creating a separate CCKey you can decide which information is 
reported to you, e.g. probably you are only interested in the key itself, but not in the 
instruction text surrounding it. 
Binary Keys = ERC_SUCCESS_BIN 
The first file is interpreted as a content description of the data that is provided in the second 
file. It comprises of the contents MIME type and the desired filename separated by a single 
colon. For example: 
The actual binary key data has to be returned in the second output. 
Keep your binary keys small in order to speed up e-mail delivery. Many e-mail accounts have 
size restrictions for incoming mail. 
NOTE: For binary keys there is no carbon copy key feature, but the XML order notification 
contains a copy of the binary key file. 
4 HTTP Key Generators  
Web based key generators reside on your server and will be called by our order processing 
system on each completed purchase of a product. 
Our system will submit the key generator input values as form data via a HTTPS request using 
the POST method. Your server should return the proper key in the response. 
IMPORTANT: The file has to be encoded using the same encoding as the input file, using 
CR/LF for line breaks. 
NOTE: You may want to generate a short usage description together with the key. If you 
would like to provide translations of this text for different languages, you can use the 
LANGUAGE input value. Anyhow, you should have a look at the key template feature before 
using this feature as it provides a more convenient way of text customization. 
application/octet-stream:key.bin 
Key Generator SDK 
-9- 
Version 4.2 
e.g. https://keygen.yourcompany.com/keygen  
We also support the unsecure HTTP protocol – however, we do not recommend sending 
unprotected data after some initial development tests. Please make sure your certificate is 
trusted. There are multiple external websites, providing the service to check your SSL 
certificate on your server without costs. A first local test is to check your SSL certificate with 
your browser. The below screenshots shows a valid and an invalid SSL certificate for server 
mycommerce.com.   
VALID 
INVALID 
Input Values will be passed as URL encoded (application/x-www-form-urlencoded) variables. 
Please use version “UTF-8 Unicode” to get data as Unicode. 
The below screenshot shows an example configuration in CP.  
The sorting of parameters is not defined, they can appear in any order and may be omitted if 
they have no value, therefore you should reference them only by their unique identifier. 
Example request (UTF8-Encoded) 
Header:  
Key Generator SDK 
-10- 
Version 4.2 
Body:  
Example response for a text key 
Header:  
Body: 
Example response for a binary key 
Header:  
Body: 
Error handling 
Errors are indicated by status codes other than 200. We recommend that you use “400 Bad 
Request”. Please return a line error message indicating the reason for failure. 
Our system retries failed requests up to 3 times before giving up. Please make sure to use a 
reliable provider so that your orders can be fulfilled in real time. If you cannot guarantee 24/7 
availability of your server you should consider submitting a generator to be hosted by us (as 
specified in section 2) or revert to use plain key lists. 
HTTP_CONNECTION = close 
REQUEST_URI = /keygen 
REQUEST_METHOD = POST 
GATEWAY_INTERFACE = CGI/1.1 
REMOTE_PORT = 59320 
REMOTE_ADDR = 1.23.45.6 
HTTP_USER_AGENT = ShareitLicenceAgent/2.0 
HTTP_ACCEPT = text/html, */* 
HTTP_HOST = yourcompany.com 
CONTENT_LENGTH = 263 
CONTENT_TYPE = application/x-www-form-urlencoded 
UNIQUE_ID = VrB17UBaMGUAAHVR3ZAAAAAK 
REQUEST_TIME_FLOAT = 1454405101.8306 
REQUEST_TIME = 1454405101 
PURCHASE_ID=481234567&PURCHASE_DATE=01%2F02%2F2016&RUNNING_NO=1&PR
ODUCT_ID=123456&QUANTITY=1&REG_NAME=John+Doe&LASTNAME=Doe&FIRSTNAM
E=John&EMAIL=JohnDoe@digitalriver.com&STREET=Street+1&CITY=K%C3%B6
ln&ZIP=50679&COUNTRY=Germany&LANGUAGE_ID=1&ISO_CODE=DE&NLALLOW=NO 
HTTP/1.1 200 OK 
Content-Type: text/plain 
TEST-DG12-SD92-98DS 
HTTP/1.1 200 OK 
Content-Type: image/gif 
Content-Disposition: filename=test.gif 
GIF89a Ò×ÛóôõíðóÕÙÝ éëðä çê»ÁÆñô÷ÙÝá 
Documents you may be interested
Documents you may be interested