Skip to content

Generalize modern table presentation with application to Protection #3770

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
henrikt-ma wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Generalize modern table presentation with application to Protection #3770

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
125 changes: 75 additions & 50 deletions chapters/annotations.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2333,7 +2333,21 @@ \subsection{Version Date and Build Information}\label{version-date-and-build-inf

\section{Access Control to Protect Intellectual Property}\label{annotations-for-access-control-to-protect-intellectual-property}\label{access-control-to-protect-intellectual-property}

This section presents annotations to define the protection and the licensing of packages.
The annotations listed below define the protection and licensing of packages.
They are all sub-annotations of the \fmtannotationindex{Protection} annotation.
\begin{center}
\begin{tabular}{l|l l}
\hline
\tablehead{Annotation} & \tablehead{Description} & \tablehead{Details}\\
\hline
\hline
{\lstinline!Protection.access!} & Access control for decrypted content & \Cref{modelica:Protection.access}\\
{\lstinline!Protection.features!} & Required license features & \Cref{modelica:Protection.features}\\
{\lstinline!Protection.License!} & User license file & \Cref{modelica:Protection.License}\\
\hline
\end{tabular}
\end{center}

The goal is to unify basic mechanisms to control the access to a package in order to protect the intellectual property contained in it.
This information is used to encrypt a package and bind it optionally to a particular target machine, and/or restrict the usage for a particular period of time.

Expand All @@ -2350,7 +2364,7 @@ \section{Access Control to Protect Intellectual Property}\label{annotations-for-
The following definitions relate to access control.

\begin{definition}[Protection]\index{protection!access control}
Define what parts of a class are visible.
Define which parts of a class that are visible.
\end{definition}

\begin{definition}[Obfuscation]\index{obfuscation!access control}
Expand All @@ -2366,29 +2380,39 @@ \section{Access Control to Protect Intellectual Property}\label{annotations-for-
Restrict the use of an encrypted package for particular users for a specified period of time.
\end{definition}

In this section annotations are defined for protection and licensing.
The \lstinline!Protection! annotation defines protection and licensing.
Obfuscation and encryption are not standardized.

Protection and licensing are both defined inside the \fmtannotationindex{Protection} annotation:
\begin{lstlisting}[language=modelica]
annotation(Protection($\ldots$));
\end{lstlisting}

\subsection{Protection of Classes}\label{protection-of-classes}

A class may have the following annotations to define what parts of a class are visible, and only the parts explicitly listed as visible below can be accessed (if a class is encrypted and no \lstinline!Protection! annotation is defined, the access annotation has the default value \lstinline!Access.documentation!):
\begin{lstlisting}[language=modelica]
record Protection
/*literal*/ constant Access access;
$\ldots$
end Protection;
type Access = enumeration(hide, icon, documentation, diagram,
This section describes the part of the \lstinline!Protection! annotation used to define protection.

\begin{annotationdefinition*}[access]\label{modelica:Protection.access}\annotationindex{access}\index{Protection@\robustinline{Protection}!\robustinline{access} sub-annotation}
\begin{synopsis}\begin{lstlisting}
/*literal*/ constant Access Protection.access;
Copy link
Collaborator

@HansOlsson HansOlsson Nov 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/*literal*/ constant Access Protection.access;
/*literal*/ constant Access access;

Making it consistent with the other ones.

Copy link
Collaborator Author

@henrikt-ma henrikt-ma Nov 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are right that the PR is currently inconsistent and that this needs to be fixed.

However, I am not sure it's such a good idea to present the sub-annotations in the same way as the annotations residing directly under annotation(…).

Copy link
Collaborator

@HansOlsson HansOlsson Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, many sub-annotations are defined as part of a record https://specification.modelica.org/master/annotations.html#annotations-for-documentation https://specification.modelica.org/master/annotations.html#annotations-for-figures https://specification.modelica.org/master/annotations.html#modelica:Dialog

So, the alternative would be to have "record Protection" preceding this declaration as in the current specification, but it would seem odd with just one element, and normally the entry would then be called "Protection".

Copy link
Collaborator Author

@henrikt-ma henrikt-ma Dec 1, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see some similarities with those examples, but as you already noted they are not quite the same:

  • The Documentation is not a sub-annotation, so it could be converted to the new style if we really wanted to. However, there is not that much to say about Documentation as a whole, so it makes sense to me that we don't present it in the same way as an annotation which we are able to cover in more detail without only referring to other sections.
  • The Figure is a type and not the name of an annotation, so it looks correct to me that we don't present it as an annotation by itself, and that we don't include it in any summary table. However, if there was a way to present Documentation.figures as a sub-annotation, it would have been nice to do so at the top of https://specification.modelica.org/master/annotations.html#annotations-for-figures, something like this:
Figure[:] Documentation.figures;

record Figure
  /*literal*/ constant String title = "" "Title meant for display";
  /*literal*/ constant String identifier = "" "Identifier meant for programmatic access";
  /*literal*/ constant String group = "" "Name of figure group";
  /*literal*/ constant Boolean preferred = false "Automatically display figure after simulation";
  Plot[:] plots "Plots";
  /*literal*/ constant String caption = "" "Figure caption";
end Figure;
  • I find the Dialog properly presented already. With loadSelector and friends being described together with the rest of Dialog, I don't see a need to change anything regarding them. (Having separate annotation definitions for Dialog.loadSelector etc would just look odd to me since they are such an integral part of Dialog.)

Copy link
Collaborator

@HansOlsson HansOlsson Dec 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, one thing to consider is that not only is it different, it also breaks the idea that the annotations are described by legal Modelica code.

E.g., we use /*literal*/ to avoid having a special keyword, whereas Protection.access is not a valid name for a component - and the most obvious way of handling it: 'Protection.access' would just create more confusion.

So, having record Protection in front of may seem a bit excessive, but at least we have some precedence and it is legal Modelica.

Copy link
Collaborator Author

@henrikt-ma henrikt-ma Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The problems I see with record Protection are:

  • It no longer fits nicely on a line.
  • We need to indicate that this is just one out of several members of the record.

I mean, this becomes a very cumbersome way to say that the access member a Protection is a /*literal*/ constant Access:

record Protection
  /*literal*/ constant Access access;
  $\ldots$
end Protection;

While I would still much prefer the non-valid Modelica Protection.access notation, one could also consider some sort of class modification notation:

Protection(/*literal*/ constant Access access);

Copy link
Collaborator

@HansOlsson HansOlsson Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, the text already has a link to the rest of the contents of Protection, and master already has the

record Protection
  /*literal*/ constant Access access;
  $\ldots$
end Protection;

So, why not keep it for now?

Copy link
Collaborator

@HansOlsson HansOlsson Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Various variants were considered, including having Protection in the text and having the full Protection-annotation followed by simplified form.

Open a new issue for resolving this.


type Access =
enumeration(hide, icon, documentation, diagram,
nonPackageText, nonPackageDuplicate,
packageText, packageDuplicate);
\end{lstlisting}
The other members of this record are given in \cref{licensing}.
\end{lstlisting}\end{synopsis}
\begin{semantics}
Allowed for class annotations.
The \lstinline!access! annotation defines which parts of a class that are visible.
If a class is encrypted and no \lstinline!Protection! annotation is provided, the default is \lstinline!Access.documentation!.

The \lstinline!access! annotation holds for the respective class and all classes that are hierarchically on a lower level, unless overridden by a \lstinline!Protection! annotation with \lstinline!access!.
Overriding \lstinline!access=Access.hide! or \lstinline!access=Access.packageDuplicate! has no effect.

\begin{example}
If the annotation is given on the top level of a package and at no other class in this package, then the \lstinline!access! annotation holds for all classes in this package.
\end{example}

The items of the \fmtannotationindex{Access} enumeration have the following meanings:
Classes should not use other classes in ways that contradict this protection.
Tools must ensure that protected contents are not shown, even if classes do not meet this requirement.

The items of the \fmtannotationindex{Access} enumeration have the following meanings (only parts explicitly listed as visible below can be accessed):
\begin{enumerate}
\item
\lstinline!Access.hide!\\
Expand Down Expand Up @@ -2418,19 +2442,11 @@ \subsection{Protection of Classes}\label{protection-of-classes}
\lstinline!Access.packageDuplicate!\\
Same as \lstinline!Access.packageText! and additionally the class, or part of the class, can be copied.
\end{enumerate}

The \lstinline!access! annotation holds for the respective class and all classes that are hierarchically on a lower level, unless overridden by a \lstinline!Protection! annotation with \lstinline!access!.
Overriding \lstinline!access=Access.hide! or \lstinline!access=Access.packageDuplicate! has no effect.

\begin{example}
If the annotation is given on the top level of a package and at no other class in this package, then the \lstinline!access! annotation holds for all classes in this package.
\end{example}

Classes should not use other classes in ways that contradict this protection.
Tools must ensure that protected contents are not shown, even if classes do not meet this requirement.
\end{semantics}
\end{annotationdefinition*}

\begin{example}
For instance a class with \lstinline!Access.hide! should not be used in the diagram layer of a class with \lstinline!Access.diagram!, and there should not be hyperlinks to classes with \lstinline!Access.icon! (from classes with visible documentation).
For instance, a class with \lstinline!Access.hide! should not be used in the diagram layer of a class with \lstinline!Access.diagram!, and there should not be hyperlinks to classes with \lstinline!Access.icon! (from classes with visible documentation).

Consider the following invalid use of a class with \lstinline!Access.hide!:
\begin{lstlisting}[language=modelica]
Expand Down Expand Up @@ -2526,30 +2542,20 @@ \subsection{Protection of Classes}\label{protection-of-classes}
\end{lstlisting}
\end{nonnormative}

\subsection{Licensing}\label{licensing}

In this section annotations within the \lstinline!Protection! annotation are defined to restrict the usage of the encrypted package:
\begin{lstlisting}[language=modelica]
record Protection
/*literal*/ constant Access access;
/*literal*/ constant String features[:] "Required license features";
/*literal*/ constant UserLicense License;
end Protection;
\subsection{Licensing}\label{licensing}

record UserLicense "Internal class name, do not use"
/*literal*/ constant String libraryKey;
/*literal*/ constant String licenseFile = "" "Default mapping if empty";
end UserLicense;
\end{lstlisting}
See \cref{protection-of-classes} for a description of \lstinline!access!.
The \fmtannotationindex{License} annotation has only an effect on the top of an encrypted class and is then valid for the whole class hierarchy.
(Usually the licensed class is a package.)
The \lstinline!libraryKey! is a secret string from the library vendor and is the protection mechanism so that a user cannot generate his/her own authorization file since the \lstinline!libraryKey! is unknown to him/her.
This section describes the part of the \lstinline!Protection! annotation used to define licensing.

\begin{annotationdefinition*}[features]\label{modelica:Protection.features}\annotationindex{features}\index{Protection@\robustinline{Protection}!\robustinline{features} sub-annotation}
\begin{synopsis}\begin{lstlisting}
/*literal*/ constant String features[:];
\end{lstlisting}\end{synopsis}
\begin{semantics}
The \lstinline!features! annotation defines the required license options.
If the features vector in the library has one or more elements, then at least a license feature according to one of the elements must be present in the authorization file.
If the features vector in the library is empty or not provided there is no need for a license feature in the authorization file.
As with the other annotations, the \lstinline!features! annotation holds for the respective class and for all classes that are hierarchically on a lower level, unless further restricted by a corresponding annotation.
If the \lstinline!features! array in the library has one or more elements, then at least a license feature according to one of the elements must be present in the authorization file.
If the \lstinline!features! array in the library is empty or not provided there is no need for a license feature in the authorization file.
Similar to the \lstinline!access! annotation, the \lstinline!features! annotation holds for the respective class and for all classes that are hierarchically on a lower level, unless further restricted by a corresponding annotation.
If no license according to the \lstinline!features! annotation is provided in the authorization file, the corresponding classes are not visible and cannot be used, not even internally in the package.

\begin{example}
Expand All @@ -2568,6 +2574,23 @@ \subsection{Licensing}\label{licensing}
));
\end{lstlisting}
\end{example}
\end{semantics}
\end{annotationdefinition*}

\begin{annotationdefinition*}[License]\label{modelica:Protection.License}\annotationindex{License}\index{Protection@\robustinline{Protection}!\robustinline{License} sub-annotation}
\begin{synopsis}\begin{lstlisting}
/*literal*/ constant UserLicense License;

record UserLicense "Internal class name, do not use"
/*literal*/ constant String libraryKey;
/*literal*/ constant String licenseFile = "" "Default mapping if empty";
end UserLicense;
\end{lstlisting}\end{synopsis}
\begin{semantics}
The \fmtannotationindex{License} annotation only has an effect at the top of an encrypted class and is then valid for the whole class hierarchy.
(Usually the licensed class is a package.)

The \lstinline!libraryKey! is a secret string from the library vendor and is the protection mechanism so that a user cannot generate his/her own authorization file since the \lstinline!libraryKey! is unknown to him/her.

In order that the protected class can be used either a tool specific license manager, or an authorization file (called \lstinline!licenseFile!) must be present.
The authorization file is standardized.
Expand Down Expand Up @@ -2617,10 +2640,12 @@ \subsection{Licensing}\label{licensing}
To protect the \lstinline!libraryKey! and the target definitions, the authorization file must be encrypted and must never show the \lstinline!libraryKey!.

\begin{nonnormative}
All other information, especially licensor and license should be visible, in order that the user can get information about the license.
All other information, especially \lstinline!licensor! and \lstinline!license! should be visible, in order that the user can get information about the license.
It is useful to include the name of the tool in the authorization file name with which it was encrypted.
Note, it is not useful to store this information in the annotation, because only the tool that encrypted the \lstinline!Authorization! package can also decrypt it.
Note that it is not useful to store this information in the annotation, because only the tool that encrypted the \lstinline!Authorization! package can also decrypt it.
\end{nonnormative}
\end{semantics}
\end{annotationdefinition*}

\begin{example}
(Before encryption:)
Expand Down