Move parts of SEMLA.md to other files

Author: henrikt-ma

Diff for: RationaleMCP/0039/ReadMe.md

@@ -28,9 +28,10 @@ different platforms.
 
 ## Revisions
 
-| Date | Description |
-| --- | --- |
-| April 9 – May 4, 2021 | Hubertus Tummescheit, Henrik Tidefelt. 1<sup>st</sup> MCP version converted from Modelon internal documentation to MCP format |
+| Version/Date                   | Changes/Comments                                                                             | Author                                     |
+|--------------------------------|----------------------------------------------------------------------------------------------|--------------------------------------------|
+| 0.1, 2015                      | Initial version                                                                              | Jesper Mattsson                            |
+| 0.2, April 9<sup>th</sup> 2021 | Restructuring to separate out requirements and examples as appendices, minor wording updates | Hubertus Tummescheit                       |
 
 
 ## Contributor License Agreement
@@ -44,6 +45,8 @@ The [rationale](rationale.md) presents the rationale with use cases.
 
 The design, called _SEMLA_ is developed in a [separate document](SEMLA.md), for later incorporation as changesets for the Modelica Specification document.
 
+A [manifest.xml example](manifest-example.md) is also provided.
+
 
 ## Backwards Compatibility
 
@@ -81,6 +84,7 @@ implementation of this proposal.
 ## References
 
 - <https://www.openssl.org/>
+- TLS 1.2 official specification: <https://tools.ietf.org/html/rfc5246>
 - <https://github.com/modelon-community/SEMLA>
 - <https://openmodelica.org/doc/OpenModelicaUsersGuide/latest/encryption.html>
 - <https://www.modelon.com/leverage-standardized-encryption-and-licensing-for-modelica-libraries/>

Diff for: RationaleMCP/0039/SEMLA.md

@@ -1,12 +1,5 @@
 # SEMLA:<br/>Tool-independent Licensing and Code Encryption of Modelica Libraries
 
-## Revision history
-
-| Version | Changes/Comments                                                                             | Author/Date                                     |
-|---------|----------------------------------------------------------------------------------------------|-------------------------------------------------|
-| 0.1     | Initial version                                                                              | Jesper Mattsson, 2015                           |
-| 0.2     | Restructuring to separate out requirements and examples as appendices, minor wording updates | Hubertus Tummescheit, April 9<sup>th</sup> 2021 |
-
 This specification describes a container for distributing Modelica
 libraries and a protocol for how a Modelica tool should communicate with
 an executable for licensing and decryption of the library. The following
@@ -437,304 +430,3 @@ and fourth form below:
         decimal integer – must fit in a 32-bit signed integer
 
     -   &lt;data&gt; = the data, as raw bytes
