LICENSE4J Development and Integration Guide

Development and Integration Guide
version 3.0
www.license4j.com
Copyright 2011-2012 LICENSE4J
LICENSE4J Development and Integration Guide
Table of Contents
1 2 3 Getting Started ---------------------------------------------------------------------------- 3 Key Pair --------------------------------------------------------------------------------------- 3 2.1 3.1 3.2 3.3 3.4 3.5 3.6 4 4.1 4.2 4.3 5 6 7 Key Pair Creation ------------------------------------------------------------------- 4 License File Creation -------------------------------------------------------------- 5 Floating License Creation-------------------------------------------------------- 6 Sign and Save License File ----------------------------------------------------- 7 License File Encryption ----------------------------------------------------------- 7 License File Validation ------------------------------------------------------------ 9 Floating License Validation --------------------------------------------------- 10 Single Serial Number Generation ------------------------------------------ 12 Bulk Serial Number Generation--------------------------------------------- 13 Serial Number Validation ------------------------------------------------------ 14 License File ---------------------------------------------------------------------------------- 5
Serial Number---------------------------------------------------------------------------- 11
Exceptions --------------------------------------------------------------------------------- 15 LICENSE4J License--------------------------------------------------------------------- 16 Support ------------------------------------------------------------------------------------- 17
1 Getting Started
LICENSE4J development library supports both license file creation and serial number generation. Created license files are saved on disk in plain text or encrypted format. It can be integrated into any java software running on JRE 1.6.0 and above to automate license creation for products. LICENSE4J runtime library is delivered within any java product and supports validation of plain text license files, encrypted license files and serial numbers. LICENSE4J library uses public key cryptography to validate license files and serial numbers, thus generated license will be cryptographically secure.
2 Key Pair
Key pair includes public and private keys and used in license generation and validation. Supported algorithms in Java runtime are used and LICENSE4J has following algorithm names defined as static variables in LicenseKeyPair class. Static algorithm variables should be used while generating key pairs. DSA key pair algorithm with SHA1withDSA signature algorithm and key sizes of 512, 768 and 1024.
RSA
key
pair
algorithm
with
SHA256withRSA,
SHA512withRSA
signature algorithms and key sizes of 1024 and 2048. EC key pair algorithm for serial number generation with
SHA512withECDSA signature algorithm and key size of 112. Each key pair has an ID and it is saved with created license file to keep relation between license and key pair. Created key pair file should be kept in a secure location since it includes your private key which is used in license file and serial number generation.
2.1 Key Pair Creation

createKeyPair static method creates and returns a LicenseKeyPair object
including public and private keys. Public key is delivered within your software product. Sample code to create a key pair:
LicenseKeyPair keypair = LicenseManager.createKeyPair( "Example KeyPair", "Example Description", LicenseKeyPair.KEYPAIR_ALGORITHM_DSA, LicenseKeyPair.SIGNATURE_ALGORITHM_SHA1withDSA, LicenseKeyPair.KEYSIZE_1024);
LicenseKeyPair class has all key pair, signature algorithms and key size
values defined as static variables. For serial number generation Elliptic Curve is used and it is defined as SERIALNUMBER. Check JavaDoc documentation for more information. After creating key pair you should save it on disk with saveKeyPairFile method as below.
LicenseManager.saveKeyPairFile(keypair, "mykeypairfile.key");
3 License File
License file format is same as a standard properties file. LICENSE4J includes many implemented features that are most probably will be sufficient for a standard software project licensing.
3.1 License File Creation

If you are developing your own application or want to integrate license file generation in your application you will need to use LicenseFile class. LicenseFile class has constructors and includes all implemented features setter and getter methods. First create a LicenseFile object with constructor:
Licensefile license = new LicenseFile();
Then set all required features with setter methods:
licenseObject.setProductName("your product name"); licenseObject.setProductId("your product id"); licenseObject.setProductVersion("your product version"); licenseObject.setUserFullName("customer name"); licenseObject.setUserEMail("customer e-mail"); licenseObject.setUserCompanyName("customer company name"); licenseObject.setUserTelephoneNumber("customer tel");
To load a plain text or an encrypted license file that is already created use the constructors as below:
Licensefile license = new LicenseFile(license file name); Licensefile license = new LicenseFile(license file name, yourPublicKey);
This will read the file and load all license features defined in license file. License issue date obtained from operating system and set. License ID as you may have noticed is the current system time as a long number. License issue date is changed every time you modify license, but license id does not change. If you needed, you can calculate date and time from license id when license file is created.
3.2 Floating License Creation

Floating licenses are normal license files with at least two mandatory features set which are License Count and Floating License Server Hardware ID.
Other methods of signing, saving and encrypting of floating licenses are same with normal license files.
3.3 Sign and Save License File

