diff --git a/5.0 Draft/SysD/Authorization/arrowhead.cls b/5.0 Draft/SysD/Authorization/arrowhead.cls new file mode 100644 index 0000000..107e691 --- /dev/null +++ b/5.0 Draft/SysD/Authorization/arrowhead.cls @@ -0,0 +1,225 @@ +% Copyright (c) 2021-08-19 Eclipse Arrowhead Project +% +% This program and the accompanying materials are made available under the +% terms of the Eclipse Public License 2.0 which is available at +% http://www.eclipse.org/legal/epl-2.0. +% +% SPDX-License-Identifier: EPL-2.0 + +% Arrowhead LaTeX Template (arrowhead.cls) +% +% A LaTeX document class for Arrowhead documentation. +% +% See example.tex for an example of how to use this class. + +\def\fileversion{1.2.1} +\def\filedate{2021/08/19} +\NeedsTeXFormat{LaTeX2e} + +\ProvidesClass{arrowhead}[\filedate\space Version \fileversion\space] +\LoadClass{article} + +\RequirePackage{xparse} +\RequirePackage{couriers} +\RequirePackage{ifthen} +\RequirePackage[hmargin=2cm,top=4cm,headheight=4cm,bottom=2.4cm,footskip=0.4cm]{geometry} +\RequirePackage{fancyhdr} +\RequirePackage{helvet} +\RequirePackage{lastpage} +\RequirePackage{listings} +\RequirePackage{microtype} +\RequirePackage[pdftex]{graphicx} +\RequirePackage{tabularx} +\RequirePackage[font={small}]{caption} +\RequirePackage[hidelinks]{hyperref} +\RequirePackage[nottoc,numbib]{tocbibind} +\RequirePackage[table]{xcolor} + +\definecolor{ArrowheadBlue}{HTML}{006F99} +\definecolor{ArrowheadGrey}{HTML}{333333} +\definecolor{ArrowheadOrange}{HTML}{D77734} +\definecolor{ArrowheadPurple}{HTML}{8F3165} +\definecolor{ArrowheadTeal}{HTML}{21A28F} +\definecolor{ArrowheadYellow}{HTML}{F6E14E} + +\DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} + +\captionsetup{width=0.94\textwidth} + +\ProcessOptions\relax + +\NewDocumentCommand{\ArrowheadTitle}{m}{\newcommand{\arrowtitle}{#1}} +\NewDocumentCommand{\ArrowheadServiceID}{m}{\newcommand{\arrowid}{#1}} +\NewDocumentCommand{\ArrowheadType}{m}{\newcommand{\arrowtype}{#1}} +\NewDocumentCommand{\ArrowheadTypeShort}{m}{\newcommand{\arrowtypeshort}{#1}} +\NewDocumentCommand{\ArrowheadVersion}{m}{\newcommand{\arrowversion}{#1}} +\NewDocumentCommand{\ArrowheadDate}{m}{\newcommand{\arrowdate}{#1}} +\NewDocumentCommand{\ArrowheadAuthor}{m}{\newcommand{\arrowauthor}{#1}} +\NewDocumentCommand{\ArrowheadStatus}{m}{\newcommand{\arrowstatus}{#1}} +\NewDocumentCommand{\ArrowheadContact}{m}{\newcommand{\arrowcontact}{#1}} +\NewDocumentCommand{\ArrowheadFooter}{m}{\newcommand{\arrowfooter}{#1}} +\NewDocumentCommand{\ArrowheadSetup}{}{ + \hypersetup{ + pdftitle={\arrowtitle\ -- \ \arrowtypeshort}, + pdfauthor={\arrowauthor\ <\arrowcontact>} + } +} +\NewDocumentCommand{\ArrowheadBox}{mm}{ + { + \vspace*{1.5\baselineskip} + \setlength{\tabcolsep}{0pt} + \renewcommand*{\arraystretch}{0} + \noindent + \begin{tabularx}{\dimexpr\textwidth-1pt-2.75ex\relax}{ + @{\textcolor[RGB]{0,72,117}{\vrule width 1pt}} + @{\hspace{2.75ex}} + X + } + \small{\textcolor[RGB]{0,72,117}{\textbf{#1}} #2} + \end{tabularx} + } +} + +\makeatletter + +\let\origsubsubsection\subsubsection +\renewcommand\subsubsection{\@ifstar{\starsubsubsection}{\nostarsubsubsection}} +\newcommand\starsubsubsection[1]{\vspace*{-0.5ex}\origsubsubsection*{#1}\vspace*{-0.75ex}} +\newcommand\nostarsubsubsection[1]{\vspace*{-0.5ex}\origsubsubsection{#1}\vspace*{-0.75ex}} + +\renewcommand\tiny{\@setfontsize\tiny{6}{7}} +\renewenvironment{abstract}{% + \begin{flushleft} + {\large \textbf{\abstractname}}\\ + \normalsize +}{% + \end{flushleft} +} + +\makeatother + +\addtocontents{toc}{\protect\setcounter{tocdepth}{2}} + +\setlength\tabcolsep{1mm} +\renewcommand\arraystretch{1.3} +\renewcommand{\familydefault}{\sfdefault} + +\renewcommand*{\headrulewidth}{0pt} +\pagestyle{fancy} + +\newcounter{Table} +\renewcommand\theTable{\arabic{Table}} + +\fancyhf{} +%% Page Header +\lhead{ + \raisebox{-0.5\height}{\includegraphics[height=2.33cm]{figures/arrowhead_logo}} +} +\rhead{% + \renewcommand{\arraystretch}{0.75}% + \begin{tabular}{p{8.67cm} p{3.33cm}} + \ifthenelse{\value{page}=1}{% + % First Page Header + \tiny{Document title} & \tiny{Document type} \\ + \footnotesize{\textbf{\arrowtitle}} & \footnotesize{\textbf{\arrowtypeshort}} \\ + \tiny{Date} & \tiny{Version} \\ + \footnotesize{\textbf{\arrowdate}} & \footnotesize{\textbf{\arrowversion}} \\ + \tiny{Author} & \tiny{Status} \\ + \footnotesize{\textbf{\arrowauthor}} & \footnotesize{\textbf{\arrowstatus}} \\ + \tiny{Contact} & \tiny{Page} \\ + \footnotesize{\textbf{\arrowcontact}} & \footnotesize{\textbf{\thepage \ (\pageref{LastPage})}} + }{% + % Standard Page Header + \tiny{Document title} & \tiny{Version} \\ + \footnotesize{\textbf{\arrowtitle}} & \footnotesize{\textbf{\arrowversion}} \\ + \tiny{Date} & \tiny{Status} \\ + \footnotesize{\textbf{\arrowdate}} & \footnotesize{\textbf{\arrowstatus}} \\ + & \tiny{Page} \\ + & \footnotesize{\textbf{\thepage \ (\pageref{LastPage})}} + } + \end{tabular}% +} +%% + +%% Page Footer +\lfoot{ + \rule[1pt]{\textwidth}{0.5pt} + \scriptsize + \arrowfooter +} +%% + +%% Syntax Highlighting + +% If you need more syntaxes than these, please add them to this document and +% contribute your additions to the Eclipse Arrowhead project. + +%%% HTTP + +\lstdefinelanguage{HTTP}{ + morekeywords={CONNECT,DELETE,GET,HEAD,OPTIONS,PUT,POST,PATCH,HTTP,HTTPS}, + sensitive=false, + morecomment=[l]{//}, + morecomment=[s]{/*}{*/}, % s is for start and end delimiter + morestring=[b]" +} + +\lstset{% + language=HTTP, + backgroundcolor=\color{white}, + basicstyle=\ttfamily\bfseries\footnotesize\color{ArrowheadGrey}, + breakatwhitespace=false, + breaklines=true, + captionpos=b, + commentstyle=\mdseries, + extendedchars=true, + frame=single, + keepspaces=true, + keywordstyle=\color{ArrowheadBlue}, + numbers=left, + numbersep=1em, + numberstyle=\tiny\color{ArrowheadGrey}, + rulecolor=\color{gray!33}, + showspaces=false, + showstringspaces=false, + showtabs=false, + stringstyle=\color{ArrowheadPurple}, + tabsize=4, + aboveskip=3ex, + belowskip=2ex, +} + +%%% ABNF + +\lstdefinelanguage{ABNF}{ + otherkeywords={=,/}, + morekeywords={alpha,digit}, + sensitive=false, + morecomment=[l]{;}, + morestring=[b]" +} + +\lstset{% + language=ABNF, + backgroundcolor=\color{white}, + basicstyle=\ttfamily\bfseries\footnotesize\color{ArrowheadGrey}, + breakatwhitespace=false, + breaklines=true, + captionpos=b, + commentstyle=\mdseries, + extendedchars=true, + frame=single, + keepspaces=true, + keywordstyle=\color{ArrowheadBlue}, + numbers=left, + numbersep=1em, + numberstyle=\tiny\color{ArrowheadGrey}, + rulecolor=\color{gray!33}, + showspaces=false, + showstringspaces=false, + showtabs=false, + stringstyle=\color{ArrowheadPurple}, + tabsize=4, + aboveskip=3ex, + belowskip=2ex, +} \ No newline at end of file diff --git a/5.0 Draft/SysD/Authorization/authorization_sysd.pdf b/5.0 Draft/SysD/Authorization/authorization_sysd.pdf new file mode 100644 index 0000000..6a34371 Binary files /dev/null and b/5.0 Draft/SysD/Authorization/authorization_sysd.pdf differ diff --git a/5.0 Draft/SysD/Authorization/authorization_sysd.tex b/5.0 Draft/SysD/Authorization/authorization_sysd.tex new file mode 100644 index 0000000..22dc2ad --- /dev/null +++ b/5.0 Draft/SysD/Authorization/authorization_sysd.tex @@ -0,0 +1,240 @@ +\documentclass[a4paper]{arrowhead} + +\usepackage[yyyymmdd]{datetime} +\usepackage{etoolbox} +\usepackage[utf8]{inputenc} +\usepackage{multirow} +\usepackage{hyperref} + +\renewcommand{\dateseparator}{-} + +\setlength{\parskip}{1em} + +%% Special references +\newcommand{\fref}[1]{{\textcolor{ArrowheadBlue}{\hyperref[sec:functions:#1]{#1}}}} +\newcommand{\mref}[1]{{\textcolor{ArrowheadPurple}{\hyperref[sec:model:#1]{#1}}}} +\newcommand{\pdef}[1]{{\textcolor{ArrowheadGrey}{#1\label{sec:model:primitives:#1}\label{sec:model:primitives:#1s}\label{sec:model:primitives:#1es}}}} +\newcommand{\pref}[1]{{\textcolor{ArrowheadGrey}{\hyperref[sec:model:primitives:#1]{#1}}}} + +\newrobustcmd\fsubsection[3]{ + \addtocounter{subsection}{1} + \addcontentsline{toc}{subsection}{\protect\numberline{\thesubsection}function \textcolor{ArrowheadBlue}{#1}} + \renewcommand*{\do}[1]{\rref{##1},\ } + \subsection*{ + \thesubsection\quad + operation + \textcolor{ArrowheadBlue}{#1} + (\notblank{#2}{\mref{#2}}{}) + \notblank{#3}{: \mref{#3}}{} + } + \label{sec:functions:#1} +} +\newrobustcmd\msubsection[2]{ + \addtocounter{subsection}{1} + \addcontentsline{toc}{subsection}{\protect\numberline{\thesubsection}#1 \textcolor{ArrowheadPurple}{#2}} + \subsection*{\thesubsection\quad#1 \textcolor{ArrowheadPurple}{#2}} + \label{sec:model:#2} \label{sec:model:#2s} \label{sec:model:#2es} +} + +\begin{document} + +%% Arrowhead Document Properties +\ArrowheadTitle{Authorization Core System} +\ArrowheadType{System Description} +\ArrowheadTypeShort{SysD} +\ArrowheadVersion{5.0.0} +\ArrowheadDate{\today} +\ArrowheadAuthor{Rajmund Bocsi} +\ArrowheadStatus{DRAFT} +\ArrowheadContact{rbocsi@aitia.ai} +\ArrowheadFooter{\href{www.arrowhead.eu}{www.arrowhead.eu}} +\ArrowheadSetup +%% + +%% Front Page +\begin{center} + \vspace*{1cm} + \huge{\arrowtitle} + + \vspace*{0.2cm} + \LARGE{\arrowtype} + \vspace*{1cm} + + %\Large{Service ID: \textit{"\arrowid"}} + \vspace*{\fill} + + % Front Page Image + %\includegraphics{figures/TODO} + + \vspace*{1cm} + \vspace*{\fill} + + % Front Page Abstract + \begin{abstract} + This document provides system description for the \textbf{Authorization Core System}. + \end{abstract} + + \vspace*{1cm} + + \end{center} + +\newpage +%% + +%% Table of Contents +\tableofcontents +\newpage +%% + +\section{Overview} +\label{sec:overview} +\color{black} +This document describes the Authorization core system, which exists to manage and to authorize +connection between various systems using authorization rules within an Eclipse Arrowhead Local Cloud (LC). It also provides token generation functionalities that adds an extra layer of security. + +The rest of this document is organized as follows. +In Section \ref{sec:prior_art}, we reference major prior art capabilities +of the system. +In Section \ref{sec:use}, we describe the intended usage of the system. +In Section \ref{sec:properties}, we describe fundamental properties +provided by the system. +In Section \ref{sec:delimitations}, we describe delimitations of capabilities +of the system. +In Section \ref{sec:services}, we describe the abstract services produced by the system. +In Section \ref{sec:security}, we describe the security capabilities +of the system. + +\subsection{Significant Prior Art} +\label{sec:prior_art} + +The strong development on cloud technology and various requirements for digitisation and automation has led to the concept of Local Clouds (LC). + +\textit{"The concept takes the view that specific geographically local automation tasks should be encapsulated and protected."} \cite{jerker2017localclouds} + +One of the main building blocks when realizing such Local Cloud is the capability of authorization and session control within the given LC. + +The previous versions of Authorization (4.6.x) are very similar to this version, however there are some key differences, even on conceptual level: + +\begin{itemize} + \item There was only peer-to-peer authorization rules supported: (system to system's service, or cloud to system in case of inter-cloud rules). The current version allows much more flexible rules. + \item Systems (or any system of an other cloud) could get a permission to use a specific system's specific service instance with a specific interface. The current version discards the interface restrictions, but allows rules for a specific operation of a service instance, or all operations of a service instance, or event type (on systems that publish such events). + \item You could only create an authorization rule if all related entities (consumer system or cloud, provider system, service definition and interface) are already existed (in the Service Registry's data storage). The current version supports rules referencing non-existent entities for future usage. + \item Only an administrator were able to add and remove rules. The current version allows providers to set their own rules. + \item Token generation used tokens that stores authorization information inside the token. These tokens could be checked without the Authorization core system (except a one-time request to acquire the public key of the Authorization system), but made provider implementation a little more difficult. The current version uses simpler tokens and provide a service operation to validate those tokens. + \item X.509 certificate trust chains was used as authentication mechanism. The current version can support any type of authentication methods by communication with a dedicated Authentication Provider core system. +\end{itemize} + +\subsection{How This System Is Meant to Be Used} +\label{sec:use} + +Authorization is a recommended core system of Eclipse Arrowhead LC and is responsible for the fundamental authorization control functionality by storing applicable authorization rules. An intra-cloud rule describes an access policy between a group of consumer systems and a provider system for a given service, service operation or event type, while an inter-cloud rule describes an access policy between a provider system and a group of neighbor clouds. + +This core system is also responsible for providing the session control functionality which is achieved by offering a token generation and a token validation service operation. + +\subsection{System functionalities and properties} +\label{sec:properties} + +\subsubsection {Functional properties of the system} + +Authorization solves the following needs to fulfill the requirements of authorization and session control. + +\begin{itemize} + \item Enables the providers to create and remove authorization rules about its services, service operations or published events. + \item Enables the providers to validate that a consumer can use a specific service operation. + \item Enables the core/support systems to validate a consumer can use a specific provider's specific service. + \item Enables the core/support systems (e.g. the Event Handler) to validate that a subscriber can receive a specific publisher's event with a specific type. + \item Enables the providers to validate an authorization token. + \item Enables the application/core/support systems to generate tokens for a consumer-provider-service triplet (if all service operation is accessible for a consumer) or a consumer-provider-service-operation quadruple. + A token can't be generated if there is no appropriate authorization rule that allows for the consumer to use the specific provider's specific service operation (or all operation of a specific service). +\end{itemize} + +Authorization allows to specify the following kinds of rules: + +\begin{itemize} + \item A service/service operation/event with a specific type is accessible to anyone within the local cloud. + \item A service/service operation/event with a specific type is accessible to anyone within the local cloud, except a list of consumers (blacklist). + \item A service/service operation/event with a specific type is accessible to anyone within the local cloud whose names appear on a given list (whitelist). A peer-to-peer rule can be specified if this list only contains one consumer. + \item A service/service operation/event with a specific type is accessible to anyone within the local cloud who meet specified meta data requirements. + \item A service/service operation is accessible to anyone from a given neighbor cloud list (inter-cloud whitelist). +\end{itemize} + +\subsubsection {Non functional properties of the system} +If an Authentication Provider (AP) is present in the Local Cloud, the Authorization will use AP's service(s) to verify a requester system before responding to its request. + +\subsubsection {Data stored by the system} +In order to achieve the mentioned functionalities, Authorization is capable to store the following information set: + +\begin{itemize} + \item \textbf{Authorization rules}: the system stores all previously mentioned kinds of permissions. + \item \textbf{Authorization tokens}: the system stores generated authorization tokens with related data, such as consumer name, provider name, service definition name, optional service operation, expiration date. Expired tokens can be automatically removed from the data storage. +\end{itemize} + +\subsection{Important Delimitations} +\label{sec:delimitations} + +\begin{itemize} + \item If the Local Cloud does not contain a Authentication Provider, there is no way for the Authorization to verify the requester system. In that case, the Authorization will consider the authentication data comes from the requester as valid. + \item If the Local Cloud does not contain a Service Registry, then rules with system meta data requirements are not supported. +\end{itemize} + +\newpage + +\section{Services produced} +\label{sec:services} + +\msubsection{service}{authorization} +The purpose of this service is to validate service consumption permissions and to grant and revoke those permissions. + +\msubsection{service}{authorization-token} +The purpose of this service is to generate and validate authorization tokens. + +\msubsection{service}{authorization-management} +Its main purpose is to manage authorization rules and validate service consumption permissions in bulk. It also provides querying functionalities for authorization rules and tokens. The service is offered for core and administrative support systems. + +\msubsection{service}{monitor} +Recommended service. Its purpose is to give information about the provider system. The service is offered for both application and core/support systems. + +\newpage + +\section{Security} +\label{sec:security} + +For authentication, the Authorization utilizes an other core system, the Authentication Provider's service to verify the identities of the requester systems. If no Authentication Provider is deployed into the Local Cloud, the Authorization trusts the requester system self-provided identity. + +For authorization, the system uses its own data storage. The following service operations can be used without any authorization rules: + +\begin{itemize} + \item \textit{authorization} service's \textit{validate-consumer} operation, + \item \textit{authorization} service's \textit{grant} operation, + \item \textit{authorization} service's \textit{revoke} operation, + \item \textit{authorization-token} service's \textit{validate-token} operation. +\end{itemize} + +The implementation of the Authorization can decide about the encryption of the connection between the Authorization and other systems. + +\newpage + +\bibliographystyle{IEEEtran} +\bibliography{bibliography} + +\newpage + +\section{Revision History} +\subsection{Amendments} + +\noindent\begin{tabularx}{\textwidth}{| p{1cm} | p{3cm} | p{2cm} | X | p{4cm} |} \hline +\rowcolor{gray!33} No. & Date & Version & Subject of Amendments & Author \\ \hline + +1 & YYYY-MM-DD & \arrowversion & & Xxx Yyy \\ \hline +\end{tabularx} + +\subsection{Quality Assurance} + +\noindent\begin{tabularx}{\textwidth}{| p{1cm} | p{3cm} | p{2cm} | X |} \hline +\rowcolor{gray!33} No. & Date & Version & Approved by \\ \hline + +1 & YYYY-MM-DD & \arrowversion & \\ \hline + +\end{tabularx} + +\end{document} \ No newline at end of file diff --git a/5.0 Draft/SysD/Authorization/bibliography.bib b/5.0 Draft/SysD/Authorization/bibliography.bib new file mode 100644 index 0000000..afc6807 --- /dev/null +++ b/5.0 Draft/SysD/Authorization/bibliography.bib @@ -0,0 +1,236 @@ +@misc{klyne2002date, + series={Request for Comments}, + number={3339}, + howpublished={RFC 3339}, + note={{RFC Editor}}, + url={https://doi.org/10.17487/RFC3339}, + aurhor={Klyne, G. and C. Newman}, + title={{Date and Time on the Internet: Timestamps}}, + year={2002} +} + +@inproceedings{grigg2004ricardian, + title={The ricardian contract}, + author={Grigg, Ian}, + booktitle={Proceedings of the First IEEE International Workshop on Electronic Contracting}, + pages={25--31}, + year={2004}, + organization={IEEE}, + url={https://doi.org/10.1109/WEC.2004.1319505} +} + +@misc{josefsson2006base64, + series={Request for Comments}, + number={4648}, + howpublished={RFC 4648}, + note={{RFC Editor}}, + url={https://doi.org/10.17487/RFC4648}, + aurhor={S. Josefsson}, + title={{The Base16, Base32, and Base64 Data Encodings}}, + year={2006} +} + +@misc{crocker2008abnf, + series={Request for Comments}, + howpublished={RFC 5234}, + publisher={{RFC Editor}}, + url={https://doi.org/10.17487/RFC5234}, + author={D. Crocker and P. Overell}, + title={{Augmented BNF for Syntax Specifications: ABNF}}, + year={2008} +} + +@misc{cooper2008internet, + series={Request for Comments}, + howpublished={RFC 5280}, + publisher={{RFC Editor}}, + url={https://doi.org/10.17487/RFC5280}, + author={D. Cooper and others}, + title={{Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List ({CRL}) Profile}}, + year={2008} +} + +@misc{bray2014json, + series={Request for Comments}, + number={7159}, + howpublished={RFC 7159}, + note={{RFC Editor}}, + url={https://doi.org/10.17487/RFC7159}, + author={Tim Bray}, + title={{The JavaScript Object Notation (JSON) Data Interchange Format}}, + year={2014} +} + +@misc{eu2014identification, + author={{Council of the European Union}}, + title={Regulation ({EU}) No 910/2014 of the {European} {Parliament} and of the {Council} of 23 July 2014 on electronic identification and trust services for electronic transactions in the internal market and repealing Directive 1999/93/{EC}}, + year={2014}, + url={https://eur-lex.europa.eu/eli/reg/2014/910/oj} +} + +@misc{fielding2014hypertext, + series={Request for Comments}, + number={7230}, + howpublished={RFC 7230}, + note={{RFC Editor}}, + url={https://doi.org/10.17487/RFC7230}, + author={R. Fielding and J. Reschke}, + title={{Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing}}, + year={2018} +} + +@inbook{jerker2017localclouds, + author={Jerker Delsing and Pal Varga}, + editor={Jerker Delsing}, + title={{Local automation clouds}}, + bookTitle={IOT Automation: Arrowhead Framework}, + year={2017}, + publisher={Taylor \& Francis Group}, + address={Boca Raton}, + pages={28}, + isbn={978-1-4987-5675-4}, + doi={10.1201/978-1-315-36789-7}, + url={https://doi.org/10.1201/9781315367897} +} + +@inbook{athan2015legalruleml, + author={Athan, Tara and Governatori, Guido and Palmirani, Monica and Paschke, Adrian and Wyner, Adam}, + editor={Faber, Wolfgang and Paschke, Adrian}, + title={{LegalRuleML: Design Principles and Foundations}}, + bookTitle={Reasoning Web. Web Logic Rules: 11th International Summer School 2015, Berlin, Germany, July 31- August 4, 2015, Tutorial Lectures.}, + year={2015}, + publisher={Springer International Publishing}, + address={Cham}, + pages={151--188}, + isbn={978-3-319-21768-0}, + doi={10.1007/978-3-319-21768-0\_6}, + url={https://doi.org/10.1007/978-3-319-21768-0\_6} +} + +@article{clack2016foundations, + author={Christopher D. Clack and Vikram A. Bakshi and Lee Braine}, + title={Smart Contract Templates: foundations, design landscape and research directions}, + journal={arXiv preprint arXiv:1608.00771}, + volume={abs/1608.00771}, + year= {2016}, + url= {http://arxiv.org/abs/1608.00771}, +} + +@article{clack2016requirements, + title={Smart Contract Templates: essential requirements and design options}, + author={Clack, Christopher D and Bakshi, Vikram A and Braine, Lee}, + journal={arXiv preprint arXiv:1612.04496}, + volume={abs/1612.04496}, + year={2016}, + url= {http://arxiv.org/abs/1612.04496}, +} + +@article{giancaspro2017smart, + title={Is a ‘smart contract’ really a smart idea? Insights from a legal perspective}, + author={Mark Giancaspro}, + journal={Computer Law \& Security Review}, + volume={33}, + number={6}, + year={2017}, + issn={0267-3649}, + url={https://doi.org/10.1016/j.clsr.2017.05.007} +} + +@misc{rescorla2018transport, + series={Request for Comments}, + number={8446}, + howpublished={RFC 8446}, + note={{RFC Editor}}, + url={https://doi.org/10.17487/RFC8446}, + author={E. Rescorla}, + title={{The Transport Layer Security (TLS) Protocol Version 1.3}}, + year={2018} +} + +@inproceedings{palm2019exchange, + author={Emanuel Palm and Olov Schelén and Ulf Bodin and Richard Hedman}, + booktitle={2019 IEEE 17th International Conference on Industrial Informatics (INDIN)}, + title={{The Exchange Network: An Architecture for the Negotiation of Non-Repudiable Token Exchanges}}, + ISSN={2378-363X}, + year={2019}, + url={http://urn.kb.se/resolve?urn=urn:nbn:se:ltu:diva-74043}, + note={\textit{accepted for publication}} +} + +@inbook{palm2019approaching, + author={Emanuel Palm and Ulf Bodin and Olov Schelén}, + title={{The Performance, Interoperability and Integration of Distributed Ledger Technologies}}, + chapter={Paper D}, + pages={111--141}, + publisher={Luleå University of Technology}, + year={2019}, + url={http://urn.kb.se/resolve?urn=urn:nbn:se:ltu:diva-74046}, + isbn={978-91-7790-403-8} +} + +@article{cowlishaw2019floating, + author={Mike Cowlishaw}, + journal={IEEE Std 754-2019 (Revision of IEEE 754-2008)}, + title={{IEEE Standard for Floating-Point Arithmetic}}, + year={2019}, + url={https://doi.org/10.1109/IEEESTD.2019.8766229}, + month={July} +} + +@online{iana2019hash, + author={IANA}, + title={{Hash Function Textual Names}}, + url={https://www.iana.org/assignments/hash-function-text-names/hash-function-text-names.xhtml}, + year={2019} +} + +@online{iana2019signature, + author={IANA}, + title={{Transport Security Layer (TLS) Parameters -- TLS SignatureScheme}}, + url={https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-signaturescheme}, + year={2019}, + note={Note the table \textit{Description} column} +} + +@misc{carion2019json, + series={Request for Comments}, + number={draft-json-schema-language-02}, + howpublished={RFC Draft}, + note={{RFC Editor}}, + url={https://tools.ietf.org/html/draft-json-schema-language-02}, + author={U. Carion}, + title={{JSON Schema Language}}, + year={2019}, + note={accessed 2019-09-27} +} + +@misc{rfc8259, + series = {Request for Comments}, + number = 8259, + howpublished = {RFC 8259}, + publisher = {RFC Editor}, + doi = {10.17487/RFC8259}, + url = {https://rfc-editor.org/rfc/rfc8259.txt}, + author = {Tim Bray}, + title = {{The JavaScript Object Notation (JSON) Data Interchange Format}}, + pagetotal = 16, + year = 2017, + month = dec, + abstract = {JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance.}, +} + + +@misc{rfc9100, + series = {Request for Comments}, + number = 9100, + howpublished = {RFC 9100}, + publisher = {RFC Editor}, + doi = {10.17487/RFC9100}, + url = {https://rfc-editor.org/rfc/rfc9100.txt}, + author = {Carsten Bormann}, + title = {{Sensor Measurement Lists (SenML) Features and Versions}}, + pagetotal = 7, + year = 2021, + month = aug, + abstract = {This short document updates RFC 8428, "Sensor Measurement Lists (SenML)", by specifying the use of independently selectable "SenML Features" and mapping them to SenML version numbers.}, +} \ No newline at end of file diff --git a/5.0 Draft/SysD/Authorization/figures/arrowhead_logo.pdf b/5.0 Draft/SysD/Authorization/figures/arrowhead_logo.pdf new file mode 100644 index 0000000..792e60c Binary files /dev/null and b/5.0 Draft/SysD/Authorization/figures/arrowhead_logo.pdf differ diff --git a/5.0 Draft/SysD/ServiceOrchestration/arrowhead.cls b/5.0 Draft/SysD/ServiceOrchestration/arrowhead.cls new file mode 100644 index 0000000..107e691 --- /dev/null +++ b/5.0 Draft/SysD/ServiceOrchestration/arrowhead.cls @@ -0,0 +1,225 @@ +% Copyright (c) 2021-08-19 Eclipse Arrowhead Project +% +% This program and the accompanying materials are made available under the +% terms of the Eclipse Public License 2.0 which is available at +% http://www.eclipse.org/legal/epl-2.0. +% +% SPDX-License-Identifier: EPL-2.0 + +% Arrowhead LaTeX Template (arrowhead.cls) +% +% A LaTeX document class for Arrowhead documentation. +% +% See example.tex for an example of how to use this class. + +\def\fileversion{1.2.1} +\def\filedate{2021/08/19} +\NeedsTeXFormat{LaTeX2e} + +\ProvidesClass{arrowhead}[\filedate\space Version \fileversion\space] +\LoadClass{article} + +\RequirePackage{xparse} +\RequirePackage{couriers} +\RequirePackage{ifthen} +\RequirePackage[hmargin=2cm,top=4cm,headheight=4cm,bottom=2.4cm,footskip=0.4cm]{geometry} +\RequirePackage{fancyhdr} +\RequirePackage{helvet} +\RequirePackage{lastpage} +\RequirePackage{listings} +\RequirePackage{microtype} +\RequirePackage[pdftex]{graphicx} +\RequirePackage{tabularx} +\RequirePackage[font={small}]{caption} +\RequirePackage[hidelinks]{hyperref} +\RequirePackage[nottoc,numbib]{tocbibind} +\RequirePackage[table]{xcolor} + +\definecolor{ArrowheadBlue}{HTML}{006F99} +\definecolor{ArrowheadGrey}{HTML}{333333} +\definecolor{ArrowheadOrange}{HTML}{D77734} +\definecolor{ArrowheadPurple}{HTML}{8F3165} +\definecolor{ArrowheadTeal}{HTML}{21A28F} +\definecolor{ArrowheadYellow}{HTML}{F6E14E} + +\DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} + +\captionsetup{width=0.94\textwidth} + +\ProcessOptions\relax + +\NewDocumentCommand{\ArrowheadTitle}{m}{\newcommand{\arrowtitle}{#1}} +\NewDocumentCommand{\ArrowheadServiceID}{m}{\newcommand{\arrowid}{#1}} +\NewDocumentCommand{\ArrowheadType}{m}{\newcommand{\arrowtype}{#1}} +\NewDocumentCommand{\ArrowheadTypeShort}{m}{\newcommand{\arrowtypeshort}{#1}} +\NewDocumentCommand{\ArrowheadVersion}{m}{\newcommand{\arrowversion}{#1}} +\NewDocumentCommand{\ArrowheadDate}{m}{\newcommand{\arrowdate}{#1}} +\NewDocumentCommand{\ArrowheadAuthor}{m}{\newcommand{\arrowauthor}{#1}} +\NewDocumentCommand{\ArrowheadStatus}{m}{\newcommand{\arrowstatus}{#1}} +\NewDocumentCommand{\ArrowheadContact}{m}{\newcommand{\arrowcontact}{#1}} +\NewDocumentCommand{\ArrowheadFooter}{m}{\newcommand{\arrowfooter}{#1}} +\NewDocumentCommand{\ArrowheadSetup}{}{ + \hypersetup{ + pdftitle={\arrowtitle\ -- \ \arrowtypeshort}, + pdfauthor={\arrowauthor\ <\arrowcontact>} + } +} +\NewDocumentCommand{\ArrowheadBox}{mm}{ + { + \vspace*{1.5\baselineskip} + \setlength{\tabcolsep}{0pt} + \renewcommand*{\arraystretch}{0} + \noindent + \begin{tabularx}{\dimexpr\textwidth-1pt-2.75ex\relax}{ + @{\textcolor[RGB]{0,72,117}{\vrule width 1pt}} + @{\hspace{2.75ex}} + X + } + \small{\textcolor[RGB]{0,72,117}{\textbf{#1}} #2} + \end{tabularx} + } +} + +\makeatletter + +\let\origsubsubsection\subsubsection +\renewcommand\subsubsection{\@ifstar{\starsubsubsection}{\nostarsubsubsection}} +\newcommand\starsubsubsection[1]{\vspace*{-0.5ex}\origsubsubsection*{#1}\vspace*{-0.75ex}} +\newcommand\nostarsubsubsection[1]{\vspace*{-0.5ex}\origsubsubsection{#1}\vspace*{-0.75ex}} + +\renewcommand\tiny{\@setfontsize\tiny{6}{7}} +\renewenvironment{abstract}{% + \begin{flushleft} + {\large \textbf{\abstractname}}\\ + \normalsize +}{% + \end{flushleft} +} + +\makeatother + +\addtocontents{toc}{\protect\setcounter{tocdepth}{2}} + +\setlength\tabcolsep{1mm} +\renewcommand\arraystretch{1.3} +\renewcommand{\familydefault}{\sfdefault} + +\renewcommand*{\headrulewidth}{0pt} +\pagestyle{fancy} + +\newcounter{Table} +\renewcommand\theTable{\arabic{Table}} + +\fancyhf{} +%% Page Header +\lhead{ + \raisebox{-0.5\height}{\includegraphics[height=2.33cm]{figures/arrowhead_logo}} +} +\rhead{% + \renewcommand{\arraystretch}{0.75}% + \begin{tabular}{p{8.67cm} p{3.33cm}} + \ifthenelse{\value{page}=1}{% + % First Page Header + \tiny{Document title} & \tiny{Document type} \\ + \footnotesize{\textbf{\arrowtitle}} & \footnotesize{\textbf{\arrowtypeshort}} \\ + \tiny{Date} & \tiny{Version} \\ + \footnotesize{\textbf{\arrowdate}} & \footnotesize{\textbf{\arrowversion}} \\ + \tiny{Author} & \tiny{Status} \\ + \footnotesize{\textbf{\arrowauthor}} & \footnotesize{\textbf{\arrowstatus}} \\ + \tiny{Contact} & \tiny{Page} \\ + \footnotesize{\textbf{\arrowcontact}} & \footnotesize{\textbf{\thepage \ (\pageref{LastPage})}} + }{% + % Standard Page Header + \tiny{Document title} & \tiny{Version} \\ + \footnotesize{\textbf{\arrowtitle}} & \footnotesize{\textbf{\arrowversion}} \\ + \tiny{Date} & \tiny{Status} \\ + \footnotesize{\textbf{\arrowdate}} & \footnotesize{\textbf{\arrowstatus}} \\ + & \tiny{Page} \\ + & \footnotesize{\textbf{\thepage \ (\pageref{LastPage})}} + } + \end{tabular}% +} +%% + +%% Page Footer +\lfoot{ + \rule[1pt]{\textwidth}{0.5pt} + \scriptsize + \arrowfooter +} +%% + +%% Syntax Highlighting + +% If you need more syntaxes than these, please add them to this document and +% contribute your additions to the Eclipse Arrowhead project. + +%%% HTTP + +\lstdefinelanguage{HTTP}{ + morekeywords={CONNECT,DELETE,GET,HEAD,OPTIONS,PUT,POST,PATCH,HTTP,HTTPS}, + sensitive=false, + morecomment=[l]{//}, + morecomment=[s]{/*}{*/}, % s is for start and end delimiter + morestring=[b]" +} + +\lstset{% + language=HTTP, + backgroundcolor=\color{white}, + basicstyle=\ttfamily\bfseries\footnotesize\color{ArrowheadGrey}, + breakatwhitespace=false, + breaklines=true, + captionpos=b, + commentstyle=\mdseries, + extendedchars=true, + frame=single, + keepspaces=true, + keywordstyle=\color{ArrowheadBlue}, + numbers=left, + numbersep=1em, + numberstyle=\tiny\color{ArrowheadGrey}, + rulecolor=\color{gray!33}, + showspaces=false, + showstringspaces=false, + showtabs=false, + stringstyle=\color{ArrowheadPurple}, + tabsize=4, + aboveskip=3ex, + belowskip=2ex, +} + +%%% ABNF + +\lstdefinelanguage{ABNF}{ + otherkeywords={=,/}, + morekeywords={alpha,digit}, + sensitive=false, + morecomment=[l]{;}, + morestring=[b]" +} + +\lstset{% + language=ABNF, + backgroundcolor=\color{white}, + basicstyle=\ttfamily\bfseries\footnotesize\color{ArrowheadGrey}, + breakatwhitespace=false, + breaklines=true, + captionpos=b, + commentstyle=\mdseries, + extendedchars=true, + frame=single, + keepspaces=true, + keywordstyle=\color{ArrowheadBlue}, + numbers=left, + numbersep=1em, + numberstyle=\tiny\color{ArrowheadGrey}, + rulecolor=\color{gray!33}, + showspaces=false, + showstringspaces=false, + showtabs=false, + stringstyle=\color{ArrowheadPurple}, + tabsize=4, + aboveskip=3ex, + belowskip=2ex, +} \ No newline at end of file diff --git a/5.0 Draft/SysD/ServiceOrchestration/bibliography.bib b/5.0 Draft/SysD/ServiceOrchestration/bibliography.bib new file mode 100644 index 0000000..afc6807 --- /dev/null +++ b/5.0 Draft/SysD/ServiceOrchestration/bibliography.bib @@ -0,0 +1,236 @@ +@misc{klyne2002date, + series={Request for Comments}, + number={3339}, + howpublished={RFC 3339}, + note={{RFC Editor}}, + url={https://doi.org/10.17487/RFC3339}, + aurhor={Klyne, G. and C. Newman}, + title={{Date and Time on the Internet: Timestamps}}, + year={2002} +} + +@inproceedings{grigg2004ricardian, + title={The ricardian contract}, + author={Grigg, Ian}, + booktitle={Proceedings of the First IEEE International Workshop on Electronic Contracting}, + pages={25--31}, + year={2004}, + organization={IEEE}, + url={https://doi.org/10.1109/WEC.2004.1319505} +} + +@misc{josefsson2006base64, + series={Request for Comments}, + number={4648}, + howpublished={RFC 4648}, + note={{RFC Editor}}, + url={https://doi.org/10.17487/RFC4648}, + aurhor={S. Josefsson}, + title={{The Base16, Base32, and Base64 Data Encodings}}, + year={2006} +} + +@misc{crocker2008abnf, + series={Request for Comments}, + howpublished={RFC 5234}, + publisher={{RFC Editor}}, + url={https://doi.org/10.17487/RFC5234}, + author={D. Crocker and P. Overell}, + title={{Augmented BNF for Syntax Specifications: ABNF}}, + year={2008} +} + +@misc{cooper2008internet, + series={Request for Comments}, + howpublished={RFC 5280}, + publisher={{RFC Editor}}, + url={https://doi.org/10.17487/RFC5280}, + author={D. Cooper and others}, + title={{Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List ({CRL}) Profile}}, + year={2008} +} + +@misc{bray2014json, + series={Request for Comments}, + number={7159}, + howpublished={RFC 7159}, + note={{RFC Editor}}, + url={https://doi.org/10.17487/RFC7159}, + author={Tim Bray}, + title={{The JavaScript Object Notation (JSON) Data Interchange Format}}, + year={2014} +} + +@misc{eu2014identification, + author={{Council of the European Union}}, + title={Regulation ({EU}) No 910/2014 of the {European} {Parliament} and of the {Council} of 23 July 2014 on electronic identification and trust services for electronic transactions in the internal market and repealing Directive 1999/93/{EC}}, + year={2014}, + url={https://eur-lex.europa.eu/eli/reg/2014/910/oj} +} + +@misc{fielding2014hypertext, + series={Request for Comments}, + number={7230}, + howpublished={RFC 7230}, + note={{RFC Editor}}, + url={https://doi.org/10.17487/RFC7230}, + author={R. Fielding and J. Reschke}, + title={{Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing}}, + year={2018} +} + +@inbook{jerker2017localclouds, + author={Jerker Delsing and Pal Varga}, + editor={Jerker Delsing}, + title={{Local automation clouds}}, + bookTitle={IOT Automation: Arrowhead Framework}, + year={2017}, + publisher={Taylor \& Francis Group}, + address={Boca Raton}, + pages={28}, + isbn={978-1-4987-5675-4}, + doi={10.1201/978-1-315-36789-7}, + url={https://doi.org/10.1201/9781315367897} +} + +@inbook{athan2015legalruleml, + author={Athan, Tara and Governatori, Guido and Palmirani, Monica and Paschke, Adrian and Wyner, Adam}, + editor={Faber, Wolfgang and Paschke, Adrian}, + title={{LegalRuleML: Design Principles and Foundations}}, + bookTitle={Reasoning Web. Web Logic Rules: 11th International Summer School 2015, Berlin, Germany, July 31- August 4, 2015, Tutorial Lectures.}, + year={2015}, + publisher={Springer International Publishing}, + address={Cham}, + pages={151--188}, + isbn={978-3-319-21768-0}, + doi={10.1007/978-3-319-21768-0\_6}, + url={https://doi.org/10.1007/978-3-319-21768-0\_6} +} + +@article{clack2016foundations, + author={Christopher D. Clack and Vikram A. Bakshi and Lee Braine}, + title={Smart Contract Templates: foundations, design landscape and research directions}, + journal={arXiv preprint arXiv:1608.00771}, + volume={abs/1608.00771}, + year= {2016}, + url= {http://arxiv.org/abs/1608.00771}, +} + +@article{clack2016requirements, + title={Smart Contract Templates: essential requirements and design options}, + author={Clack, Christopher D and Bakshi, Vikram A and Braine, Lee}, + journal={arXiv preprint arXiv:1612.04496}, + volume={abs/1612.04496}, + year={2016}, + url= {http://arxiv.org/abs/1612.04496}, +} + +@article{giancaspro2017smart, + title={Is a ‘smart contract’ really a smart idea? Insights from a legal perspective}, + author={Mark Giancaspro}, + journal={Computer Law \& Security Review}, + volume={33}, + number={6}, + year={2017}, + issn={0267-3649}, + url={https://doi.org/10.1016/j.clsr.2017.05.007} +} + +@misc{rescorla2018transport, + series={Request for Comments}, + number={8446}, + howpublished={RFC 8446}, + note={{RFC Editor}}, + url={https://doi.org/10.17487/RFC8446}, + author={E. Rescorla}, + title={{The Transport Layer Security (TLS) Protocol Version 1.3}}, + year={2018} +} + +@inproceedings{palm2019exchange, + author={Emanuel Palm and Olov Schelén and Ulf Bodin and Richard Hedman}, + booktitle={2019 IEEE 17th International Conference on Industrial Informatics (INDIN)}, + title={{The Exchange Network: An Architecture for the Negotiation of Non-Repudiable Token Exchanges}}, + ISSN={2378-363X}, + year={2019}, + url={http://urn.kb.se/resolve?urn=urn:nbn:se:ltu:diva-74043}, + note={\textit{accepted for publication}} +} + +@inbook{palm2019approaching, + author={Emanuel Palm and Ulf Bodin and Olov Schelén}, + title={{The Performance, Interoperability and Integration of Distributed Ledger Technologies}}, + chapter={Paper D}, + pages={111--141}, + publisher={Luleå University of Technology}, + year={2019}, + url={http://urn.kb.se/resolve?urn=urn:nbn:se:ltu:diva-74046}, + isbn={978-91-7790-403-8} +} + +@article{cowlishaw2019floating, + author={Mike Cowlishaw}, + journal={IEEE Std 754-2019 (Revision of IEEE 754-2008)}, + title={{IEEE Standard for Floating-Point Arithmetic}}, + year={2019}, + url={https://doi.org/10.1109/IEEESTD.2019.8766229}, + month={July} +} + +@online{iana2019hash, + author={IANA}, + title={{Hash Function Textual Names}}, + url={https://www.iana.org/assignments/hash-function-text-names/hash-function-text-names.xhtml}, + year={2019} +} + +@online{iana2019signature, + author={IANA}, + title={{Transport Security Layer (TLS) Parameters -- TLS SignatureScheme}}, + url={https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-signaturescheme}, + year={2019}, + note={Note the table \textit{Description} column} +} + +@misc{carion2019json, + series={Request for Comments}, + number={draft-json-schema-language-02}, + howpublished={RFC Draft}, + note={{RFC Editor}}, + url={https://tools.ietf.org/html/draft-json-schema-language-02}, + author={U. Carion}, + title={{JSON Schema Language}}, + year={2019}, + note={accessed 2019-09-27} +} + +@misc{rfc8259, + series = {Request for Comments}, + number = 8259, + howpublished = {RFC 8259}, + publisher = {RFC Editor}, + doi = {10.17487/RFC8259}, + url = {https://rfc-editor.org/rfc/rfc8259.txt}, + author = {Tim Bray}, + title = {{The JavaScript Object Notation (JSON) Data Interchange Format}}, + pagetotal = 16, + year = 2017, + month = dec, + abstract = {JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance.}, +} + + +@misc{rfc9100, + series = {Request for Comments}, + number = 9100, + howpublished = {RFC 9100}, + publisher = {RFC Editor}, + doi = {10.17487/RFC9100}, + url = {https://rfc-editor.org/rfc/rfc9100.txt}, + author = {Carsten Bormann}, + title = {{Sensor Measurement Lists (SenML) Features and Versions}}, + pagetotal = 7, + year = 2021, + month = aug, + abstract = {This short document updates RFC 8428, "Sensor Measurement Lists (SenML)", by specifying the use of independently selectable "SenML Features" and mapping them to SenML version numbers.}, +} \ No newline at end of file diff --git a/5.0 Draft/SysD/ServiceOrchestration/figures/arrowhead_logo.pdf b/5.0 Draft/SysD/ServiceOrchestration/figures/arrowhead_logo.pdf new file mode 100644 index 0000000..792e60c Binary files /dev/null and b/5.0 Draft/SysD/ServiceOrchestration/figures/arrowhead_logo.pdf differ diff --git a/5.0 Draft/SysD/ServiceOrchestration/serviceorchestration_sysd.pdf b/5.0 Draft/SysD/ServiceOrchestration/serviceorchestration_sysd.pdf new file mode 100644 index 0000000..fca3340 Binary files /dev/null and b/5.0 Draft/SysD/ServiceOrchestration/serviceorchestration_sysd.pdf differ diff --git a/5.0 Draft/SysD/ServiceOrchestration/serviceorchestration_sysd.tex b/5.0 Draft/SysD/ServiceOrchestration/serviceorchestration_sysd.tex new file mode 100644 index 0000000..113bebd --- /dev/null +++ b/5.0 Draft/SysD/ServiceOrchestration/serviceorchestration_sysd.tex @@ -0,0 +1,260 @@ +\documentclass[a4paper]{arrowhead} + +\usepackage[yyyymmdd]{datetime} +\usepackage{etoolbox} +\usepackage[utf8]{inputenc} +\usepackage{multirow} +\usepackage{hyperref} + +\renewcommand{\dateseparator}{-} + +\setlength{\parskip}{1em} + +%% Special references +\newcommand{\fref}[1]{{\textcolor{ArrowheadBlue}{\hyperref[sec:functions:#1]{#1}}}} +\newcommand{\mref}[1]{{\textcolor{ArrowheadPurple}{\hyperref[sec:model:#1]{#1}}}} +\newcommand{\pdef}[1]{{\textcolor{ArrowheadGrey}{#1\label{sec:model:primitives:#1}\label{sec:model:primitives:#1s}\label{sec:model:primitives:#1es}}}} +\newcommand{\pref}[1]{{\textcolor{ArrowheadGrey}{\hyperref[sec:model:primitives:#1]{#1}}}} + +\newrobustcmd\fsubsection[3]{ + \addtocounter{subsection}{1} + \addcontentsline{toc}{subsection}{\protect\numberline{\thesubsection}function \textcolor{ArrowheadBlue}{#1}} + \renewcommand*{\do}[1]{\rref{##1},\ } + \subsection*{ + \thesubsection\quad + operation + \textcolor{ArrowheadBlue}{#1} + (\notblank{#2}{\mref{#2}}{}) + \notblank{#3}{: \mref{#3}}{} + } + \label{sec:functions:#1} +} +\newrobustcmd\msubsection[2]{ + \addtocounter{subsection}{1} + \addcontentsline{toc}{subsection}{\protect\numberline{\thesubsection}#1 \textcolor{ArrowheadPurple}{#2}} + \subsection*{\thesubsection\quad#1 \textcolor{ArrowheadPurple}{#2}} + \label{sec:model:#2} \label{sec:model:#2s} \label{sec:model:#2es} +} + +\begin{document} + +%% Arrowhead Document Properties +\ArrowheadTitle{Service Orchestration Core System} +\ArrowheadType{System Description} +\ArrowheadTypeShort{SysD} +\ArrowheadVersion{5.0.0} +\ArrowheadDate{\today} +\ArrowheadAuthor{Rajmund Bocsi} +\ArrowheadStatus{DRAFT} +\ArrowheadContact{rbocsi@aitia.ai} +\ArrowheadFooter{\href{www.arrowhead.eu}{www.arrowhead.eu}} +\ArrowheadSetup +%% + +%% Front Page +\begin{center} + \vspace*{1cm} + \huge{\arrowtitle} + + \vspace*{0.2cm} + \LARGE{\arrowtype} + \vspace*{1cm} + + %\Large{Service ID: \textit{"\arrowid"}} + \vspace*{\fill} + + % Front Page Image + %\includegraphics{figures/TODO} + + \vspace*{1cm} + \vspace*{\fill} + + % Front Page Abstract + \begin{abstract} + This document provides system description for the \textbf{Service Orchestration Core System}. + \end{abstract} + + \vspace*{1cm} + + \end{center} + +\newpage +%% + +%% Table of Contents +\tableofcontents +\newpage +%% + +\section{Overview} +\label{sec:overview} +\color{black} +This document describes the Service Orchestration Core System, which exists to find matching providers for the consumer's specification within an Eclipse Arrowhead Local Cloud (LC) and optionally, in other Arrowhead clouds by collaborating with other core/support Systems. This can be achieved by using stored matching rules or applying a more dynamic strategy using the Service Registry Core System. This recommended system may provide the data storage functionality for the information related to matching rules and/or provider reservation. + +The rest of this document is organized as follows. +In Section \ref{sec:prior_art}, we reference major prior art capabilities +of the system. +In Section \ref{sec:use}, we describe the intended usage of the system. +In Section \ref{sec:properties}, we describe fundamental properties +provided by the system. +In Section \ref{sec:delimitations}, we describe delimitations of capabilities +of the system. +In Section \ref{sec:services}, we describe the abstract services produced by the system. +In Section \ref{sec:security}, we describe the security capabilities +of the system. + +\subsection{Significant Prior Art} +\label{sec:prior_art} + +The strong development on cloud technology and various requirements for digitisation and automation has led to the concept of Local Clouds (LC). + +\textit{"The concept takes the view that specific geographically local automation tasks should be encapsulated and protected."} \cite{jerker2017localclouds} + +A service orchestration system is a central component in any Service-Oriented Architecture (SOA). In applications, the use of SOA for a massive distributed System of Systems requires orchestration. It is utilised to dynamically allow the re-use of existing services and systems in order to create new services and functionality. + +There are some key differences, even on conceptual level, between the previous versions (Orchestrator 4.6.x) and this version: + +\begin{itemize} + \item The previous versions were named the system as Orchestrator. Because this expression has a different meaning in some related domains, it is decided that the current version uses the name Service Orchestration to avoid confusion. + \item The previous versions contained three (or two in earlier versions) kind of orchestration strategies: a store containing simple, peer-to-peer rules, an other store containing more flexible rules and a dynamic orchestration method which used the live data of the Service Registry to achieve its goal. The current version separates the three strategies into three different Service Orchestration systems (but with the same orchestration service operations), and the Local Cloud's administrator can decide which strategy want to support for their use case. + \item There was no data storage separation requirement: the Orchestrator's data storage was interconnected to other systems' storage. In the current version, data storage separation is mandatory. + \item You could only create an orchestration rule if all related entities (consumer system, provider system, service definition and interface) are already existed (in the Service Registry's data storage). The current version supports rules referencing non-existent entities for future usage. + \item Only an administrator were able to add and remove rules (in case of simple store orchestration). The current version allows any system (only those with the proper permissions, of course) to add and remove orchestration rules. + \item Only the orchestration pull was supported in which the consumer could start an orchestration process for itself. The current version also supports orchestration push: the consumers can subscribe to a service orchestration (or an other support/application system can subscribe them) and after the subscription and whenever a system notifies the Service Orchestration system, it performs the orchestration for the related subscribers. + \item The Quality-of-Service (QoS) Manager component was embedded into the Orchestrator (only QoS data comes from a support system). The current version moves these functionalities into a separate support system (which also be responsible to collect and store QoS data). + \item X.509 certificate trust chains was used as authentication mechanism. The current version can support any type of authentication methods by using a dedicate Authentication Provider core system. +\end{itemize} + +\subsection{How This System Is Meant to Be Used} +\label{sec:use} + +Service Orchestration is a recommended core system of Eclipse Arrowhead Local Cloud and is responsible for finding and pairing service consumers and providers. + +There are two ways to use the offered functionality: + +\begin{itemize} + \item An application that want to consume a service should ask the Service Orchestration to find one or more accessible providers that meet the necessary requirements. The Service Orchestration returns the information that the application needs to consume the specified service. + \item An application can subscribe for orchestration with the necessary requirements (or can be subscribed by an other application/support system). The Service Orchestration performs the orchestration process and returns the information on the specified channel. Additionally, whenever a system notifies the Service Orchestration system, it does the orchestration again and returns the updated information the the subscriber. +\end{itemize} + +The \textit{information} that is provided to the consumer whenever an orchestration is done depends on the strategy that the Service Orchestration system has implemented. + +\begin{itemize} + \item In the case of simple store orchestration, the response contains service instance names. The consumer can use these names to query the Service Registry and acquire access information of the service it should consume. + \item In the case of flexible store orchestration or dynamic orchestration, the Service Orchestration system has to contact the Service Registry to perform the orchestration so in the response it can return everything what is needed for the consumer to perform a service operation consumption. +\end{itemize} + +\subsection{System functionalities and properties} +\label{sec:properties} + +\subsubsection {Functional properties of the system} +Service Orchestration solves the following needs to fulfill the requirements of orchestration. + +\begin{itemize} + \item Enables the application and core/support systems to find the appropriate providers to consume their services. + \item Enables the application and core/support systems to subscribe/unsubscribe to repeated orchestration (orchestration push). + \item Enables other application and core/support systems to notify the Service Orchestration system to re-orchestrate for the related subscribers. + \item Enables other application and core/support systems to subscribe/unsubscribe consumers to repeated orchestrations. +\end{itemize} + +\subsubsection {Non functional properties of the system} +If an Authentication Provider (AP) is present in the Local Cloud, the Service Orchestration system will use AP's service(s) to verify a requester system before responding to its request. + +If flexible store or dynamic orchestration strategy is used, the following are true as well: + +\begin{itemize} + \item (\textit{Condition}: Authorization system is present in the Local Cloud): if the consumer is not authorized to use a service provider the orchestration service removes the appropriate provider from the response; + \item (\textit{Condition}: Authorization system is present in the Local Cloud): orchestration service automatically adds every necessary tokens to the response (if the related provider requires it); + \item (\textit{Condition}: Gatekeeper system is present in the Local Cloud): inter-cloud orchestration is possible; + \item (\textit{Condition}: Gatekeeper and Gatepath system is present in the Local Cloud): inter-cloud orchestration is possible even between two closed local clouds and the necessary communication tunnel will be built during the orchestration process; + \item (\textit{Condition}: Quality-of-Service Management system is present in the Local Cloud): during orchestration Quality-of-Service requirements can be considered; + \item (\textit{Condition}: Translation system is present in the Local Cloud): protocol and data model translation can be used to fulfill orchestration requirements. +\end{itemize} + +\subsubsection {Data stored by the system} +In order to achieve the mentioned functionalities, Service Orchestration is capable to store the following information set: + +\begin{itemize} + \item \textbf{Simple orchestration rules} (\textit{only used in the simple store orchestration strategy}): A rule consists a consumer system name, a service definition name, a service instance name and a priority. Multiple service instance can assign to the same consumer-service definition pair as long as the priority is different. + \item \textbf{Flexible orchestration rules} (\textit{only used in the flexible store orchestration strategy}): A rule consists a consumer system name and/or consumer system metadata requirements, a provider system name (with cloud identification data, if the provider is in an other cloud) and/or provider system metadata requirements, a service definition name, an optional service interface requirement, optional service metadata requirements, optional minimum and maximum service version requirements and an optional priority. + \item \textbf{Provider reservations} (\textit{only used in the flexible store and dynamic orchestration strategies}): A storage to manage ongoing provider reservations. It consists a consumer system name, a reserved provider name and a timestamp which marks the end of reservation. +\end{itemize} + +\subsection{Important Delimitations} +\label{sec:delimitations} + +\begin{itemize} + \item There are three orchestration strategies (for now). A Service Orchestration implementation must support only one of those (but it may support multiple strategies). The administrator of the Local Cloud can decide what kind of orchestration strategy is used in the cloud, a consumer can not. + \item If the Local Cloud does not contain an Authentication system, there is no way for the Service Orchestration to verify the requester system. In that case, the Service Orchestration will consider the authentication data comes from the requester as valid. + \item If the Local Cloud does not contain a Service Registry, then Service Orchestration system with simple store strategy can be used. The two other strategies need the continuous support of the Service Registry system to provide their services. + \item The flexible store and dynamic orchestration strategies need other core/support systems to provide their full functionalities, see details above. +\end{itemize} + +\newpage + +\section{Services produced} +\label{sec:services} + +\msubsection{service}{orchestration} +The purpose of this service is to find information about providers that meet the requirements. It also provided subscription functionality to repeated orchestrations (orchestration push). The service is offered for both application and core/support systems. + +\msubsection{service}{orchestration-push-management} +The purpose of this service is to manage orchestration push subscriptions in bulk. It also allows to signal the Service Orchestration system to orchestrate to related subscribers. The service is offered for both application and core/support systems. + +\msubsection{service}{simple-store-management} +Recommended service (and only if the Service Orchestration system is using the simple store strategy). The purpose of this service is to add, remove and query simple store orchestration rules in bulk. The service is offered for core/support systems. + +\msubsection{service}{flexible-store-management} +Recommended service (and only if the Service Orchestration system is using the flexible store strategy). The purpose of this service is to add, remove and query flexible store orchestration rules in bulk. The service is offered for core/support systems. + +\msubsection{service}{reservation-management} +Recommended service (and only if the Service Orchestration system is using the flexible store or dynamic strategy). The purpose of this service is to add, remove and query active reservations. The service is offered for core/support systems. + +\msubsection{service}{monitor} +Recommended service. Its purpose is to give information about the provider system. The service is offered for both application and core/support systems. + +\newpage + +\section{Security} +\label{sec:security} + +For authentication, the Service Orchestration utilizes an other core system, the Authentication system's service to verify the identities of the requester systems. If no Authentication system is deployed into the Local Cloud, the Service Orchestration trusts the requester system self-provided identity. + +For authorization, the system uses an other core system, the Authorization system to decide whether a consumer can use its services or not. If the Authorization core system is not present in the Local Cloud, then the Service Orchestration allows for anyone in the local cloud to use its services. The following service operations can always be used without any authorization rules: + +\begin{itemize} + \item \textit{orchestration} service's \textit{orchestration-pull} operation, + \item \textit{orchestration} service's \textit{subscribe} operation, + \item \textit{orchestration} service's \textit{unsubscribe} operation. +\end{itemize} + +Furthermore, if the Authorization system is deployed in the Local Cloud, a Service Orchestration system with flexible store or dynamic orchestration strategy, will use the appropriate service to check whether the consumer can consume the required service of a specific provider during the orchestration process. + +The implementation of the Service Orchestration can decide about the encryption of the connection between the Service Orchestration and other systems. + +\newpage + +\bibliographystyle{IEEEtran} +\bibliography{bibliography} + +\newpage + +\section{Revision History} +\subsection{Amendments} + +\noindent\begin{tabularx}{\textwidth}{| p{1cm} | p{3cm} | p{2cm} | X | p{4cm} |} \hline +\rowcolor{gray!33} No. & Date & Version & Subject of Amendments & Author \\ \hline + +1 & YYYY-MM-DD & \arrowversion & & Xxx Yyy \\ \hline +\end{tabularx} + +\subsection{Quality Assurance} + +\noindent\begin{tabularx}{\textwidth}{| p{1cm} | p{3cm} | p{2cm} | X |} \hline +\rowcolor{gray!33} No. & Date & Version & Approved by \\ \hline + +1 & YYYY-MM-DD & \arrowversion & \\ \hline + +\end{tabularx} + +\end{document} \ No newline at end of file diff --git a/5.0 Draft/SysD/ServiceRegistry/arrowhead.cls b/5.0 Draft/SysD/ServiceRegistry/arrowhead.cls new file mode 100644 index 0000000..107e691 --- /dev/null +++ b/5.0 Draft/SysD/ServiceRegistry/arrowhead.cls @@ -0,0 +1,225 @@ +% Copyright (c) 2021-08-19 Eclipse Arrowhead Project +% +% This program and the accompanying materials are made available under the +% terms of the Eclipse Public License 2.0 which is available at +% http://www.eclipse.org/legal/epl-2.0. +% +% SPDX-License-Identifier: EPL-2.0 + +% Arrowhead LaTeX Template (arrowhead.cls) +% +% A LaTeX document class for Arrowhead documentation. +% +% See example.tex for an example of how to use this class. + +\def\fileversion{1.2.1} +\def\filedate{2021/08/19} +\NeedsTeXFormat{LaTeX2e} + +\ProvidesClass{arrowhead}[\filedate\space Version \fileversion\space] +\LoadClass{article} + +\RequirePackage{xparse} +\RequirePackage{couriers} +\RequirePackage{ifthen} +\RequirePackage[hmargin=2cm,top=4cm,headheight=4cm,bottom=2.4cm,footskip=0.4cm]{geometry} +\RequirePackage{fancyhdr} +\RequirePackage{helvet} +\RequirePackage{lastpage} +\RequirePackage{listings} +\RequirePackage{microtype} +\RequirePackage[pdftex]{graphicx} +\RequirePackage{tabularx} +\RequirePackage[font={small}]{caption} +\RequirePackage[hidelinks]{hyperref} +\RequirePackage[nottoc,numbib]{tocbibind} +\RequirePackage[table]{xcolor} + +\definecolor{ArrowheadBlue}{HTML}{006F99} +\definecolor{ArrowheadGrey}{HTML}{333333} +\definecolor{ArrowheadOrange}{HTML}{D77734} +\definecolor{ArrowheadPurple}{HTML}{8F3165} +\definecolor{ArrowheadTeal}{HTML}{21A28F} +\definecolor{ArrowheadYellow}{HTML}{F6E14E} + +\DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} + +\captionsetup{width=0.94\textwidth} + +\ProcessOptions\relax + +\NewDocumentCommand{\ArrowheadTitle}{m}{\newcommand{\arrowtitle}{#1}} +\NewDocumentCommand{\ArrowheadServiceID}{m}{\newcommand{\arrowid}{#1}} +\NewDocumentCommand{\ArrowheadType}{m}{\newcommand{\arrowtype}{#1}} +\NewDocumentCommand{\ArrowheadTypeShort}{m}{\newcommand{\arrowtypeshort}{#1}} +\NewDocumentCommand{\ArrowheadVersion}{m}{\newcommand{\arrowversion}{#1}} +\NewDocumentCommand{\ArrowheadDate}{m}{\newcommand{\arrowdate}{#1}} +\NewDocumentCommand{\ArrowheadAuthor}{m}{\newcommand{\arrowauthor}{#1}} +\NewDocumentCommand{\ArrowheadStatus}{m}{\newcommand{\arrowstatus}{#1}} +\NewDocumentCommand{\ArrowheadContact}{m}{\newcommand{\arrowcontact}{#1}} +\NewDocumentCommand{\ArrowheadFooter}{m}{\newcommand{\arrowfooter}{#1}} +\NewDocumentCommand{\ArrowheadSetup}{}{ + \hypersetup{ + pdftitle={\arrowtitle\ -- \ \arrowtypeshort}, + pdfauthor={\arrowauthor\ <\arrowcontact>} + } +} +\NewDocumentCommand{\ArrowheadBox}{mm}{ + { + \vspace*{1.5\baselineskip} + \setlength{\tabcolsep}{0pt} + \renewcommand*{\arraystretch}{0} + \noindent + \begin{tabularx}{\dimexpr\textwidth-1pt-2.75ex\relax}{ + @{\textcolor[RGB]{0,72,117}{\vrule width 1pt}} + @{\hspace{2.75ex}} + X + } + \small{\textcolor[RGB]{0,72,117}{\textbf{#1}} #2} + \end{tabularx} + } +} + +\makeatletter + +\let\origsubsubsection\subsubsection +\renewcommand\subsubsection{\@ifstar{\starsubsubsection}{\nostarsubsubsection}} +\newcommand\starsubsubsection[1]{\vspace*{-0.5ex}\origsubsubsection*{#1}\vspace*{-0.75ex}} +\newcommand\nostarsubsubsection[1]{\vspace*{-0.5ex}\origsubsubsection{#1}\vspace*{-0.75ex}} + +\renewcommand\tiny{\@setfontsize\tiny{6}{7}} +\renewenvironment{abstract}{% + \begin{flushleft} + {\large \textbf{\abstractname}}\\ + \normalsize +}{% + \end{flushleft} +} + +\makeatother + +\addtocontents{toc}{\protect\setcounter{tocdepth}{2}} + +\setlength\tabcolsep{1mm} +\renewcommand\arraystretch{1.3} +\renewcommand{\familydefault}{\sfdefault} + +\renewcommand*{\headrulewidth}{0pt} +\pagestyle{fancy} + +\newcounter{Table} +\renewcommand\theTable{\arabic{Table}} + +\fancyhf{} +%% Page Header +\lhead{ + \raisebox{-0.5\height}{\includegraphics[height=2.33cm]{figures/arrowhead_logo}} +} +\rhead{% + \renewcommand{\arraystretch}{0.75}% + \begin{tabular}{p{8.67cm} p{3.33cm}} + \ifthenelse{\value{page}=1}{% + % First Page Header + \tiny{Document title} & \tiny{Document type} \\ + \footnotesize{\textbf{\arrowtitle}} & \footnotesize{\textbf{\arrowtypeshort}} \\ + \tiny{Date} & \tiny{Version} \\ + \footnotesize{\textbf{\arrowdate}} & \footnotesize{\textbf{\arrowversion}} \\ + \tiny{Author} & \tiny{Status} \\ + \footnotesize{\textbf{\arrowauthor}} & \footnotesize{\textbf{\arrowstatus}} \\ + \tiny{Contact} & \tiny{Page} \\ + \footnotesize{\textbf{\arrowcontact}} & \footnotesize{\textbf{\thepage \ (\pageref{LastPage})}} + }{% + % Standard Page Header + \tiny{Document title} & \tiny{Version} \\ + \footnotesize{\textbf{\arrowtitle}} & \footnotesize{\textbf{\arrowversion}} \\ + \tiny{Date} & \tiny{Status} \\ + \footnotesize{\textbf{\arrowdate}} & \footnotesize{\textbf{\arrowstatus}} \\ + & \tiny{Page} \\ + & \footnotesize{\textbf{\thepage \ (\pageref{LastPage})}} + } + \end{tabular}% +} +%% + +%% Page Footer +\lfoot{ + \rule[1pt]{\textwidth}{0.5pt} + \scriptsize + \arrowfooter +} +%% + +%% Syntax Highlighting + +% If you need more syntaxes than these, please add them to this document and +% contribute your additions to the Eclipse Arrowhead project. + +%%% HTTP + +\lstdefinelanguage{HTTP}{ + morekeywords={CONNECT,DELETE,GET,HEAD,OPTIONS,PUT,POST,PATCH,HTTP,HTTPS}, + sensitive=false, + morecomment=[l]{//}, + morecomment=[s]{/*}{*/}, % s is for start and end delimiter + morestring=[b]" +} + +\lstset{% + language=HTTP, + backgroundcolor=\color{white}, + basicstyle=\ttfamily\bfseries\footnotesize\color{ArrowheadGrey}, + breakatwhitespace=false, + breaklines=true, + captionpos=b, + commentstyle=\mdseries, + extendedchars=true, + frame=single, + keepspaces=true, + keywordstyle=\color{ArrowheadBlue}, + numbers=left, + numbersep=1em, + numberstyle=\tiny\color{ArrowheadGrey}, + rulecolor=\color{gray!33}, + showspaces=false, + showstringspaces=false, + showtabs=false, + stringstyle=\color{ArrowheadPurple}, + tabsize=4, + aboveskip=3ex, + belowskip=2ex, +} + +%%% ABNF + +\lstdefinelanguage{ABNF}{ + otherkeywords={=,/}, + morekeywords={alpha,digit}, + sensitive=false, + morecomment=[l]{;}, + morestring=[b]" +} + +\lstset{% + language=ABNF, + backgroundcolor=\color{white}, + basicstyle=\ttfamily\bfseries\footnotesize\color{ArrowheadGrey}, + breakatwhitespace=false, + breaklines=true, + captionpos=b, + commentstyle=\mdseries, + extendedchars=true, + frame=single, + keepspaces=true, + keywordstyle=\color{ArrowheadBlue}, + numbers=left, + numbersep=1em, + numberstyle=\tiny\color{ArrowheadGrey}, + rulecolor=\color{gray!33}, + showspaces=false, + showstringspaces=false, + showtabs=false, + stringstyle=\color{ArrowheadPurple}, + tabsize=4, + aboveskip=3ex, + belowskip=2ex, +} \ No newline at end of file diff --git a/5.0 Draft/SysD/ServiceRegistry/bibliography.bib b/5.0 Draft/SysD/ServiceRegistry/bibliography.bib new file mode 100644 index 0000000..afc6807 --- /dev/null +++ b/5.0 Draft/SysD/ServiceRegistry/bibliography.bib @@ -0,0 +1,236 @@ +@misc{klyne2002date, + series={Request for Comments}, + number={3339}, + howpublished={RFC 3339}, + note={{RFC Editor}}, + url={https://doi.org/10.17487/RFC3339}, + aurhor={Klyne, G. and C. Newman}, + title={{Date and Time on the Internet: Timestamps}}, + year={2002} +} + +@inproceedings{grigg2004ricardian, + title={The ricardian contract}, + author={Grigg, Ian}, + booktitle={Proceedings of the First IEEE International Workshop on Electronic Contracting}, + pages={25--31}, + year={2004}, + organization={IEEE}, + url={https://doi.org/10.1109/WEC.2004.1319505} +} + +@misc{josefsson2006base64, + series={Request for Comments}, + number={4648}, + howpublished={RFC 4648}, + note={{RFC Editor}}, + url={https://doi.org/10.17487/RFC4648}, + aurhor={S. Josefsson}, + title={{The Base16, Base32, and Base64 Data Encodings}}, + year={2006} +} + +@misc{crocker2008abnf, + series={Request for Comments}, + howpublished={RFC 5234}, + publisher={{RFC Editor}}, + url={https://doi.org/10.17487/RFC5234}, + author={D. Crocker and P. Overell}, + title={{Augmented BNF for Syntax Specifications: ABNF}}, + year={2008} +} + +@misc{cooper2008internet, + series={Request for Comments}, + howpublished={RFC 5280}, + publisher={{RFC Editor}}, + url={https://doi.org/10.17487/RFC5280}, + author={D. Cooper and others}, + title={{Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List ({CRL}) Profile}}, + year={2008} +} + +@misc{bray2014json, + series={Request for Comments}, + number={7159}, + howpublished={RFC 7159}, + note={{RFC Editor}}, + url={https://doi.org/10.17487/RFC7159}, + author={Tim Bray}, + title={{The JavaScript Object Notation (JSON) Data Interchange Format}}, + year={2014} +} + +@misc{eu2014identification, + author={{Council of the European Union}}, + title={Regulation ({EU}) No 910/2014 of the {European} {Parliament} and of the {Council} of 23 July 2014 on electronic identification and trust services for electronic transactions in the internal market and repealing Directive 1999/93/{EC}}, + year={2014}, + url={https://eur-lex.europa.eu/eli/reg/2014/910/oj} +} + +@misc{fielding2014hypertext, + series={Request for Comments}, + number={7230}, + howpublished={RFC 7230}, + note={{RFC Editor}}, + url={https://doi.org/10.17487/RFC7230}, + author={R. Fielding and J. Reschke}, + title={{Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing}}, + year={2018} +} + +@inbook{jerker2017localclouds, + author={Jerker Delsing and Pal Varga}, + editor={Jerker Delsing}, + title={{Local automation clouds}}, + bookTitle={IOT Automation: Arrowhead Framework}, + year={2017}, + publisher={Taylor \& Francis Group}, + address={Boca Raton}, + pages={28}, + isbn={978-1-4987-5675-4}, + doi={10.1201/978-1-315-36789-7}, + url={https://doi.org/10.1201/9781315367897} +} + +@inbook{athan2015legalruleml, + author={Athan, Tara and Governatori, Guido and Palmirani, Monica and Paschke, Adrian and Wyner, Adam}, + editor={Faber, Wolfgang and Paschke, Adrian}, + title={{LegalRuleML: Design Principles and Foundations}}, + bookTitle={Reasoning Web. Web Logic Rules: 11th International Summer School 2015, Berlin, Germany, July 31- August 4, 2015, Tutorial Lectures.}, + year={2015}, + publisher={Springer International Publishing}, + address={Cham}, + pages={151--188}, + isbn={978-3-319-21768-0}, + doi={10.1007/978-3-319-21768-0\_6}, + url={https://doi.org/10.1007/978-3-319-21768-0\_6} +} + +@article{clack2016foundations, + author={Christopher D. Clack and Vikram A. Bakshi and Lee Braine}, + title={Smart Contract Templates: foundations, design landscape and research directions}, + journal={arXiv preprint arXiv:1608.00771}, + volume={abs/1608.00771}, + year= {2016}, + url= {http://arxiv.org/abs/1608.00771}, +} + +@article{clack2016requirements, + title={Smart Contract Templates: essential requirements and design options}, + author={Clack, Christopher D and Bakshi, Vikram A and Braine, Lee}, + journal={arXiv preprint arXiv:1612.04496}, + volume={abs/1612.04496}, + year={2016}, + url= {http://arxiv.org/abs/1612.04496}, +} + +@article{giancaspro2017smart, + title={Is a ‘smart contract’ really a smart idea? Insights from a legal perspective}, + author={Mark Giancaspro}, + journal={Computer Law \& Security Review}, + volume={33}, + number={6}, + year={2017}, + issn={0267-3649}, + url={https://doi.org/10.1016/j.clsr.2017.05.007} +} + +@misc{rescorla2018transport, + series={Request for Comments}, + number={8446}, + howpublished={RFC 8446}, + note={{RFC Editor}}, + url={https://doi.org/10.17487/RFC8446}, + author={E. Rescorla}, + title={{The Transport Layer Security (TLS) Protocol Version 1.3}}, + year={2018} +} + +@inproceedings{palm2019exchange, + author={Emanuel Palm and Olov Schelén and Ulf Bodin and Richard Hedman}, + booktitle={2019 IEEE 17th International Conference on Industrial Informatics (INDIN)}, + title={{The Exchange Network: An Architecture for the Negotiation of Non-Repudiable Token Exchanges}}, + ISSN={2378-363X}, + year={2019}, + url={http://urn.kb.se/resolve?urn=urn:nbn:se:ltu:diva-74043}, + note={\textit{accepted for publication}} +} + +@inbook{palm2019approaching, + author={Emanuel Palm and Ulf Bodin and Olov Schelén}, + title={{The Performance, Interoperability and Integration of Distributed Ledger Technologies}}, + chapter={Paper D}, + pages={111--141}, + publisher={Luleå University of Technology}, + year={2019}, + url={http://urn.kb.se/resolve?urn=urn:nbn:se:ltu:diva-74046}, + isbn={978-91-7790-403-8} +} + +@article{cowlishaw2019floating, + author={Mike Cowlishaw}, + journal={IEEE Std 754-2019 (Revision of IEEE 754-2008)}, + title={{IEEE Standard for Floating-Point Arithmetic}}, + year={2019}, + url={https://doi.org/10.1109/IEEESTD.2019.8766229}, + month={July} +} + +@online{iana2019hash, + author={IANA}, + title={{Hash Function Textual Names}}, + url={https://www.iana.org/assignments/hash-function-text-names/hash-function-text-names.xhtml}, + year={2019} +} + +@online{iana2019signature, + author={IANA}, + title={{Transport Security Layer (TLS) Parameters -- TLS SignatureScheme}}, + url={https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-signaturescheme}, + year={2019}, + note={Note the table \textit{Description} column} +} + +@misc{carion2019json, + series={Request for Comments}, + number={draft-json-schema-language-02}, + howpublished={RFC Draft}, + note={{RFC Editor}}, + url={https://tools.ietf.org/html/draft-json-schema-language-02}, + author={U. Carion}, + title={{JSON Schema Language}}, + year={2019}, + note={accessed 2019-09-27} +} + +@misc{rfc8259, + series = {Request for Comments}, + number = 8259, + howpublished = {RFC 8259}, + publisher = {RFC Editor}, + doi = {10.17487/RFC8259}, + url = {https://rfc-editor.org/rfc/rfc8259.txt}, + author = {Tim Bray}, + title = {{The JavaScript Object Notation (JSON) Data Interchange Format}}, + pagetotal = 16, + year = 2017, + month = dec, + abstract = {JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance.}, +} + + +@misc{rfc9100, + series = {Request for Comments}, + number = 9100, + howpublished = {RFC 9100}, + publisher = {RFC Editor}, + doi = {10.17487/RFC9100}, + url = {https://rfc-editor.org/rfc/rfc9100.txt}, + author = {Carsten Bormann}, + title = {{Sensor Measurement Lists (SenML) Features and Versions}}, + pagetotal = 7, + year = 2021, + month = aug, + abstract = {This short document updates RFC 8428, "Sensor Measurement Lists (SenML)", by specifying the use of independently selectable "SenML Features" and mapping them to SenML version numbers.}, +} \ No newline at end of file diff --git a/5.0 Draft/SysD/ServiceRegistry/figures/arrowhead_logo.pdf b/5.0 Draft/SysD/ServiceRegistry/figures/arrowhead_logo.pdf new file mode 100644 index 0000000..792e60c Binary files /dev/null and b/5.0 Draft/SysD/ServiceRegistry/figures/arrowhead_logo.pdf differ diff --git a/5.0 Draft/SysD/ServiceRegistry/serviceregistry_sysd.pdf b/5.0 Draft/SysD/ServiceRegistry/serviceregistry_sysd.pdf new file mode 100644 index 0000000..20b1971 Binary files /dev/null and b/5.0 Draft/SysD/ServiceRegistry/serviceregistry_sysd.pdf differ diff --git a/5.0 Draft/SysD/ServiceRegistry/serviceregistry_sysd.tex b/5.0 Draft/SysD/ServiceRegistry/serviceregistry_sysd.tex new file mode 100644 index 0000000..5de396d --- /dev/null +++ b/5.0 Draft/SysD/ServiceRegistry/serviceregistry_sysd.tex @@ -0,0 +1,228 @@ +\documentclass[a4paper]{arrowhead} + +\usepackage[yyyymmdd]{datetime} +\usepackage{etoolbox} +\usepackage[utf8]{inputenc} +\usepackage{multirow} +\usepackage{hyperref} + +\renewcommand{\dateseparator}{-} + +\setlength{\parskip}{1em} + +%% Special references +\newcommand{\fref}[1]{{\textcolor{ArrowheadBlue}{\hyperref[sec:functions:#1]{#1}}}} +\newcommand{\mref}[1]{{\textcolor{ArrowheadPurple}{\hyperref[sec:model:#1]{#1}}}} +\newcommand{\pdef}[1]{{\textcolor{ArrowheadGrey}{#1\label{sec:model:primitives:#1}\label{sec:model:primitives:#1s}\label{sec:model:primitives:#1es}}}} +\newcommand{\pref}[1]{{\textcolor{ArrowheadGrey}{\hyperref[sec:model:primitives:#1]{#1}}}} + +\newrobustcmd\fsubsection[3]{ + \addtocounter{subsection}{1} + \addcontentsline{toc}{subsection}{\protect\numberline{\thesubsection}function \textcolor{ArrowheadBlue}{#1}} + \renewcommand*{\do}[1]{\rref{##1},\ } + \subsection*{ + \thesubsection\quad + operation + \textcolor{ArrowheadBlue}{#1} + (\notblank{#2}{\mref{#2}}{}) + \notblank{#3}{: \mref{#3}}{} + } + \label{sec:functions:#1} +} +\newrobustcmd\msubsection[2]{ + \addtocounter{subsection}{1} + \addcontentsline{toc}{subsection}{\protect\numberline{\thesubsection}#1 \textcolor{ArrowheadPurple}{#2}} + \subsection*{\thesubsection\quad#1 \textcolor{ArrowheadPurple}{#2}} + \label{sec:model:#2} \label{sec:model:#2s} \label{sec:model:#2es} +} + +\begin{document} + +%% Arrowhead Document Properties +\ArrowheadTitle{Service Registry Core System} +\ArrowheadType{System Description} +\ArrowheadTypeShort{SysD} +\ArrowheadVersion{5.0.0} +\ArrowheadDate{\today} +\ArrowheadAuthor{Rajmund Bocsi} +\ArrowheadStatus{DRAFT} +\ArrowheadContact{rbocsi@aitia.ai} +\ArrowheadFooter{\href{www.arrowhead.eu}{www.arrowhead.eu}} +\ArrowheadSetup +%% + +%% Front Page +\begin{center} + \vspace*{1cm} + \huge{\arrowtitle} + + \vspace*{0.2cm} + \LARGE{\arrowtype} + \vspace*{1cm} + + %\Large{Service ID: \textit{"\arrowid"}} + \vspace*{\fill} + + % Front Page Image + %\includegraphics{figures/TODO} + + \vspace*{1cm} + \vspace*{\fill} + + % Front Page Abstract + \begin{abstract} + This document provides system description for the \textbf{Service Registry Core System}. + \end{abstract} + + \vspace*{1cm} + + \end{center} + +\newpage +%% + +%% Table of Contents +\tableofcontents +\newpage +%% + +\section{Overview} +\label{sec:overview} +\color{black} +This document describes the Service Registry core system, which exists to enable service discovery within an Eclipse Arrowhead Local Cloud (LC). Example of such interactions is a provider system offering some kind of service for use by other systems in the LC. This core system provides the data storage functionality for the information related to the currently and actively offered services within the Local Cloud. It also stores information about the systems that offer and/or can use the previously mentioned services, and optionally data about the devices on which those systems are running. + +The rest of this document is organized as follows. +In Section \ref{sec:prior_art}, we reference major prior art capabilities +of the system. +In Section \ref{sec:use}, we describe the intended usage of the system. +In Section \ref{sec:properties}, we describe fundamental properties +provided by the system. +In Section \ref{sec:delimitations}, we describe delimitations of capabilities +of the system. +In Section \ref{sec:services}, we describe the abstract services produced by the system. +In Section \ref{sec:security}, we describe the security capabilities +of the system. + +\subsection{Significant Prior Art} +\label{sec:prior_art} + +The strong development on cloud technology and various requirements for digitization and automation has led to the concept of Local Clouds (LC). + +\textit{"The concept takes the view that specific geographically local automation tasks should be encapsulated and protected."} \cite{jerker2017localclouds} + +One of the main building blocks when realizing such Local Cloud is the capability of storing and maintaining information about the systems and services belonged to the given LC. + +The previous versions of the Service Registry (4.6.x) are very similar to this version, however there are some key differences, even in conceptual level: + +\begin{itemize} + \item There was no data storage separation requirement: the Service Registry's data storage was interconnected to other systems' storage. In the current version, data storage separation is mandatory. + \item Every service definition contained exactly one operation. In the current version, a service definition can consist of several operations. + \item The optional device information storage (and system information storage as well, to an extent) was handled by different systems. In the current version, the Service Registry handles all three level (service instances, systems, devices). + \item Service access information (e.g. domain name or IP address) was tied to the system that provides that service, and only one such address could be specified. In the current version, service access information is tied to the interface of a service instance, and multiple addresses can be provided. + \item Service interface representation was very rudimentary, a much sophisticated approach is used in the current version. + \item X.509 certificate trust chains was used as authentication mechanism. The current version can support any type of authentication methods by using a dedicate Authentication Provider core system. +\end{itemize} + +\subsection{How This System Is Meant to Be Used} +\label{sec:use} + +Service Registry is a mandatory core system of Eclipse Arrowhead Local Cloud and is responsible for the fundamental service discovery functionality. Systems and services (and devices) are being discoverable for other systems by consuming the services provided by Service Registry core system. + +An application or other core/support system is required to register itself and its services into Service Registry if it is designed to be part of the Local Cloud and to unregister before shutdown or when it does not intend to continue to provide its services. + +\subsection{System functionalities and properties} +\label{sec:properties} + +\subsubsection {Functional properties of the system} +Service Registry solves the following needs to fulfill the requirements of service/system/device discovery. + +\begin{itemize} + \item Enables the application and other core/support systems to register themselves in order to being part of the Local Cloud. + \item Enables the application and other core/support systems to unregister themselves from the Local Cloud. + \item Enables the application and other core/support system to register the device on which the system is running. + \item Enables the application and other core/support system to unregister the device on which the system is running (only if no other systems belongs to that device). + \item Enables the application and other core/support systems to publish their services within the Local Cloud. + \item Enables the application and other core/support systems to revoke their services from the Local Cloud. + \item Makes the offered services/systems/devices queryable for other systems within the Local Cloud. +\end{itemize} + +\subsubsection {Non functional properties of the system} +If an Authentication Provider (AP) is present in the Local Cloud, the Service Registry will use AP's service(s) to verify a requester system before responding to its request. + +\subsubsection {Data stored by the system} +In order to achieve the mentioned functionalities, Service Registry is capable to store the following information set: + +\begin{itemize} + \item \textbf{Device}: name, various types (e.g. MAC address) of addresses of the device and custom meta data. + \item \textbf{System}: name, version, various types (e.g. IP address) of addresses of the system, expiration date and time, an optional reference to the device on which the system is running, custom meta data. + \item \textbf{Service definition}: name. + \item \textbf{Interface}: name, communication protocol, optional validation data. + \item \textbf{Service instance}: name, service definition and system reference, version, expiration date and time, instance level custom meta data, interface reference, security policy, and interface-related data (e. g. IP addresses, port, base path, content type, input and output data models). +\end{itemize} + +\subsection{Important Delimitations} +\label{sec:delimitations} + +\begin{itemize} + \item Names (device name, system name, service definition name, service instance name, interface name) must be unique in the Local Cloud. + \item If the Local Cloud does not contain a Authentication Provider, there is no way for the Service Registry to verify the requester system. In that case, the Service Registry will consider the authentication data comes from the requester as valid. + \item If the Local Cloud contains a Service Orchestration core system, only "public" services (such as the \textit{orchestration} service) can be queried directly from the Service Registry by the application systems. For any "non-public" services the application systems need to orchestrate. "Public" services should be marked in the Service Registry, for example using a service instance meta data entry. +\end{itemize} + +\newpage + +\section{Services produced} +\label{sec:services} + +\msubsection{service}{service-discovery} +The purpose of this service is to lookup, publish and revoke provided services. The service is offered for both application and core/support systems. + +\msubsection{service}{system-discovery} +The purpose of this service is to lookup, publish and revoke systems that are part of (or wants to be part of) the Local Cloud. The service is offered for both application and core/support systems. + +\msubsection{service}{device-discovery} +The purpose of this service is to lookup, publish and revoke devices on which the Local Cloud's systems are running. The service is offered for both application and core/support systems. + +\msubsection{service}{service-registry-management} +Recommended service. Its purpose is to manage service definitions, service instances, interfaces, systems and devices in bulk. The different operations provide querying, registering and unregistering functionalities. The service is offered for administrative support systems. + +\msubsection{service}{monitor} +Recommended service. Its purpose is to give information about the provider system. The service is offered for both application and core/support systems. + +\newpage + +\section{Security} +\label{sec:security} + +For authentication, the Service Registry utilizes an other core system, the Authentication Provider's service to verify the identities of the requester systems. If no Authentication Provider is deployed into the Local Cloud, the Service Registry trusts the requester system self-provided identity. + +For authorization, in secure mode, the Service Registry only allows to lookup "public" services. Information about all other services (including the \textit{service-registry-management}) are only available through orchestration. Systems can only register/unregister themselves and their services/device. In insecure mode, all services are available for lookup. + +The implementation of the Service Registry can decide about the encryption of the connection between the Service Registry and other systems. + +\newpage + +\bibliographystyle{IEEEtran} +\bibliography{bibliography} + +\newpage + +\section{Revision History} +\subsection{Amendments} + +\noindent\begin{tabularx}{\textwidth}{| p{1cm} | p{3cm} | p{2cm} | X | p{4cm} |} \hline +\rowcolor{gray!33} No. & Date & Version & Subject of Amendments & Author \\ \hline + +1 & YYYY-MM-DD & \arrowversion & & Xxx Yyy \\ \hline +\end{tabularx} + +\subsection{Quality Assurance} + +\noindent\begin{tabularx}{\textwidth}{| p{1cm} | p{3cm} | p{2cm} | X |} \hline +\rowcolor{gray!33} No. & Date & Version & Approved by \\ \hline + +1 & YYYY-MM-DD & \arrowversion & \\ \hline + +\end{tabularx} + +\end{document} \ No newline at end of file