-
-# References
-
-\[1\] TLS 1.2 official specification:
-<https://tools.ietf.org/html/rfc5246>
-
-# Appendix A: Example “manifest.xml” file
-
-This is an example of what the “manifest.xml” file could look like for
-an example encrypted library:
-
-&lt;?xml version=*"1.0"* encoding=*"utf-8"*?&gt;
-
-&lt;archive&gt;
-
-&lt;!-- All paths in the file are interpreted as relative to the
-directory of the top-level
-
-package (e.g., the path to this file would be ".library/manifest.xml"),
-and allows
-
-only forward slashes as directory separators. --&gt;
-
-&lt;manifest version=*"1.0"*/&gt;
-
-&lt;!-- The id attribute is the actual Modelica identifier of the
-library. The file attribute
-
-from SMA is no longer needed, as it will always be "package.mo" or
-"package.moc"
-
-(and the tool will need the logic of checking for both .mo and .moc
-anyway).
-
-The enabled attribute (optional, default value is true) indicates
-whether the library
-
-should be enabled/loaded by default. --&gt;
-
-&lt;library id=*"ExampleLib"* enabled=*"true"*&gt;
-
-&lt;!-- Official title of the library (optional) --&gt;
-
-&lt;title&gt;Example Encrypted Library&lt;/title&gt;
-
-&lt;!-- Description (optional) --&gt;
-
-&lt;description&gt;
-
-Dummy library showing directory structure for an encrypted library (with
-empty files)
-
-&lt;/description&gt;
-
-&lt;!-- The version of the library. Version information is formatted
-according to the
-
-Modelica language specification. The build and date attributes are
-optional. --&gt;
-
-&lt;version number=*"1.0"* build=*"1"* date=*"2013-08-04"*/&gt;
-
-&lt;!-- Version of the Modelica language that is used in this library.
---&gt;
-
-&lt;language version=*"3.2"* /&gt;
-
-&lt;!-- Copyright notice (optional)--&gt;
-
-&lt;copyright&gt;
-
-Copyright © 2014, Modelon AB.
-
-&lt;/copyright&gt;
-
-&lt;!-- License information (optional) --&gt;
-
-&lt;license&gt;
-
-Some license information.
-
-&lt;/license&gt;
-
-&lt;!-- Encryption/license check information (only for proprietary
-libraries).
-
-If this is present, then the library is encrypted. --&gt;
-
-&lt;encryption&gt;
-
-&lt;!-- Library vendor executable. May be repeated - one for each
-supported platform.
-
-path: the path to the executable
-
-platform: the OS/platform to use this executable on, must be unique
-among
-
-executable nodes
-
-licensing: if this executable handles licensing (optional, default is
-true)
-
-The executable shall be placed under the vendor-specific directory
-
-(i.e. .library/VENDORNAME/). The normal case is that licensing has the
-same
-
-value for each executable node, but it is allowed to have different
-values
-
-for different platforms. --&gt;
-
-&lt;executable path=*".library/Modelon/vendor.exe"* platform=*"win32"*
-licensing=*"true"* /&gt;
-
-&lt;executable path=*".library/Modelon/vendor32"* platform=*"linux32"*
-licensing=*"true"* /&gt;
-
-&lt;executable path=*".library/Modelon/vendor64"* platform=*"linux64"*
-licensing=*"true"* /&gt;
-
-&lt;/encryption&gt;
-
-&lt;!-- Icon for the library (PNG format) (optional) --&gt;
-
-&lt;icon file=*"Resources/Images/el.png"* /&gt;
-
-&lt;/library&gt;
-
-&lt;!-- Leaving out optional compatibility and dependencies in this
-example. --&gt;
-
-&lt;/archive&gt;
-
-# Appendix B: Discussion of Weaknesses
-
-There are several cryptographic keys involved. If someone were to
-extract a key from an executable or alter the executable to change the
-key, then that would have different consequences depending on what key
-it is:
-
--   The private key of the tool
-
-    -   Finding this key would allow decryption of all libraries that
-        trust that key. It would be possible to replace the key, but
-        that would require new releases (or at least new distributable)
-        of all libraries that trust that tool.
-
-    -   Altering this key would not be useful for an attacker.
-
--   The private key of the LVE
-
-    -   It might be possible to eavesdrop on the communication between
-        tool and LVE with this key. Requires additional study of chosen
-        crypto scheme to determine. With private key of tool as well, it
-        is definitely possible (but uninteresting if you have that key).
-
--   The session key
-
-    -   Generated for each communication session, but could be extracted
-        for a specific communication by debugging the tool or LVE.
-
-    -   Finding this would allow eavesdropping on the communication.
-
-    -   Altering this key is not possible.
-
--   List of public keys that the LVE trusts
-
-    -   Finding this list would not be useful for an attacker.
-
-    -   Altering this list would allow adding your own and thus allow
-        decryption of the library.
-
--   The key/keys used by the LVE to decrypt the library
-
-    -   Finding this key would allow decrypting the library.
-
-    -   Altering this key would not be useful for an attacker.
-
-Note that both the public/private key pair in the LVE and the key used
-to decrypt the library could be newly generated for each build of the
-library distributable.
-
-All of these keys should be protected with some sort of obfuscation of
-the object code to make them harder to extract. It would, however, be
-impossible to completely protect against such attacks.
-
-In conclusion, the most serious breach would be if an attacker obtained
-the private key of the tool, allowing decryption of any library released
-for that tool. The current situation is that the same vulnerability
-necessarily exists in any tool that supports encrypted libraries.
-
-Since Modelica tools need access to the Modelica source code by the
-nature of the language specification, theses weaknesses have been
-considered acceptable by all commercial parties that so far have made
-use of this feature. The weaknesses are identical to those of
-tool-specific encryption schemes.
-
-# Appendix C: Requirements considered for the design of SEMLA
-
-The following requirements for commercial libraries were considered in
-the design of this proposal:
-
-## Library Vendor
-
--   Library vendor needs to be able to define which libraries that
-    should be available on which tools, i.e. explicit encoding of
-    supported tools. *Yes, through list of trusted keys.*
-
-<!-- -->
-
--   Library vendor needs to be able to enable/disable parts (features)
-    in any given library based on standardized annotations. *Not
-    hindered, standard license annotations are used.*
-
--   Library vendor needs to be able to specify visibility of components
-    based on the standardized annotations. *Not hindered, standard
-    license annotations are used.*
-
--   The solution should offer a means to check the license for the
-    library as a whole without parsing the Modelica code. *Yes, optional
-    alternate licensing mechanism can be used for tools that do not
-    understand license annotations.*
-
--   Library vendor needs to be able to license/protect external
-    libraries written in e.g. C and Fortran 77 independently of the
-    licensing mechanism for the library. *Not affected by this
-    specification, such checks can be added to the external libraries
-    themselves.*
-
--   Library vendor needs to be able to make new releases of existing
-    libraries and release new libraries without any action from the tool
-    vendor. *Yes, when licensing is supplied by library vendor.*
-
--   Encryption mechanism shall be possible to use with or without the
-    licensing mechanism of the protocol. *Yes.*
-
--   Encryption mechanism shall ensure protection of library vendor IP.
-    (In this case, this is defined only as Modelica source code.) *In
-    part. It is not possible to fulfill this completely, since
-    everything necessary to decrypt the code must be available to the
-    client computer. Protection is also limited by what the tool does or
-    does not expose to the user. Extracting any IP that is not shown by
-    the tool requires using decompilation and/or debugging tools to
-    extract cryptographic keys from either the tool or the LVE (see
-    Weaknesses below). This is similar to the current situation.*
-
--   The solution shall be not be limited to a specific licensing
-    mechanism. *Yes, license mechanism is not specified. It is required
-    that feature names are used, but this is also assumed by the
-    description of licensing annotations in the Modelica language
-    specification.*
-
--   The protocol shall offer means to with reasonable effort replace
-    encryption keys, or equivalent, in cases of security breaches. *All
-    involved keys belonging to library vendors can be switched for any
-    library release. Changing the key pair used by the tool could be
-    done by adding a second key pair during a transition period. Library
-    vendors could then replace the compromised key with the new one in
-    their list of trusted tools. A tool may have more than one key pair.
-    For tools that have more than one key pair, the LVE needs to be
-    restarted in between trying different key pairs.*
-
-## Tool Vendor
-
--   A tool may store all files except Modelica source code on disc in
-    unencrypted form, e.g., in order to support linking with library
-    files during compilation. *Yes.*
-
--   The solution shall support standardized mechanisms for
-    enabling/disabling parts of a library, by means of annotations
-    defined in the Modelica specification. *Not hindered, standard
-    license annotations are used.*
-
--   Well documented low-level API for licensing and encryption for easy
-    integration in applications. *Documented above.*
-
--   Solution shall enable customizations and tailored functionality on
-    top of the low-level API. *API is fairly generic and uses
-    file-system model, this enables customizations through special files
-    or folders.*
-
--   Error messages must be supported by the API. *Yes, error messages
-    can be passed back to tool.*
-
--   Alternative, tool specific, licensing mechanisms shall not be
-    prevented by the API. *Yes, license checking is controlled by tool.*
-
--   It shall be possible to store/ship several libraries/top-level
-    packages in a single file. *Yes.*
-
-## User
-
--   The API shall enable convenient to installation procedures for
-    libraries. *Possible with tool support, library is distributed as a
-    single file with a well-defined file extension.*
-
--   Error messages should enable users and support personnel to isolate
-    errors related to licensing and encryption. *Yes, error messages can
-    be passed back to tool.*