Doc/clarify api doc (#41)

* Updated API documentation * Documentation: Added "Keys for accessing DGC Gateway" section #39
eu-digital-green-certificates · May 27, 2021 · 14afe2f · 14afe2f
1 parent 420aeb7
commit 14afe2f
Show file tree

Hide file tree

Showing 5 changed files with 62 additions and 12 deletions.
diff --git a/README.md b/README.md
@@ -26,16 +26,36 @@ The DGC Verifier Service is part of the national backends and caches the public
 
 ## Development
 
+**Note:** The verifier service needs a connection to the gateway in order to run. There is no standalone version available.
+
 ### Prerequisites
 
 - [Open JDK 11](https://openjdk.java.net)
 - [Maven](https://maven.apache.org)
 - [Docker](https://www.docker.com)
-- An installation of the [DGCG](https://https://github.com/eu-digital-green-certificates/dgc-gateway)
-- Keys to access the [DGCG](https://https://github.com/eu-digital-green-certificates/dgc-gateway) via the
+- An installation of the [DGCG](https://github.com/eu-digital-green-certificates/dgc-gateway)
+- Keys to access the [DGCG](https://github.com/eu-digital-green-certificates/dgc-gateway) via the
   [DGCG Connector](https://github.com/eu-digital-green-certificates/dgc-lib) of the [DGC-lib](https://github.com/eu-digital-green-certificates/dgc-lib)
 - Authenticate to [Github Packages](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry)
 
+#### Needed keys for accessing the DGC Gateway 
+<p id="access-keys"></p>
+For accessing the DGC Gateway via the DGC Connector you need the following keys in place:
+
+- The public key of the used Gateway. The public key should be stored in the *tls_trust_store*. If you use one of the 
+  provided gateways, you will get the public key as .pem from DIGIT. This .pem needs to be converted into pkcs12 format:
+  ````
+  openssl pkcs12 -export -in pub_tls.pem -name trust -out tls_trust_store.p12
+  ````
+- Your key pair for accessing the Gateway stored in *tls_key_store*. This needs to be generated by yourself and then whitelisted by operations team (see [onboarding manual](https://github.com/eu-digital-green-certificates/dgc-participating-countries/blob/main/gateway/OnboardingChecklist.md) of the Gateway). To use it in the verifier service this needs to be converted as well into pkcs12 format:
+  ````
+  openssl pkcs12 -export -in tls.pem -inkey tls_private.pem -name 1 -out tls_key_store.p12
+  ````
+
+- The public key of the TrustAnchor of the Gateway. If you use one of the provided Gateways you will get it as well, at onboarding. The key should be stored in a jks file.
+
+For more information on how to generate certificates for DGC Gateway and how to run your own local one, please have a look in the documentation of the [Gateway](https://github.com/eu-digital-green-certificates/dgc-gateway).
+
 #### Authenticating in to GitHub Packages
 
 As some of the required libraries (and/or versions are pinned/available only from GitHub Packages) You need to authenticate
@@ -57,10 +77,10 @@ The following steps need to be followed
   - Use your GitHub username as username
   - Use the generated PAT as password
 
-**Note:** The verifier service needs the connection to the gateway in order to run. There is no standalone version available.
+
 
 For further information about the keys and certificates needed, please refer to the documentation of the 
-[DGCG](https://https://github.com/eu-digital-green-certificates/dgc-gateway) and the 
+[DGCG](https://github.com/eu-digital-green-certificates/dgc-gateway) and the 
 [DGC-lib](https://github.com/eu-digital-green-certificates/dgc-lib)
 
 ### Build
@@ -83,7 +103,7 @@ mvn clean install
 All required dependencies will be downloaded, the project build and the artifact stored in your local repository.
 #### Run with docker
 * Perform maven build as described above
-* Place the keys and certificates named above into the ***certs*** folder.
+* Place the keys and certificates named [above](#access-keys) into the ***certs*** folder.
 * Adjust the values in the [docker-compose.yml](docker-compose.yml) file to fit the url for the gateway you use and 
   your keys and certificates you have to access it.
   ```yaml

diff --git a/certs/PlaceYourGatewayAccessKeysHere.md b/certs/PlaceYourGatewayAccessKeysHere.md
@@ -1,7 +1,7 @@
 ### Note: 
 
 If you want to run the verifier service via the given docker-compose file, place your keys to access the 
-[DGCG](https://https://github.com/eu-digital-green-certificates/dgc-gateway) in this folder and adjust the file names
+[DGCG](https://github.com/eu-digital-green-certificates/dgc-gateway) in this folder and adjust the file names
 in the [docker-compose.yml](../docker-compose.yml) file.
 
 Further information can be found in the [README](../README.md)
diff --git a/docs/dgca-verifier-service.md b/docs/dgca-verifier-service.md
@@ -1,5 +1,5 @@
 # European Digital Green Certificate Applications 
-##DGCA-Verifier-Service
+## DGCA-Verifier-Service
 
 ### Intention
 The DGCA-Verifier-Service provides a template implementation for a member state backend service for a verifier application.

diff --git a/src/main/java/eu/europa/ec/dgc/verifier/restapi/controller/ContextController.java b/src/main/java/eu/europa/ec/dgc/verifier/restapi/controller/ContextController.java
@@ -22,6 +22,7 @@
 
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.ExampleObject;
 import io.swagger.v3.oas.annotations.media.Schema;
 import io.swagger.v3.oas.annotations.responses.ApiResponse;
 import java.io.IOException;
@@ -54,7 +55,18 @@ public class ContextController {
                 description = "Returns the current context for the verifier app.",
                 content = @Content(
                     mediaType = MediaType.APPLICATION_JSON_VALUE,
-                    schema = @Schema(implementation = String.class)))
+                    schema = @Schema(implementation = String.class),
+                    examples = {@ExampleObject(value = "{\"origin\":\"DE\",\"versions\":{\"default\":{\"privacyUrl\":"
+                          + "\"https://publications.europa.eu/en/web/about-us/legal-notices/eu-mobile-apps\","
+                          + "\"context\":{\"url\":\"https://dgca-verifier-service.example.com/context\",\"pubKeys\":"
+                          + "[\"lKdU1EbQubxyDDm2q3N8KclZ2C94+3eI=\","
+                          + "\"r/mIkG3eEpVdm+u/ko/cwxzOMo1bkA5E=\"]},\"endpoints\":{\"status\":{\"url\":"
+                          + "\"https://dgca-verifier-service.example.com/signercertificateStatus\",\"pubKeys\":"
+                          + "[\"lKdU1EbQubxyDDm2q3N8KclZ2C94+3eI=\","
+                          + "\"r/mIkG3eEpVdm+u/ko/cwxzOMo1bkA5E=\"]},\"update\":{\"url\":"
+                          + "\"https://dgca-verifier-service.example.com/signercertificateUpdate\",\"pubKeys\":"
+                          + "[\"lKdU1EbQubxyDDm2q3N8KclZ2C94+3eI=\","
+                          + "\"r/mIkG3eEpVdm+u/ko/cwxzOMo1bkA5E=\"]}}},\"0.1.0\":{\"outdated\":true}}}")}))
         }
     )
     public ResponseEntity<String> getContext() {

diff --git a/src/main/java/eu/europa/ec/dgc/verifier/restapi/controller/SignerInformationController.java b/src/main/java/eu/europa/ec/dgc/verifier/restapi/controller/SignerInformationController.java
@@ -25,6 +25,7 @@
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.enums.ParameterIn;
+import io.swagger.v3.oas.annotations.headers.Header;
 import io.swagger.v3.oas.annotations.media.ArraySchema;
 import io.swagger.v3.oas.annotations.media.Content;
 import io.swagger.v3.oas.annotations.media.ExampleObject;
@@ -59,7 +60,11 @@ public class SignerInformationController {
      */
     @GetMapping(path = "/signercertificateUpdate", produces = MediaType.TEXT_PLAIN_VALUE)
     @Operation(
-        summary = "Gets one signer certificate.",
+        summary = "Gets one signer certificate and a resume token.",
+        description = "This method return one signer certificate and a corresponding resume token. In order to "
+            + "download all available certificates, start calling this method without the resume token set. Then repeat"
+            + " to call this method, with the resume token parameter set to the value of the last response. When you "
+            + "receive a 204 response you have downloaded all available certificates.",
         tags = {"Signer Information"},
         parameters = {
             @Parameter(
@@ -71,7 +76,17 @@ public class SignerInformationController {
         responses = {
             @ApiResponse(
                 responseCode = "200",
-                description = "Returns a filtered list of trusted certificates.",
+                description = "Returns one signer certificate and as header parameter a resume token and the kid. "
+                    + "There might be more certificates available to download. Repeat the request with the resume "
+                    + "token parameter set to the actual value, until you get a 204 response.",
+                headers = {
+                    @Header(
+                        name = "X-RESUME-TOKEN",
+                        description = "Token can be used to resume the download of the certificates."),
+                    @Header(
+                        name = "X-KID",
+                        description = "The kid of the returned certificate.")
+                },
                 content = @Content(
                     mediaType = MediaType.TEXT_PLAIN_VALUE,
                     schema = @Schema(implementation = String.class),
@@ -114,12 +129,15 @@ public ResponseEntity<String> getSignerCertificateUpdate(
      */
     @GetMapping(path = "/signercertificateStatus", produces = MediaType.APPLICATION_JSON_VALUE)
     @Operation(
-        summary = "Gets list of kids from all valid certificates.",
+        summary = "Gets a list of kids from all valid certificates.",
         tags = {"Signer Information"},
+        description = "Gets a list of kids from all valid certificates. This list can be used to verify, that the "
+            + "downloaded certificates are still valid. If a kid of a downloaded certificate is not part of the list, "
+            + "the certificate is not valid any more.",
         responses = {
             @ApiResponse(
                 responseCode = "200",
-                description = "Returns a filtered list of trusted certificates.",
+                description = "Returns a list of kids of all valid certificates.",
                 content = @Content(
                     mediaType = MediaType.APPLICATION_JSON_VALUE,
                     array = @ArraySchema(schema = @Schema(implementation = String.class)),