After creating LicenseFile object you have to sign it with your key pair. Load your previously created key pair and call signLicenseFile method to sign license file.
keypair = LicenseManager.loadKeyPair("mykeypairfile.key"); LicenseManager.signLicenseFile(keypair, licenseObject);
After signing license a signature feature will be added to license file, that is the signature of your license features and will be used by
LicenseValidator to validate that license file you delivered is not modified.
LicenseManager class has a saveLicense method to save your license to a file.
Just call the method as below and save your license file.
LicenseManager.saveLicense(licenseObject, "somelicense.lic");
3.4 License File Encryption

License file is a plain text file and can be opened with a text editor. When opened all features you defined can be read. However your customer can not change even a single character in license file, if change a character license signature validation will fail so the license will be invalid.
If for some reason you want to hide license file contents from your customer, you can encrypt it with encryptLicenseFile method.
LicenseManager.encryptLicenseFile( "somelicense.lic", "somelicense.lic.enc", keypair);
First line in encrypted license will include some information about your product separated with tabs. It is not used in license validation, written just for informational purposes. The format of first line as follows.
ProductName ProductEdition
ProductVersion (ProductID) License (LicenseID)
Encrypted license contents starts in second line. An example of encrypted license file content is given below.
XYZ Professional Edition 1.0 (9928282) License (1329228019522) f471b585a63b71f0361760a96bac3a1f42bc4d8a9bc9b3f9868ab27e556b73eb7 98ec1086b314f9d70ab214469dc26a70e71c3a4232f23d1fa306958228ce0bbdb 17c9328c209730a3c2f83cbe23e24d2abb0d2ec0a6c2e99cc1258fa13b6750aca 707c127459dd240f274e39fc956438486a104ccd09cb1343b21815a55cb42554c ef5427f5490ca362a02920fdc67155498643b3661631b72a9395d134d67a0f802 44925de73067983bef6b85a46210bcf3bf297f22d321126c0597139f2a2e30c5b 7e4a30b48fb372d9603a8600077b321cedf2d203f2b1508774ea770505a50583b b2a003fcba489372e8ef57b840e5a6e
Encrypting a license file does not affect validation procedure; it can be validated with same method as plain text license files.
3.5 License File Validation

To validate license in your software, first define your public key as a string then call validateLicenseFile method as below:
LicenseFile license = LicenseValidator.validateLicenseFile( "LicenseFile.l4j", publickeyString, "My Product ID", "MY Product Edition", "My Product Version", new Date(), // license file name // public key // product id if needed // product edition if needed // product version if needed // current date if needed
new SimpleDateFormat("dd-MM-yyyy").parse("10-06-2011")); // release date if needed
Only license file name and public key are required, all other parameters are optional and depend on your license validation need. If you have a family of products and generate different license files for each product with using a same key pair, then you can use product id parameter so license generated for one of your products will not be valid in your another product. You can use product edition parameter and generate different license files for each of your product edition, so license for one edition (e.g. standard edition) will not work on another product edition (e.g. professional edition). Product version parameter may be used to generate different licenses for major version changes in your product. For example you can generate licenses for version 1.0 of your product, when you release
version 2.0, generate new licenses for this version and customers with 1.0 version license can not use version 2.0 so they have to buy new license. Current date parameter can be null since license validator method get the current time from operating system. If you get the current time with another method you can give it as a parameter to license validator method. Product release date can be used for license maintenance period control. Most of the software comes with a one year maintenance included, after one year customer needs to buy maintenance license to update the software. LICENSE4J checks for valid license maintenance period with defined license issue date and maintenance expire date in license file against product release date given as a parameter in license validator method.
3.6 Floating License Validation

To validate license in your software, first define your public key as a string then call validateLicenseFileFloating method as below:
LicenseFile license = LicenseValidator.validateLicenseFileFloating( publickeyString, // public key string "My Product ID", "MY Product Edition", "My Product Version", new Date(), // product id if needed // product edition if needed // product version if needed // current date if needed
new SimpleDateFormat("dd-MM-yyyy").parse("10-06-2011")); // release date if needed
10
hostname, portnumber,
// host name // port number // a valid license handler // an invalid license handler
new PeriodicLicenseCheckValidHandler(), new PeriodicLicenseCheckInvalidHandler(),
new PeriodicFloatingLicenseServerConnectionCheckHandler()); // floating license server connection check handler.
You can find an example in LICENSE4J package (example no: 7). The package also includes valid and invalid license check handlers and floating license server connection check handlers samples.
4 Serial Number
LICENSE4J use Elliptic Curve cryptography to generate license serial numbers, so generated serial numbers are cryptographically secure. One drawback of generating cryptographically secure serial numbers is that serial number has a length of 55 characters. Since Elliptic Curve algorithm is supported in Java 1.7, serial number generation and validation requires Java 1.7. Serial numbers are separated with a - sign in groups of five digits. Separator character can be specified during license creation. Generated serial numbers can be validated with customer name, customer company name and some hidden internal string.
11
4.1 Single Serial Number Generation

