Copied instructions for adding Web eID authentication token validation library to the project from web-eid-authtoken-validation-dotnet repository.

WE2-572

Signed-off-by: Mihkel Kivisild [email protected]

Author: Mihkel Kivisild

example/README.md

@@ -13,42 +13,77 @@ The ASP.NET web application makes use of the following technologies:
 -   the Web eID JavaScript library [_web-eid.js_](https://github.com/web-eid/web-eid.js),
 -   the digital signing library [_libdigidocpp_](https://github.com/open-eid/libdigidocpp/tree/master/examples/DigiDocCSharp).
 
-Note that for including the Web eID authentication token validation library as a nuget package you need to have added a Package Source with the following address to the NuGet Package Manager:
-https://gitlab.com/api/v4/projects/35362906/packages/nuget/index.json
-
 ## Quickstart
 
 Complete the steps below to run the example application in order to test authentication and digital signing with Web eID.
 
-### 1. Configure the origin URL
+### 1. Add the Web eID authentication token validation library to your project
+
+#### When using Visual Studio
+
+1. Configure Web eID GitLab package repository as a NuGet package source.  
+   In MS Visual Studio, go to the **Tools** > **NuGet Package Manager** > **Package Manager Settings** menu command. Select **Package Sources** and add a new source. Name it _Web eID GitLab_ and set the _Source_ URL to `https://gitlab.com/api/v4/projects/35362906/packages/nuget/index.json`.
+
+2. Install the `WebEid.Security` NuGet package.  
+   You can install the package either from the GUI or the Package Manager Console.
+
+  - From GUI:  
+    Right-click the project in the Solution Explorer where you want to install the Web eID dependency. Select **Manage NuGet Packages**. Choose the _Web eID GitLab_ package source you added earlier from the _Package source_ dropdown. Then, install the `WebEid.Security` package.
+     
+
+  - From Package Manager Console:  
+    Run the following command:
+    ```
+    Install-Package WebEid.Security
+    ```
+
+#### When using `dotnet` CLI
+
+In case you prefer using command line tools, you can add the package source using the `dotnet` CLI with the following command:
+
+```
+dotnet nuget add source https://gitlab.com/api/v4/projects/35362906/packages/nuget/index.json --name "Web eID GitLab"
+```
+
+And then in `src` folder run the following command to ensure all packages are installed:
+
+```
+dotnet restore WebEid.AspNetCore.Example.sln
+```
+
+**Note:** When you install a package, NuGet records the dependency in either your project file or a `packages.config` file, depending on the selected package management format (`Packages.config` or `PackageReference`).
+
+For more detailed information on different methods of installing NuGet packages, refer to [Microsoft's official documentation](https://learn.microsoft.com/en-us/nuget/consume-packages/overview-and-workflow#ways-to-install-a-nuget-package).
+
+### 2. Configure the origin URL
 
 One crucial step of the Web eID authentication token validation algorithm is verifying the token signature. The value that is signed contains the site origin URL (the URL serving the web application) to protect against man-in-the-middle attacks. Hence the site origin URL must be configured in application settings.
 
-To configure the origin URL, add `OriginUrl` field in the application settings file  `appsettings.json`  as follows:
+To configure the origin URL, add `OriginUrl` field in the application settings file in either `appsettings.Development.json` for `Development` profile or `appsettings.json` for `Production` profile as follows:
 ```json
 {
   "OriginUrl": "https://example.org"
 }
 ```
-Note that the URL **must not end with a slash** `/`.
+Note that the URL **must not end with a slash** `/` and the URL must be the same as the `applicationUrl` in `launchSettings.json`. When you change the `OriginUrl`, also change the `applicationUrl` in `launchSettings.json`.
 
-### 2. Configure the trusted certificate authority certificates
+### 3. Configure the trusted certificate authority certificates
 
-The algorithm, which performs the validation of the Web eID authentication token, needs to know which intermediate certificate authorities (CA) are trusted to issue the eID authentication certificates. CA certificates are loaded from `.cer` files in the profile-specific subdirectory of the  [`Certificates` resource directory](https://github.com/web-eid/web-eid-asp-dotnet-example/src/WebEid.AspNetCore.Example/Certificates). By default, Estonian eID test CA certificates are included in the `Development` profile and production CA certificates in the `Production` profile.
+The algorithm, which performs the validation of the Web eID authentication token, needs to know which intermediate certificate authorities (CA) are trusted to issue the eID authentication certificates. CA certificates are loaded from `.cer` files in the profile-specific subdirectory of the  [`Certificates` resource directory](https://github.com/web-eid/web-eid-asp-dotnet-example/tree/main/src/WebEid.AspNetCore.Example/Certificates). By default, Estonian eID test CA certificates are included in the `Development` profile and production CA certificates in the `Production` profile.
 
 In case you need to provide your own CA certificates, add the `.cer` files to the  `src/WebEid.AspNetCore.Example/Certificates/{Dev,Prod}` profile-specific directory.
 
-### 3. Setup the `libdigidocpp` library for signing
+### 4. Setup the `libdigidocpp` library for signing
 
 `libdigidocpp` is a library for creating, signing and verifying digitally signed documents according to XAdES and XML-DSIG standards. It is a C++ library that has [SWIG](http://swig.org/) bindings for C#.
 
 Set up the `libdigidocpp` library as follows:
 
 #### For MS Windows
 
-1.  Install the _libdigidocpp-3.17.1.msi_ package or higher. The installation packages are available from  [https://github.com/open-eid/libdigidocpp/releases](https://github.com/open-eid/libdigidocpp/releases).
+1.  Install the _libdigidocpp-4.0.0.8301.x64.msi_ package or higher. The installation packages are available from  [https://github.com/open-eid/libdigidocpp/releases](https://github.com/open-eid/libdigidocpp/releases).
 2.  Copy the C# source files from the `libdigidocpp` installation folder `include\digidocpp_csharp` to the `src\WebEid.AspNetCore.Example\DigiDoc` folder.
-3.  Copy all files from either the `x64` subfolder of the `libdigidocpp` installation folder to the example application build output folder `bin\...\net8.0` (after building, see next step). When building custom applications, choose `x64` if your application is 64-bit and `x86` if it is 32-bit.
+3.  Copy all files from the `libdigidocpp` installation folder to the example application build output folder `bin\Debug\net8.0` (after building, see next step).
 4.  When running in the `Development` profile, create an empty file named `EE_T.xml` for TSL cache as described in the [_Using test TSL lists_](https://github.com/open-eid/libdigidocpp/wiki/Using-test-TSL-lists#preconditions) section of the `libdigidocpp` wiki.
 
 #### For Ubuntu Linux
@@ -72,51 +107,49 @@ Set up the `libdigidocpp` library as follows:
 4. Copy the necessary DigiDoc C# library files into your project:
 
     ```sh
-    cp /usr/include/digidocpp_csharp/* WebEid.AspNetCore.Example/DigiDoc/
+    cp /usr/include/digidocpp_csharp/* /usr/lib/x86_64-linux-gnu/libdigidoc_csharp.so WebEid.AspNetCore.Example/DigiDoc/
     ```
 
 #### For macOS
 
-1.  Install the _libdigidocpp-3.17.1.pkg_ package or higher. The installation packages are available from  [https://github.com/open-eid/libdigidocpp/releases](https://github.com/open-eid/libdigidocpp/releases).
+1.  Install the *libdigidocpp_4.0.0.1460.pkg* package or higher. The installation packages are available from  [https://github.com/open-eid/libdigidocpp/releases](https://github.com/open-eid/libdigidocpp/releases).
 2.  Copy the C# source files from `/Library/libdigidocpp/include/digidocpp_csharp` directory to `src/WebEid.AspNetCore.Example/DigiDoc` directory.
-3.  Go to `src/WebEid.AspNetCore.Example/bin/.../net8.0` directory and create symbolic link to `/Library/libdigidocpp/lib/libdigidoc_csharp.dylib` library:
+3.  Go to `bin/Debug/net8.0` directory and create symbolic link to `/Library/libdigidocpp/lib/libdigidoc_csharp.dylib` library:
     ```cmd
     ln -s /Library/libdigidocpp/lib/libdigidoc_csharp.dylib
     ```
 
 Further information is available in the [libdigidocpp example C# application source code](https://github.com/open-eid/libdigidocpp/tree/master/examples/DigiDocCSharp) and in the [`libdigidocpp` Wiki](https://github.com/open-eid/libdigidocpp/wiki).
 
-### 4. Build the application
+### 5. Build the application
 
-You need to have the [.NET 6.0 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/6.0) installed for building the application package.
+You need to have the [.NET 8.0 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) installed for building the application package.
 Build the application by running the following command in a terminal window under the `src` directory:
 
 ```cmd
 dotnet build
 ```
 
-### 5. Choose either the  `Development`  or  `Production`  profile
+### 6. Choose either the  `Development`  or  `Production`  profile
 
 If you have a test eID card, use the  `Development`  profile. In this case access to paid services is not required, but you need to upload the authentication and signing certificates of the test card to the test OCSP responder database as described in section _[Using DigiDoc4j in test mode with the  `dev`  profile](https://github.com/web-eid/web-eid-spring-boot-example#using-digidoc4j-in-test-mode-with-the-dev-profile)_ of the Web eID Java example application documentation. The`Development` profile is activated by default.
 
 If you only have a production eID card, i.e. an eID card issued to a real person or organization, use the  `Production`  profile. You can still test authentication without further configuration; however, for digital signing to work, you need access to a paid timestamping service as described in section [_Using DigiDoc4j in production mode with the  `prod`  profile_](https://github.com/web-eid/web-eid-spring-boot-example#using-digidoc4j-in-production-mode-with-the-prod-profile) of the Web eID Java example documentation.
 
-You can specify the profile as an environment variable `ASPNETCORE_ENVIRONMENT` when running the application. To set the profile for the current session before starting the app using [`dotnet run`](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-run), use the following command:
-```cmd
-set ASPNETCORE_ENVIRONMENT=Production
-```
+You can specify the profile as an environment variable `ASPNETCORE_ENVIRONMENT` when running the application. To set the profile for the current session before starting the app using dotnet run, edit the appropriate profile in the `launchSettings.json` file located at `src/WebEid.AspNetCore.Example/Properties/`. Modify the `environmentVariables` section in the `launchSettings.json` file by setting the `ASPNETCORE_ENVIRONMENT` to `Production`.
 
-### 6. Run the application
+### 7. Run the application
 
 Run the application with the following command in a terminal window under the `src` directory:
 
 ```cmd
 dotnet run --project WebEid.AspNetCore.Example
 ```
 
-This will activate the default `Development` profile and launch the built-in `kestrel` web server on HTTPS port 5001.
+This will activate the `https` profile in the `launchSettings.json` and launch the built-in `kestrel` web server on the defined `applicationUrl`.
 
-When the application has started, open https://localhost:5001 in your preferred web browser and follow instructions on the front page.
+When the application has started, open your preferred web browser on the address defined in `launchSettings.json` on the `applicationUrl` field at `https` profile and follow instructions on the front page.
+By default the address is https://localhost:44391.
 
 ## Overview of the source code
 
@@ -129,7 +162,7 @@ The `src\WebEid.AspNetCore.Example` directory contains the ASP.NET application s
     -   digital signing,
 -   `DigiDoc`: contains the C# binding files of the `libdigidocpp` library; these files must be copied from the `libdigidocpp` installation directory `\include\digidocpp_csharp`,
 -   `Pages`: Razor pages,
--   `Services`: Web eID signing service implementation that uses `libdigidocpp`.
+-   `Signing`: Web eID signing service implementation that uses `libdigidocpp`.
 
 ## More information
 
@@ -141,10 +174,6 @@ See the [Web eID Java example application documentation](https://github.com/web-
 
 You are running in the `Development` profile, but you have not created an empty file named `EE_T.xml` for TSL cache. Creating the file is mandatory and is described in more detail in the [_Using test TSL lists_](https://github.com/open-eid/libdigidocpp/wiki/Using-test-TSL-lists#preconditions) section of the `libdigidocpp` wiki.
 
-#### Why do I get the `System.BadImageFormatException: An attempt was made to load a program with an incorrect format` error during signing?
-
-You are using `libdigidocpp` DLLs for the wrong architecture. Copy files from the `x64` subfolder of the  `libdigidocpp` installation folder to right place as described in the section _3. Setup the `libdigidocpp` library for signing_ above. In case you get this error while developing a custom 32-bit application, copy files from the `x86` subfolder instead.
-
 ## Building and running with Docker on Ubuntu Linux
 
 This section covers the steps required to build the application on an Ubuntu Linux environment and run it using Docker.
@@ -153,13 +182,13 @@ This section covers the steps required to build the application on an Ubuntu Lin
 
 Before you begin, ensure you have the following installed on your system:
 
-- .NET SDK 7.0
+- .NET SDK 8.0
 - libdigidocpp-csharp
 
 You can install them using the following command:
 
 ```sh
-sudo apt install dotnet-sdk-7.0 libdigidocpp-csharp
+sudo apt install dotnet-sdk-8.0 libdigidocpp-csharp
 ```
 
 Note: Before installing `libdigidocpp-csharp` you have to have added the RIA repository as a package source. See [For Ubuntu Linux section](#for-ubuntu-linux) for information.
@@ -177,7 +206,7 @@ To build the application, follow these steps:
 2. Copy the necessary DigiDoc C# library files into your project:
 
     ```sh
-    cp /usr/include/digidocpp_csharp/* WebEid.AspNetCore.Example/DigiDoc/
+    cp /usr/include/digidocpp_csharp/* /usr/lib/x86_64-linux-gnu/libdigidoc_csharp.so WebEid.AspNetCore.Example/DigiDoc/
     ```
 
 3. Publish the application with the Release configuration: