Skip to content
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

Clearer protection #3629

Open
wants to merge 8 commits into
base: master
Choose a base branch
from
Open

Clearer protection #3629

Changes from 4 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
e3c8950
Be consistent with example.
HansOlsson Dec 17, 2024
61f2106
Skip unneeded indentation.
HansOlsson Dec 17, 2024
92b7ef0
Remove incorrect referene.
HansOlsson Dec 17, 2024
a893150
Try to be clearer.
HansOlsson Dec 17, 2024
8f10764
Apply suggestions from code review
HansOlsson Jan 3, 2025
3aaa907
Default for dates.
HansOlsson Jan 3, 2025
c0ae911
Rename class a suggested.
HansOlsson Jan 3, 2025
2e1f703
Update chapters/annotations.tex
HansOlsson Jan 8, 2025
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
47 changes: 24 additions & 23 deletions chapters/annotations.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2318,14 +2318,15 @@ \subsection{Licensing}\label{licensing}
record Protection
/*literal*/ constant Access access;
/*literal*/ constant String features[:] "Required license features";

record License
/*literal*/ constant String libraryKey;
/*literal*/ constant String licenseFile = "" "Optional, default mapping if empty";
end License;
/*literal*/ constant IntLicense License;
HansOlsson marked this conversation as resolved.
Show resolved Hide resolved
end Protection;

record IntLicense "Internal class name, do not use"
Copy link
Collaborator

Choose a reason for hiding this comment

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

Wouldn't it look cleaner like this,

Suggested change
record IntLicense "Internal class name, do not use"
record IntLicense "Type of Protection.License"

or without any description at all?

Suggested change
record IntLicense "Internal class name, do not use"
record IntLicense

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

The problem is that we want to avoid two things:

  • Use of the class name, i.e., annotation(Protection(License=UserLicense(...
  • Having annotations of the form annotation(UserLicense(libraryKey=... (as if were a normal annotation-record).

To me just saying that the class name is internal seems the simplest way to achieve that.

An alternative to this description would be to have it as a separate segment and state that it is internal before that.

Copy link
Collaborator

Choose a reason for hiding this comment

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

I like the idea of avoiding nested record definitions.

/*literal*/ constant String libraryKey;
/*literal*/ constant String licenseFile = "" "Optional, default mapping if empty";
HansOlsson marked this conversation as resolved.
Show resolved Hide resolved
end IntLicense;
\end{lstlisting}
See \cref{protection-of-classes} for a description of \lstinline!access!, and note that licensing information uses another record \lstinline!Protection! with different contents given below.
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.
Expand All @@ -2350,26 +2351,26 @@ \subsection{Licensing}\label{licensing}

In order that the protected class can be used either a tool specific license manager, or a license file (called \lstinline!licenseFile!) must be present.
The license file is standardized.
It is a Modelica package without classes that has a \lstinline!Protection! annotation of the following form which specifies a sequence of target records, which makes it natural to define start/end dates for different sets of targets individually:
It is a Modelica package without classes that has a \lstinline!Authorization! annotation of the following form which specifies a sequence of target records, which makes it natural to define start/end dates for different sets of targets individually:
HansOlsson marked this conversation as resolved.
Show resolved Hide resolved
\begin{lstlisting}[language=modelica]
record Protection
record Authorization
/*literal*/ constant String licensor = "" "Optional string to show information about the licensor";
/*literal*/ constant String libraryKey "Matching the key in the class. Must be encrypted and not visible";
/*literal*/ constant License license[:] "Definition of the license options and of the access rights";
end Authorization;

record License
/*literal*/ constant String licensee = "" "Optional string to show information about the licensee";
/*literal*/ constant String id[:] "Unique machine identifications, e.g., MAC addresses";
/*literal*/ constant String features[:] "Activated library license features";
/*literal*/ constant String startDate = "" "Optional start date in UTCformat YYYY-MM-DD";
/*literal*/ constant String expirationDate = "" "Optional expiration date in UTCformat YYYY-MM-DD";
/*literal*/ constant String operations[:] "Library usage conditions";
end License;
end Protection;
record Authorization
/*literal*/ constant String licensor = "" "Optional string to show information about the licensor";
HansOlsson marked this conversation as resolved.
Show resolved Hide resolved
/*literal*/ constant String libraryKey "Matching the key in the class. Must be encrypted and not visible";
/*literal*/ constant License license[:] "Definition of the license options and of the access rights";
end Authorization;
\end{lstlisting}%
\index{Authorization@\robustinline{Authorization}!license file}\index{License@\robustinline{License}!license file}
using the following definition:
\begin{lstlisting}[language=modelica]
record License
/*literal*/ constant String licensee = "" "Optional string to show information about the licensee";
HansOlsson marked this conversation as resolved.
Show resolved Hide resolved
/*literal*/ constant String id[:] "Unique machine identifications, e.g., MAC addresses";
/*literal*/ constant String features[:] "Activated library license features";
/*literal*/ constant String startDate = "" "Optional start date in UTCformat YYYY-MM-DD";
HansOlsson marked this conversation as resolved.
Show resolved Hide resolved
/*literal*/ constant String expirationDate = "" "Optional expiration date in UTCformat YYYY-MM-DD";
HansOlsson marked this conversation as resolved.
Show resolved Hide resolved
/*literal*/ constant String operations[:] "Library usage conditions";
end License;
\end{lstlisting}
Copy link
Collaborator

Choose a reason for hiding this comment

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

Somewhere below here, the default behaviors should be explained:

Suggested change
\end{lstlisting}
\end{lstlisting}
If \lstinline!startDate! or \lstinline!expirationDate! are empty (the default), the license has no start day or expiration date, respectively.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Will add a reformulated version.


The format of the strings used for \lstinline!libraryKey! and \lstinline!id! are not specified (they are vendor specific).
The \lstinline!libraryKey! is a secret of the library developer.
Expand Down