doc(core): add readme and update handbook and history

1 files changed, 139 insertions, 0 deletions

diff --git a/infos/ms-connector/readme_1.3.5.md b/infos/ms-connector/readme_1.3.5.md
new file mode 100644
index 00000000..5d012783
--- /dev/null
+++ b/infos/ms-connector/readme_1.3.5.md
@@ -0,0 +1,139 @@
+# MS-Connector v1.3.5 Release vom 21.11.2022
+
+Der MS-Connector implementiert eine Bridge zwischen dem österreichischen E-ID System und dem eIDAS Framework um ausländischen Benutzern eine Anmeldung am österreichischen Service-Providern zu ermöglichen.
+
+### Änderungen in dieser Version
+
+  - Zusätzliche Prüfung für ERnP Antworten ergänzt um zwischen beendeten und ins ZMR gekittete Entities zu unterscheiden
+        - Ins ZMR gekittete Entities werden wie ZMR Entities behandelt
+  - Optionale Identifikation von ZMR Entities für Updates nur mehr auf Basis der bPK _ZP_ hinzugefügt
+  - Deaktivierung von privaten Service-Providern für spezifische Länder hinzugefügt
+  - GELF Appender für logback Framework hinzugefügt
+  - Optimierung des Statistiklog
+        - Unterscheidung zwischen automatischer und benutzer-initiiter ERnP Eintragung
+        - Zusätzlicher JSON basierter Statistiklog mit weiteren Details zum Matching
+  - Aktualisierung von Drittherstellerbibliotheken
+        - EAAF-Components 1.3.8
+        - SpringBoot 2.5.14
+        - Spring-Framework 5.3.23
+        - Apache CXF 3.5.4
+        - commons-text 1.10.0
+        - jackson-databind 2.13.4.2
+        - log4j 2.19.0
+        - logback-gelf 4.0.2
+
+
+### Durchführen eines Updates 
+
+Nachfolgend finden Sie die erforderlichen Schritte für das Update eines bestehenden MS-specific eIDAS Connectors auf die aktuelle Version 1.3.5. Das vollständige Handbuch mit allen Konfigurationsparametern finden Sie im Releasepackage im Verzeichnis: _infos/handbook/_
+
+### Ausgehend von einer bestehenden Version 1.3.4 
+
+1. Stoppen Sie die *MS-Connector* Applikation und fertigen Sie eine Sicherungskopie Ihrer Applikation inklusive Konfiguration an
+
+2. Entpacken Sie das Releasepacket *ms_specific_connector-1.3.5-dist.zip* in ein temporäres Verzeichnis welches in weiterer Folge __MsConnectorPackage__ bezeichnet wird.
+
+3. Kopieren sie die Applikation __MsConnectorPackage__/ms_connector.war nach in das Applikationsverzeichnis ihres Applikationsservers
+
+4. Aus dem ID Austria Projekt kommt es zu einer Anpassung an der Frontend/Backend Schnittstelle des ID Austria System (BRZ/BM.I) welche in weiterer Folge auch Einfluss auf den MS-Connector hat. Hintergrund ist, dass vom MS-Connector ein AuthBlock für das ID Austria System erzeugt und signiert wird welcher anschließend im ID Austria System verifiziert wird. Im Zuge der Schnittstellenanpassung kommt es zu einer Änderung des Inhalts des AuthBlock. Die MS-Connector Version 1.3.3 unterstützt sowohl das alte als auch das neue AuthBlock Format wobei das zu verwendete Version per Konfiguration geändert werden kann. Da aus aktueller Sicht offen ist ab wann das ID Austria Backend das neue Format unterstützt und ob eine parallele Unterstützung beide Formate durch das Backend umgesetzt wird, muss der MS-Connector bis auf weiteres mit dem Konfigurationsparameter ```eidas.ms.auth.eIDAS.authblock.use.legacy.version=true```, für die Erstellung des alten AuthBlock Formats, betrieben werden.
+
+5. Neue optionale Konfigurationsparameter
+   
+   - ```eidas.ms.auth.eIDAS.node_v2.proxyservices.privatesp.notsupported```
+   - ```eidas.ms.auth.eIDAS.zmrclient.req.update.with.bpk.only```
+   
+6. Neuer erweiterter Statisiklogger hinzugefügt
+
+   Zusätzlich zum bestehenden Statistiklogger wurde in neuer JSON basierter Logger ergänzt welcher zusätzliche Informationen zum Matching Prozess beinhaltet. Der Statistiklogger kann in er Logger-Konfiguration *logback_config.xml* so konfiguriert werden dass die Statistikinformationen in eine separate Datei geschrieben werden.
+
+   ```
+     <logger name="at.asitplus.eidas.specific.core.logger.AdvancedStatisicLogger" additivity="false" level="info">
+       <appender-ref ref="statisticJson"/>
+     </logger>   
+   ```
+
+   ```
+     <appender name="statisticJson" class="ch.qos.logback.core.rolling.RollingFileAppender">
+       <!--See also http://logback.qos.ch/manual/appenders.html#RollingFileAppender-->
+       <File>${catalina.base}/logs/eidas-ms-statistic-json.log</File>
+       <encoder>
+         <pattern>%m%n</pattern>
+       </encoder>
+       <rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
+         <maxIndex>9999</maxIndex>
+         <FileNamePattern>${catalina.base}/logs/eidas-ms-statistic-json.log.%i</FileNamePattern>
+       </rollingPolicy>
+       <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
+         <MaxFileSize>10000KB</MaxFileSize>
+       </triggeringPolicy>
+     </appender>
+   ```
+
+   
+
+   Je Anmeldevorgang wird eine Logzeile mit Informationen zum entsprechenden Anmeldeprozess geschrieben wobei die Log-Message folgende Daten enthält:
+
+   ```
+   {
+     "timestamp": "2022.10.25-07:02:11",                ... Datum und Uhrzeit der Anmeldung    
+     "txId": "48ccb404-4bb6-46fa-a2db-69b32235bc3c",     ... technische eindeutige TransactionsId
+     "entityid": "https://eid.egiz.gv.at/authHandler/restricted/eidas/metadata",  ... eindeutiger Identifier des anfragenden System (z.B. IDA AuthHandler)
+     "unique-sp-id": "http://test.com/test#mandates4",     ... eindeutiger Identifier der Anwendung
+     "success": {                                          ... im Falle einer erfolgreichen Anmeldung
+       "spSector": "urn:publicid:gv.at:cdid+ZP-MH",            ... bPK Bereich der Anwendung
+       "ccc": "EE"                                             ... Land des EU Bürgers
+     },
+     "error": {                                            ... im Falle eines Fehlers
+       "code": "auth.21",                                       ... Fehlercode
+       "msg": "The authentication process was stopped by user"  ... Fehlermessage
+     },
+     "idenityMatching": {                            ... Informationen zum Matchingprozess falls dieses gestartet wurde
+       "finalMatchingMethod": "BY_PERSONALID",        ... Letzte durchgeführte Operation welche zum erfolgreichen Match oder einen Abbruch durch Benutzer geführt hat (Codes sind identisch zum aktuellen Log)
+       "matchingProcessDetails": {                      ... Details zur Suche und zum Benutzerverhalten
+         "BY_PERSONALID": {                              ... Ergebnisse der Suche mittels PersonalIdentifier
+           "zmr": 0,                                                       
+           "ernp": 1
+         },
+         "BY_COUNTRY_SPECIFIC": null,                    ... Ergebnisse der Suche entsprechend länderspezifischer Eigenschaften falls durchgeführt
+         "BY_MDS": null,                                 ... Ergebnisse der Suche mittels MDS
+         "USE_IDA": false,                               ... true falls ein Match mittels Handy-Signatur oder IDA versucht wurde
+         "USE_EIDAS": 0,                                 ... Anzahl der alternativen eIDAS Anmeldungen welche versucht wurden
+         "USE_ADDRESS": 0                                ... Anzahl der Adresssuchen, welche mit Suchdaten durchgeführt wurden
+       }
+     }
+   }
+   ```
+
+   Folgende Matching-Status werden durch den Statistik-Logger gesetzt:
+
+   - BY_PERSONALID                               --> Matching über eIDAS PersonalIdentifier
+
+   +    BY_COUNTRY_SPECIFIC                   --> Matching über länderspezifische Eigenschaften (z.B. für DE)
+   +    BY_ID_AUSTRIA                                 --> Matching via ID Austria Login
+   +    BY_EIDAS                                           --> Matching via alternativer eIDAS Anmeldung
+   +    BY_ADDRESS                                    --> Matching über Adresssuche
+   +    BY_NEW_ERNP_ENTRY                   --> falls die Person neu angelegt wurde
+   +    BY_USER_TO_NEW_ERNP_ENTRY  -->falls die Person durch Klick der Schaltfläche in der GUI neu angelegt wurde
+   +    CANCELED_BY_USER                      --> Anmeldeprozess wurde durch den Benutzer bei GUI basierten Matching-Prozess abgebrochen
+   +    NO_REQUIRED                                --> Falls für den aktuellen Anmeldeprozess kein / noch kein Matching erforderlich war (z.B. Fehler am eIDAS Node vor Matching)
+
+   
+
+   **Technische Einschränkungen**
+
+   Benutzerabbrüche welche durch schließen des Browserfensters erfolgen sind nicht im Statistiklog enthalten da in diesem Fall der Anmeldeprozess nicht mehr aus dem Browser zurückkehrt und serverseitig nach einem Timeout geschlossen wird.  Eine Abschätzung zur Anzahl der Anmeldeprozesse welche über dieses Verhalten abgebrochen werden lässt sich jedoch indirekt aus dem technischen Log ableiten. Hierfür kann, innerhalb des selben Zeitraums, die Anzahl der Logzeilen mit dem Message:
+
+   ```
+   a.a.e.s.m.a.e.v.s.RegisterSearchService | Matching operation: seachByPersonalId results: 
+   ```
+
+   mit der Anzahl der Statistiklog Einträge verglichen werden. Eine Differenz der Anzahl dieser beiden Werte spiegelt die Abbrüche durch schließen des Browserfenster während der Matchingschritte wider.
+
+   
+
+   
+
+   
+
+   
+