From 55a8483884c70b03c86a6508469f708e48211638 Mon Sep 17 00:00:00 2001
From: gcontini <1121667+gcontini@users.noreply.github.com>
Date: 周六, 28 11月 2020 09:38:30 +0800
Subject: [PATCH] improve documentation add project/feature documentation
---
src/templates/licensecc_properties.h.in | 8 ++
/dev/null | 4 -
doc/api/public_api.rst | 9 ++
doc/usage/concepts.rst | 83 ++++++++++++++++++++
include/licensecc/datatypes.h | 17 ++-
doc/usage/issue-licenses.md | 4
include/licensecc/licensecc.h | 11 +-
README.md | 8 +-
doc/index.rst | 46 +++++-----
9 files changed, 145 insertions(+), 45 deletions(-)
diff --git a/README.md b/README.md
index f17eb2b..081b830 100644
--- a/README.md
+++ b/README.md
@@ -5,10 +5,10 @@
[](https://en.wikipedia.org/wiki/C%2B%2B#Standardization)
[](http://github.com/badges/stability-badges)
[](https://opensource.org/licenses/BSD-3-Clause)
-[](https://travis-ci.org/open-license-manager/open-license-manager)
+[](https://travis-ci.org/open-license-manager/licensecc)
[](https://github.com/open-license-manager/licensecc/actions)
-[](https://www.codacy.com/manual/gcontini/open-license-manager?utm_source=github.com&utm_medium=referral&utm_content=open-license-manager/open-license-manager&utm_campaign=Badge_Grade)
-[](https://codecov.io/gh/open-license-manager/open-license-manager)
+[](https://www.codacy.com/gh/open-license-manager/licensecc/dashboard?utm_source=github.com&utm_medium=referral&utm_content=open-license-manager/licensecc&utm_campaign=Badge_Grade)
+[](https://codecov.io/gh/open-license-manager/open-license-manager)
[](http://github.com/open-license-manager/licensecc/issues)
[](https://groups.google.com/d/forum/licensecc)
@@ -31,7 +31,7 @@
- a C++ library with a nice C api, `licensecc` with minimal (or no) external dependencies (the part you have to integrate in your software) that is the project you're currently in.
- a license debugger `lcc-inspector` to be sent to the final customer when there are licensing problems or for calculating the pc hash before issuing the license.
- a license generator (github project [lcc-license-generator](https://github.com/open-license-manager/lcc-license-generator)) `lccgen` for customizing the library and generate the licenses.
-- examples projecs
+- Usage [examples](hhttps://github.com/open-license-manager/examples) to simplify the integration in your project.
## How to build
Below an overview of the basic build procedure, you can find detailed instructions for [Linux](http://open-license-manager.github.io/licensecc/development/Build-the-library.html)
diff --git a/doc/api/public_api.rst b/doc/api/public_api.rst
index 803c1fb..df87cb7 100644
--- a/doc/api/public_api.rst
+++ b/doc/api/public_api.rst
@@ -20,3 +20,12 @@
***********************
.. doxygenfunction:: acquire_license
+
+.. doxygenstruct:: CallerInformations
+ :members:
+
+.. doxygenstruct:: LicenseLocation
+ :members:
+
+.. doxygenstruct:: LicenseInfo
+ :members:
\ No newline at end of file
diff --git a/doc/index.rst b/doc/index.rst
index f5fe6dd..5d89e3e 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -1,9 +1,9 @@
-#######################################
-C++ software protection with Licensecc
-#######################################
-Copy protect, restrict the usage of your C++ software with a license file.
+###########################################
+Licensecc: a C++ software license manager
+###########################################
+Copy protect, limit the usage of your C++ software with a license.
-|c11|_ |License|_ |unstable|_ |BuildStatus|_ |CodacyBadge|_ |codecov|_ |forum|_
+|c11|_ |License|_ |unstable|_ |TravisBuild|_ |GithubCI|_ |CodacyBadge|_ |codecov|_ |forum|_
.. |c11| image:: https://img.shields.io/badge/c%2B%2B-11-blue.svg
.. _c11: https://en.wikipedia.org/wiki/C%2B%2B#Standardization
@@ -11,34 +11,30 @@
.. _unstable: http://github.com/badges/stability-badges
.. |License| image:: https://img.shields.io/badge/License-BSD%203--Clause-blue.svg
.. _License: ttps://opensource.org/licenses/BSD-3-Clause
-.. |TravisBuild| image:: https://travis-ci.org/open-license-manager/open-license-manager.svg?branch=develop
-.. _TravisBuild: https://travis-ci.org/open-license-manager/open-license-manager
+.. |TravisBuild| image:: https://travis-ci.org/open-license-manager/licensecc.svg?branch=develop
+.. _TravisBuild: https://travis-ci.org/open-license-manager/licensecc
.. |GithubCI| image:: https://github.com/open-license-manager/licensecc/workflows/Github_CI/badge.svg
.. _GithubCI: https://github.com/open-license-manager/licensecc/actions
-.. |CodacyBadge| image:: https://api.codacy.com/project/badge/Grade/62d6e1bb22d648bd85b6f3bc344a545a
-.. _CodacyBadge: https://www.codacy.com/manual/gcontini/open-license-manager?utm_source=github.com&utm_medium=referral&utm_content=open-license-manager/open-license-manager&utm_campaign=Badge_Grade
-.. |codecov| image:: https://codecov.io/gh/open-license-manager/open-license-manager/branch/develop/graph/badge.svg
-.. _codecov: https://codecov.io/gh/open-license-manager/open-license-manager
-.. |issues| image:: https://img.shields.io/github/issues/open-license-manager/open-license-manager
-.. _issues: http://github.com/open-license-manager/open-license-manager/issues
+.. |CodacyBadge| image:: https://app.codacy.com/project/badge/Grade/81a1f6bc15014618934fc5fab4d3c206
+.. _CodacyBadge: https://www.codacy.com/gh/open-license-manager/licensecc/dashboard?utm_source=github.com&utm_medium=referral&utm_content=open-license-manager/licensecc&utm_campaign=Badge_Grade
+.. |codecov| image:: https://codecov.io/gh/open-license-manager/licensecc/branch/develop/graph/badge.svg
+.. _codecov: https://codecov.io/gh/open-license-manager/licensecc
+.. |issues| image:: https://img.shields.io/github/issues/licensecc/open-license-manager
+.. _issues: http://github.com/open-license-manager/licensecc/issues
.. |forum| image:: https://img.shields.io/badge/forum-licensecc-blue.svg?style=flat
.. _forum: https://groups.google.com/d/forum/licensecc
Protect the software you develop from unauthorized copies, limit the usage in time, to a specific set of
-machines, or prevent the usage in virtualized environments. It is an open source license management system that helps to keep your
-software closed |:smirk:| . Among the other features the most notable one is: if it runs on a "real hardware"
+machines, or prevent the usage in virtualized environments. `Licensecc` is an open source license management system
+that helps to keep your software closed |:smirk:| .
+Among the other features the most notable one is: if it runs on a "real hardware" (not a container/vm)
it can generate a signature of that hardware and report if the signature doesn't match, because for instance
-the software has been copied to another pc.
+the software has been copied to another place.
A comprehensive :ref:`list of features <analysis/features:Features>`, and their status is available in the project wiki.
If you're experiencing problems, or you just need informations you can't find here in the documentation,
please contact us on the `user forum <https://groups.google.com/forum/#!forum/licensecc>`_ (hosted on Google), we'll be happy to help.
-
-Notice
-****************
-We're in the process of renaming the repository from `open-license-manager` to `licensecc`.
-Please update your project references and github remotes. Some link on the website may be broken.
License (BSD)
**************
@@ -51,7 +47,7 @@
*******************
The software is made by 4 main sub-components:
-* ``licensecc`` : the C++ library with a C api (the part you have to integrate in your software) with minimal (or no) external dependencies.
+* ``licensecc`` : the C++ library with a C api (the part you have to integrate in your software) with minimal external dependencies. (github project `licensecc <https://github.com/open-license-manager/licensecc>`_ )
* ``lccinspector`` : a license debugger to be sent to the final customer to diagnose licensing problems or for calculating the hardware id before issuing the license.
* ``lccgen`` : a license generator (github project `lcc-license-generator`_ ) to initialize the library and generate the licenses.
* ``examples`` : usage samples (github project `examples <https://github.com/open-license-manager/examples>`_ ).
@@ -196,4 +192,8 @@
:caption: Miscellaneous:
other/*
-
+
+.. meta::
+ :description: open source license manager, copy protection library in C++.
+ :keywords: license manager, c++, open source, copy protection, hardware identifcation
+ :title: a
diff --git a/doc/usage/concepts.rst b/doc/usage/concepts.rst
new file mode 100644
index 0000000..55cef06
--- /dev/null
+++ b/doc/usage/concepts.rst
@@ -0,0 +1,83 @@
+###########################################
+Projects, features and versions
+###########################################
+
+Projects
+================
+
+Licensecc is a library to protect your software from unauthorized copies. It does so generating a private key
+to sign the licenses and a public key to verify the signatures. The public key is included in binary form in the
+compiled `licensecc-static-lib` library at compile time.
+
+Since we're open source the keys can't be generated once and committed to github, we need to generate them before the
+compilation of the library.
+
+A ``project`` in ``licensecc`` terms refers to a folder containing a private key, a public key and a file containing customizations.
+Licensecc source tree can host multiple projects simultaneously, but can compile only one project at once.
+
+Projects are stored by default in the ``licensecc\projects`` folder, though you can place them elsewhere.
+Below the structure that is automatically created for you at compile time: there is one project named 'DEFAULT' used to compile and run tests.
+
+::
+
+ projects
+ 鈹斺攢鈹� DEFAULT #(your project name)
+ 鈹溾攢鈹� include
+ 鈹偮犅� 鈹斺攢鈹� licensecc
+ 鈹偮犅� 鈹斺攢鈹� DEFAULT
+ 鈹偮犅� 鈹溾攢鈹� licensecc_properties.h
+ 鈹偮犅� 鈹斺攢鈹� public_key.h
+ 鈹溾攢鈹� licenses
+ 鈹偮犅� 鈹斺攢鈹� test.lic
+ 鈹斺攢鈹� private_key.rsa
+
+If you want to use or create a new project in the configure phase of cmake specify the parameter '-DLCC_PROJECT_NAME'.
+
+A `licensecc-project` corresponds to one executable it has to be licensed. So for instance suppose you have two executables "Foo" and "Bar"
+and you want to issue licenses separately (licenses of "Foo" incompatible with "Bar") you need to:
+
+* create two `licensecc-projects` eg. "FooLicensecc" and "BarLicensecc" (names are for example here, you can choose them as you like, remember they will appear in the license file).
+* for each project:
+ * configure, compile and install `licensecc`
+
+In "Foo" and "Bar" (your original software) be sure to locate and link the right version of `licensecc-static-lib`. Eg. in your "Foo" CmakeLists.txt:
+
+Copy ``Findlicensecc.cmake`` from examples project in your project ``./cmake/`` folder.
+Add the following lines to your ``CmakeLists.txt``
+
+.. code-block::
+
+ SET(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${CMAKE_CURRENT_SOURCE_DIR}/cmake/")
+ find_package(licensecc 2.0.0 REQUIRED COMPONENTS "FooLicensecc")
+
+
+Features
+================
+
+A licensed software can have multiple functions that can be enabled or disabled independently using license files.
+Each software function takes the name of `feature` in Licensecc.
+Each feature can (need to) be licensed separately, the licenses then are merged in one license file and sent to the customer.
+
+There are parameters in ``lccgen`` to produce a multi-feature license directly avoiding the manual merge:
+
+.. code-block::
+
+ lccgen license issue -f PROJECT_NAME,MY_AWESOME_FEATURE -o example.lic
+
+To verify a feature pass the feature name in the ``CallerInformations`` structure
+(see: :ref:`verify license <api/public_api:Verify a license>`):
+
+.. code-block:: c
+
+ CallerInformations callerInfo = {"\0", "MY_AWESOME_FEATURE"};
+ LCC_EVENT_TYPE result = acquire_license(&callerInfo, nullptr, &licenseInfo);
+
+For a working example see `program_features <https://github.com/open-license-manager/examples/program_features>`_ in
+examples project.
+
+Versions
+================
+
+.. TODO::
+
+ Versions are not yet implemented.
diff --git a/doc/usage/issue-licenses.md b/doc/usage/issue-licenses.md
index 47dcc23..83a7347 100644
--- a/doc/usage/issue-licenses.md
+++ b/doc/usage/issue-licenses.md
@@ -39,10 +39,10 @@
Once you have the hardware identifier you can issue the command:
```
-cd projects/DEFAULT #(or whatever your project name is)
+cd projects/DEFAULT #(or whatever your `lcc-project` is)
lcc license issue --client-signature XXXX-XXXX-XXXX -o licenses/{license-file-name}.lic
```
-usually this command is issued in the host machine where you compiled `licensecc`
+to create the license file (usually this command is issued in the host machine where you compiled `licensecc`).
## Full set of options
A good way to start exploring available options is the command: `lcc license issue --help`
diff --git a/doc/usage/multi-feature.rst b/doc/usage/multi-feature.rst
deleted file mode 100644
index 238d4a7..0000000
--- a/doc/usage/multi-feature.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-#########################################
-Multi-component software
-#########################################
-
diff --git a/include/licensecc/datatypes.h b/include/licensecc/datatypes.h
index 4f3717b..4bb4044 100644
--- a/include/licensecc/datatypes.h
+++ b/include/licensecc/datatypes.h
@@ -91,14 +91,18 @@
} LicenseLocation;
/**
- * Informations on the software requiring the license
+ * Informations about the software requesting the license verification (eg, software version, feature to verify).
*/
typedef struct {
- char version[LCC_API_VERSION_LENGTH + 1]; // software version in format xxxx[.xxxx.xxxx] //TODO
/**
- * Name of the feature you want to verify. If empty the default feature will be verified.
- * Every project has a default feature that is equal to the project name.
- * Every feature has a section in the license file:
+ * software version in format xxxx[.xxxx.xxxx]
+ * NOT IMPLEMENTED pass '\0'
+ */
+ char version[LCC_API_VERSION_LENGTH + 1];
+ /**
+ * Name of the feature you want to verify. If empty ('\0') the 'default' feature will be verified.
+ * (every project has a default feature that is equal to the project name).
+ * Every feature has a separate section in the license file:
* <pre>
* [feature_xx]
* sig=AAAA
@@ -106,8 +110,7 @@
* expiry-date=20201111
* </pre>
*/
- char feature_name[LCC_API_FEATURE_NAME_SIZE +
- 1]; // name of the feature you' (must correspond to the name in the license)
+ char feature_name[LCC_API_FEATURE_NAME_SIZE + 1];
/**
* this number passed in by the application must correspond to the magic number used when compiling the library.
* See cmake parameter -DLCC_PROJECT_MAGIC_NUM and licensecc_properties.h macro VERIFY_MAGIC
diff --git a/include/licensecc/licensecc.h b/include/licensecc/licensecc.h
index ae1d833..5632788 100644
--- a/include/licensecc/licensecc.h
+++ b/include/licensecc/licensecc.h
@@ -22,7 +22,7 @@
/**
* \brief Calculates the hardware identifier associated with a specific pc.
* \details
- * The software, when it doesn't find a valid license should show to the user the calculated identifier.
+ * The caller, when it doesn't find a valid license (see `acquire_license` below) should show to the user the calculated identifier.
* The user should report the pc_identifier to the software editor that will in turn use it to issue a license.
*
* pc_id_method = ::STRATEGY_DEFAULT is usually the best choice.
@@ -46,11 +46,12 @@
* This method is used to request the use of one license for a product.
* In case of local license it's used to check if the product is licensed.
*
- * @return ::LICENSE_OK(0) if successful. Other values if there are errors.
+ * @return LCC_EVENT_TYPE::LICENSE_OK(0) if successful. Other values if there are errors.
*
- * @param callerInformation[in]
- * a vendor defined string containing the name of the product we want to request.
- * @param licenseLocation[in] otpional, can be NULL.
+ * @param callerInformation[in] optional, can be NULL.
+ * contains informations on the software that is requesting the license verification. Let the software
+ * specify its version or request verification for features that need to be enabled separately.
+ * @param licenseLocation[in] optional, can be NULL.
* licenseLocation, either the name of the file
* or the name of the environment variable should be !='\0'
* @param license_out[out] optional, can be NULL, if set it will return extra informations about the license.
diff --git a/src/templates/licensecc_properties.h.in b/src/templates/licensecc_properties.h.in
index 1dd89e8..3bce633 100644
--- a/src/templates/licensecc_properties.h.in
+++ b/src/templates/licensecc_properties.h.in
@@ -88,6 +88,14 @@
* - If it detects the software is running in a virtual machine in the cloud it will use ::LCC_CLOUD_STRATEGIES
*/
STRATEGY_DEFAULT = -1,
+ /**
+ * \brief Uses mac address to generate hardware id.
+ *
+ * This strategy use the mac address of one of the network adapters to generate the hardware identifier.
+ * Network adapters are scored using their names, trying to avoid vpn adapters and virtual devices.
+ * Mac address should be unique in the subnetwork, so this strategy poses some limitation on the number of licenses
+ * that can be in use in the same subnet.
+ */
STRATEGY_ETHERNET = 0,
STRATEGY_IP_ADDRESS = 1,
STRATEGY_DISK = 2,
--
Gitblit v1.9.1