Develop

obp-api/src/main/docs/glossary/TPP_Certificate_Verification.md

@@ -0,0 +1,87 @@
+### TPP Certificate Verification
+
+The signing and verification flow of certificates for TPP requests is a follows:
+
+#### Generation of the Request by TPP
+
+**Step 1: Calculating the Hash for the Digest Field**
+
+* TPP creates the body of the request (e.g., JSON containing transaction or consent data).
+* TPP applies the SHA-256 algorithm to the body of the request to generate a unique hash.
+* The resulting hash is encoded in Base64 and placed in the request header under the `Digest` field.
+
+**Step 2: Creating the Signing String**
+
+* TPP prepares a signing string based on specific fields from the request header.
+* The signing string is a concatenation of the values of the signed fields in a specific format.
+* The order of the fields is critical and follows the specifications.
+
+**Step 3: Signing the Signing String**
+
+* TPP uses its RSA private key associated with its certificate to generate a digital signature.
+* The signature is applied to the signing string using the RSA-SHA256 algorithm.
+* The resulting digital signature is Base64-encoded and placed in the `Signature` field.
+
+**Step 4: Adding the Certificate to the TPP-Signature-Certificate Field**
+
+* TPP includes its public certificate in the request header under the `TPP-Signature-Certificate` field.
+* The certificate is issued by a trusted certification authority (CA) and contains the TPP's public key.
+
+**Step 5: Sending the Request to OBP**
+
+* TPP sends the complete request, including the `Digest`, `Signature`, and `TPP-Signature-Certificate` headers, to the OBP endpoint.
+
+---
+
+#### Verification of the Request by OBP
+
+**Step 1: Validating the TPP Certificate**
+
+* OBP verifies the TPP certificate included in the `TPP-Signature-Certificate` field.\
+  Steps:
+
+1. Verify the certificate's trust chain up to a trusted certification authority.
+2. Ensure the certificate is valid (not expired or revoked).
+3. Confirm the certificate is issued for the appropriate usage (e.g., digital signatures for Open Banking), based on the information from the National Bank registry (e.g., certificate SN and CA found in the `Signature` field).
+
+* **Result**: If the certificate is valid, the TPP's identity is confirmed.
+
+**Step 2: Verifying the Signature in the `Signature` Field**
+
+* OBP extracts the fields included in the signing string based on the information in the `Signature` field.
+* OBP recreates the signing string in the same format used by the TPP.
+* OBP uses the public key from the certificate in the `TPP-Signature-Certificate` field to verify the signature in the `Signature` field.
+* **Result**: If the signature is valid, the authenticity of the request is confirmed.
+
+**Step 3: Verifying the Hash in the `Digest` Field**
+
+* OBP computes its own SHA-256 hash of the received request body.
+* The computed hash is compared with the value in the `Digest` header.
+* **Result**: If the two hashes match, the integrity of the request body is confirmed.
+
+**Step 4: Authorizing the Request**
+
+* If all verifications (integrity, signature, and certificate) pass, OBP processes the request.
+* Otherwise, the request is rejected with an error message (e.g., `401 Unauthorized` or `403 Forbidden`).
+
+---
+
+#### Additional Details
+
+**How does OBP verify the signature in the `Signature` field?**
+
+1. **Extracts the public key from the `TPP-Signature-Certificate`**:
+   * OBP retrieves the certificate (`TPP-Signature-Certificate`) from the request header.
+   * From this certificate, OBP extracts the TPP's public key.
+2. **Recreates the Signing String**:
+   * OBP analyzes the `Signature` header to identify the signed fields (e.g., `Digest`, `X-Request-ID`, `Date`, etc.).
+   * OBP recreates the signing string from the actual values of these fields in the specified order.
+3. **Decodes the Signature**:
+   * OBP decodes the value in the `Signature.signature` field (the digital signature generated by TPP).
+   * Decoding is done using the public key extracted from the `TPP-Signature-Certificate` and the algorithm specified in `Signature.algorithm` (e.g., RSA-SHA256).
+4. **Compares the Resulting Hash**:
+   * During decoding, OBP obtains a hash calculated by TPP at the time of signing.
+   * OBP compares this hash with the hash generated internally from the recreated signing string.
+5. **Possible Outcomes**:
+   * If the hashes match, the signature is valid.
+   * If the hashes do not match, the signature is invalid, and the request is rejected.