LicenseManager class has methods for single or in bulk serial number
generation. class.
First
of
all
you
should
create
key
pair
with
SERIALNUMBER algorithms defined as static variables in LicenseKeyPair
When you have your key pair, call to generateSerialNumber will generate a serial number and return as a string.
// this will generate a serial number without name or company validation. String serial1 = LicenseManager.generateSerialNumber( keypair, null, null, null, null, "-"); // some internal string if needed // name if needed // name if needed // hardware id if needed // separator character if needed
// this will generate a serial number with name and company validation. String serial2 = LicenseManager.generateSerialNumber( keypair, null, "Some Customer", "A Company", null, "-"); // some internal string if needed // name if needed // name if needed // hardware id if needed // separator character if needed
Internal string can be used for validating for example product version, edition or another property. You can keep public key same between your major product releases and only change internal string then
12
generate serial numbers for your different product versions with different internal strings, thus serial number generated for one version will not work on the other version. If you want your users to enter name and/or company name with serial number then specify them as string variables. License validation will be performed by using these values. Hardware ID is the string you get from your customer if you like by using Hardware ID Viewer sample application in LICENSE4J package. ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789 characters can not be used as a separator character, other characters (- + / \ * ? = ! etc) can be used. You may also use null or an empty string as a parameter to not use a separator character.
4.2 Bulk Serial Number Generation

LicenseManager class has bulkGenerateSerialNumber methods, the first one
returns set of strings as below.
Set<String> serials = LicenseManager.bulkGenerateSerialNumber( keypair, "abc", "-", Integer.parseInt(count)); // your key pair // some internal string // separator character // number of serial numbers
The second bulkGenerateSerialNumber method returns set of LicenseSerialNumber objects which can be saved to disk. Also with this method you can
13
define product information to be saved in file. BUT these product information are not used in serial number generation, they are used informational only for your internal records. For example Licence Serial Number Manager GUI tool in LICENSE4J package use these product information and display in the list.
Set<LicenseSerialNumber> serials = LicenseManager .bulkGenerateSerialNumber( keypair internelString, separatorCharacter, howmanyserials, productName, productId, productVersion, productEdition); // your key pair, // your internal string // separator char // number of serial numbers // product name // product id // product version // product edition
4.3 Serial Number Validation

License serial number method validation which is a performed boolean with variable returns
validateLicenseSerialNumber
indicating a valid or invalid serial number.
boolean serialOK = LicenseValidator.validateLicenseSerialNumber( publickeyString serialnumber, null, name, company -1); // public key // serial number // some internal string if needed // name if needed // company if needed // hardware validation method
14
You should give internal string as parameter if you used in serial number generation. If you used name or company in serial number generation you should get these values from customer during serial number input (as in example applications 3 and 4 provided in LICENSE4J package). Hardware ID validation methods are: -1 for no hardware id validation; 0 for mac address validation; 1 for hostname validation; 2 for mac address and hostname validation. The first character of Hardware ID numbers is hardware id validation method.
5 Exceptions
LicenseFileReadException is thrown if license file is not found, an IO error
occurs or file format invalid.

KeyPairFileReadException is thrown if keypair file is not found, an IO error
occurs or file format invalid.

LicenseFileSecurityException is thrown if license file is not signed, signature
not valid (modified license file), or SignatureException caught.

LicenseSecurityException is thrown if Java cryptography error occurs (One
of the NoSuchAlgorithmException, NoSuchPaddingException, InvalidKeySpecException,

InvalidKeyException, InvalidAlgorithmParameterException, IllegalBlockSizeException, BadPaddingException, SignatureException caught). It is also thrown if given
public key string is null or inappropriate.
15
LicenseHardwareIDException is thrown if the license is node-locked to a
computer but license validator method cannot get running computer hardware id from operating system (One of the SocketException or
UnknownHostException caught).
LicenseContentException is thrown supplied file or string is not a valid plain
text or encrypted license file, or a valid serial number object saved to disk.
FloatingLicenseServerNotAvailableException is thrown if floating license server
connection error occurs.

FloatingLicenseNotFoundException is thrown if requested license is not found
on floating license server.

FloatingLicenseNotAvailableException is thrown if requested license is not
available (license count reached).
6 LICENSE4J License
LICENSE4J is licensed with a license file created with LICENSE4J. By default downloaded LICENSE4J does not include a license file, and it runs in trial mode. END-USER LICENSE AGREEMENT can be found in EULA.txt file. Trial mode restrictions as you may have noticed are that some fields in serial number generation window are disabled.
16
One license is required for each user using LICENSE4J GUI tools and for each developer using LICENSE4J Development library. You can buy a license on web site www.license4j.com/buy/. LICENSE4J Runtime library is free and can be delivered with your software product for license validation purposes. License can be installed in with Licensing menu item in Help menu of GUI tools, or calling the same dialog in library with command java -cp
License4J-Library.jar com.license4j.License4JLicenseDialog
7 Support
LICENSE4J support is provided via e-mail, all contact addresses are available on LICENSE4J web site www.license4j.com.
17

LICENSE4J Development and Integration Guide

Enviado por

Dados do documento

Descrição original:

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

LICENSE4J Development and Integration Guide

Enviado por

Direitos autorais:

Formatos disponíveis

Development and Integration Guide

Copyright 2011-2012 LICENSE4J